Add --log-file so logs are easier to collect (#321)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,7 +11,7 @@ Please delete this template text before filing, but you _need_ to include the fo
 
 - Watchexec's version
 - The OS you're using
-- A log with `-vvv` (if it has sensitive info you can email it at felix@passcod.name — do that _after_ filing so you can reference the issue ID)
+- A log with `-vvv --log-file ../watchexec.log` (if it has sensitive info you can email it at felix@passcod.name — do that _after_ filing so you can reference the issue ID)
 - A sample command that you've run that has the issue
 
 Thank you

.github/ISSUE_TEMPLATE/regression.md

@@ -15,7 +15,7 @@ assignees: ''
 - Latest version that worked:
 - Earliest version that doesn't: (don't sweat testing earlier versions if you don't remember or have time, your current version will do)
 - OS:
-- A debug log with `-vvv`:
+- A debug log with `-vvv --log-file ../watchexec.log`:
 
 ```
 ```

Cargo.lock

@@ -2438,6 +2438,16 @@ dependencies = [
  "tracing-core",
 ]
 
+[[package]]
+name = "tracing-serde"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc6b213177105856957181934e4920de57730fc69bf42c37ee5bb664d406d9e1"
+dependencies = [
+ "serde",
+ "tracing-core",
+]
+
 [[package]]
 name = "tracing-subscriber"
 version = "0.3.11"
@@ -2448,12 +2458,15 @@ dependencies = [
  "lazy_static",
  "matchers",
  "regex",
+ "serde",
+ "serde_json",
  "sharded-slab",
  "smallvec",
  "thread_local",
  "tracing",
  "tracing-core",
  "tracing-log",
+ "tracing-serde",
 ]
 
 [[package]]

completions/zsh

@@ -20,6 +20,7 @@ args=(
 	'(-W --watch-when-idle)'{-W,--watch-when-idle}'[Ignore events while the command is still running]'
 	'(-V --version)'{-V,--version}'[Prints version information]'
 	'(-v --verbose)'{-v,-vv,-vvv,-vvvv,--verbose}'[Print debugging messages to stderr]'
+	'--log-file=[Output logs to a file, in JSON format]:path:_path_files -/'
 	'(-N --notify)'{-N,--notify}'[Send desktop notifications on command start and end]'
 	'--print-events[Print triggering events to stderr (changed paths, etc)]'
 	'(-d --debounce)'{-d+,--debounce=}'[Set the timeout between detected change and command execution, defaults to 100ms]:milliseconds'

crates/cli/Cargo.toml

@@ -71,6 +71,7 @@ version = "0.3.6"
 features = [
 	"env-filter",
 	"fmt",
+	"json",
 ]
 
 [target.'cfg(target_env = "musl")'.dependencies]

crates/cli/src/args.rs

@@ -75,6 +75,12 @@ pub fn get_args(tagged_filterer: bool) -> Result<ArgMatches> {
 			.multiple_occurrences(true)
 			.short('v')
 			.long("verbose"))
+		.arg(Arg::new("log-file")
+			.help_heading(Some(OPTSET_DEBUGGING))
+			.help("Write debugging messages to file in JSON format (use for bug reports)")
+			.long("log-file")
+			.takes_value(true)
+			.value_name("path"))
 		.arg(Arg::new("print-events")
 			.help_heading(Some(OPTSET_DEBUGGING))
 			.help("Print events that trigger actions")

crates/cli/src/main.rs

@@ -1,6 +1,6 @@
 #![deny(rust_2018_idioms)]
 
-use std::env::var;
+use std::{fs::File, sync::Mutex, env::var};
 
 use miette::{IntoDiagnostic, Result};
 use tracing::debug;
@@ -37,6 +37,10 @@ async fn main() -> Result<()> {
 
 	{
 		let verbosity = args.occurrences_of("verbose");
+		let log_file = if let Some(file) = args.value_of("log-file") {
+			Some(File::create(file).into_diagnostic()?)
+		} else { None };
+
 		let mut builder = tracing_subscriber::fmt().with_env_filter(match verbosity {
 			0 => "watchexec-cli=warn",
 			1 => "watchexec=debug,watchexec-cli=debug",
@@ -49,7 +53,9 @@ async fn main() -> Result<()> {
 			builder = builder.with_span_events(FmtSpan::NEW | FmtSpan::CLOSE);
 		}
 
-		if verbosity > 3 {
+		if let Some(writer) = log_file {
+			builder.json().with_writer(Mutex::new(writer)).try_init().ok();
+		} else if verbosity > 3 {
 			builder.pretty().try_init().ok();
 		} else {
 			builder.try_init().ok();

crates/cli/tests/snapshots/help__help_unix.snap

@@ -1,6 +1,5 @@
 ---
-source: cli/tests/help.rs
-assertion_line: 16
+source: crates/cli/tests/help.rs
 expression: "String::from_utf8(output.stdout).unwrap()"
 ---
 watchexec 1.19.0
@@ -64,8 +63,10 @@ Behaviour options:
             Specify the signal to send when using --on-busy-update=signal
 
 Debugging options:
-        --print-events    Print events that trigger actions
-    -v, --verbose         Print debugging messages (-v, -vv, -vvv, -vvvv; use -vvv for bug reports)
+        --log-file <path>    Write debugging messages to file in JSON format (use for bug reports)
+        --print-events       Print events that trigger actions
+    -v, --verbose            Print debugging messages (-v, -vv, -vvv, -vvvv; use -vvv for bug
+                             reports)
 
 Use @argfile as first argument to load arguments from the file `argfile` (one argument per line)
 which will be inserted in place of the @argfile (further arguments on the CLI will override or add

crates/cli/tests/snapshots/help__help_windows.snap

@@ -64,8 +64,10 @@ Behaviour options:
             Specify the signal to send when using --on-busy-update=signal
 
 Debugging options:
-        --print-events    Print events that trigger actions
-    -v, --verbose         Print debugging messages (-v, -vv, -vvv, -vvvv; use -vvv for bug reports)
+        --log-file <path>    Write debugging messages to file in JSON format (use for bug reports)
+        --print-events       Print events that trigger actions
+    -v, --verbose            Print debugging messages (-v, -vv, -vvv, -vvvv; use -vvv for bug
+                             reports)
 
 Use @argfile as first argument to load arguments from the file `argfile` (one argument per line)
 which will be inserted in place of the @argfile (further arguments on the CLI will override or add

crates/filterer/globset/src/lib.rs

@@ -5,7 +5,7 @@
 
 use std::{
 	ffi::OsString,
-	path::{Path, PathBuf, MAIN_SEPARATOR},
+	path::{Path, PathBuf},
 };
 
 use ignore::gitignore::{Gitignore, GitignoreBuilder};
@@ -150,6 +150,7 @@ impl Filterer for GlobsetFilterer {
 					#[cfg(unix)]
 					if let Ok(based) = path.strip_prefix(&self.origin) {
 						let rebased = {
+							use std::path::MAIN_SEPARATOR;
 							let mut b = self.origin.clone().into_os_string();
 							b.push(PathBuf::from(String::from(MAIN_SEPARATOR)));
 							b.push(PathBuf::from(String::from(MAIN_SEPARATOR)));

doc/watchexec.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "WATCHEXEC" "1" "April 2022" "" ""
+.TH "WATCHEXEC" "1" "June 2022" "" ""
 .
 .SH "NAME"
 \fBwatchexec\fR \- execute commands when watched files change
@@ -164,6 +164,10 @@ Prints the events (changed paths, etc) that have triggered an action to STDERR\.
 Prints diagnostic and debugging messages to STDERR\. Increase the amount of \fBv\fRs to get progressively more output: for bug reports use \fBthree\fR, and for deep debugging \fBfour\fR can be helpful\.
 .
 .TP
+\fB\-\-log\-file\fR \fIpath\fR
+Writes diagnostic and debugging messages (from the \fB\-v\fR options) to file instead of STDERR, in JSON format\. This is preferrable for reporting bugs\. Be careful \fBnot\fR to write to a file within the purview of Watchexec to avoid recursion!
+.
+.TP
 \fB\-V\fR, \fB\-\-version\fR
 Print the version of watchexec\.
 .

doc/watchexec.1.html

@@ -177,6 +177,7 @@ watchexec [-h|--help]</p>
 <dl>
 <dt><code>--print-events</code>, <code>--changes-only</code> (deprecated alias)</dt><dd><p>Prints the events (changed paths, etc) that have triggered an action to STDERR.</p></dd>
 <dt><code>-v</code>, <code>--verbose</code>, <code>-vv</code>, etc</dt><dd><p>Prints diagnostic and debugging messages to STDERR. Increase the amount of <code>v</code>s to get progressively more output: for bug reports use <strong>three</strong>, and for deep debugging <strong>four</strong> can be helpful.</p></dd>
+<dt><code>--log-file</code> <var>path</var></dt><dd><p>Writes diagnostic and debugging messages (from the <code>-v</code> options) to file instead of STDERR, in JSON format. This is preferrable for reporting bugs. Be careful <strong>not</strong> to write to a file within the purview of Watchexec to avoid recursion!</p></dd>
 <dt><code>-V</code>, <code>--version</code></dt><dd><p>Print the version of watchexec.</p></dd>
 <dt><code>-h</code>, <code>--help</code></dt><dd><p>Print a help message.</p></dd>
 </dl>
@@ -315,7 +316,7 @@ watchexec [-h|--help]</p>
 
   <ol class='man-decor man-foot man foot'>
     <li class='tl'></li>
-    <li class='tc'>April 2022</li>
+    <li class='tc'>June 2022</li>
     <li class='tr'>watchexec(1)</li>
   </ol>
 

doc/watchexec.1.ronn

@@ -125,6 +125,9 @@ Prints the events (changed paths, etc) that have triggered an action to STDERR.
 * `-v`, `--verbose`, `-vv`, etc:
 Prints diagnostic and debugging messages to STDERR. Increase the amount of `v`s to get progressively more output: for bug reports use **three**, and for deep debugging **four** can be helpful.
 
+* `--log-file` <path>:
+Writes diagnostic and debugging messages (from the `-v` options) to file instead of STDERR, in JSON format. This is preferrable for reporting bugs. Be careful **not** to write to a file within the purview of Watchexec to avoid recursion!
+
 * `-V`, `--version`:
 Print the version of watchexec.