diff --git a/completions/elvish b/completions/elvish index f373240a..48ac72b6 100644 --- a/completions/elvish +++ b/completions/elvish @@ -64,7 +64,7 @@ set edit:completion:arg-completer[watchexec] = {|@words| cand --ignore-nothing 'Don''t ignore anything at all' cand -p 'Wait until first change before running command' cand --postpone 'Wait until first change before running command' - cand -n 'Don''t use a shell' + cand -n 'Shorthand for ''--shell=none''' cand --no-environment 'Deprecated shorthand for ''--emit-events=none''' cand --only-emit-events 'Only emit events to stdout, run no commands' cand --no-process-group 'Don''t use a process group' diff --git a/completions/fish b/completions/fish index b39801cb..aa028380 100644 --- a/completions/fish +++ b/completions/fish @@ -32,7 +32,7 @@ complete -c watchexec -l no-default-ignore -d 'Don\'t use internal default ignor complete -c watchexec -l no-discover-ignore -d 'Don\'t discover ignore files at all' complete -c watchexec -l ignore-nothing -d 'Don\'t ignore anything at all' complete -c watchexec -s p -l postpone -d 'Wait until first change before running command' -complete -c watchexec -s n -d 'Don\'t use a shell' +complete -c watchexec -s n -d 'Shorthand for \'--shell=none\'' complete -c watchexec -l no-environment -d 'Deprecated shorthand for \'--emit-events=none\'' complete -c watchexec -l only-emit-events -d 'Only emit events to stdout, run no commands' complete -c watchexec -l no-process-group -d 'Don\'t use a process group' diff --git a/completions/nu b/completions/nu index 483edadd..583cf71a 100644 --- a/completions/nu +++ b/completions/nu @@ -47,7 +47,7 @@ module completions { --delay-run: string # Sleep before running the command --poll: string # Poll for filesystem changes --shell: string # Use a different shell - -n # Don't use a shell + -n # Shorthand for '--shell=none' --no-environment # Deprecated shorthand for '--emit-events=none' --emit-events-to: string@"nu-complete watchexec emit_events_to" # Configure event emission --only-emit-events # Only emit events to stdout, run no commands diff --git a/completions/powershell b/completions/powershell index 0b80d6e4..d2f86786 100644 --- a/completions/powershell +++ b/completions/powershell @@ -67,7 +67,7 @@ Register-ArgumentCompleter -Native -CommandName 'watchexec' -ScriptBlock { [CompletionResult]::new('--ignore-nothing', 'ignore-nothing', [CompletionResultType]::ParameterName, 'Don''t ignore anything at all') [CompletionResult]::new('-p', 'p', [CompletionResultType]::ParameterName, 'Wait until first change before running command') [CompletionResult]::new('--postpone', 'postpone', [CompletionResultType]::ParameterName, 'Wait until first change before running command') - [CompletionResult]::new('-n', 'n', [CompletionResultType]::ParameterName, 'Don''t use a shell') + [CompletionResult]::new('-n', 'n', [CompletionResultType]::ParameterName, 'Shorthand for ''--shell=none''') [CompletionResult]::new('--no-environment', 'no-environment', [CompletionResultType]::ParameterName, 'Deprecated shorthand for ''--emit-events=none''') [CompletionResult]::new('--only-emit-events', 'only-emit-events', [CompletionResultType]::ParameterName, 'Only emit events to stdout, run no commands') [CompletionResult]::new('--no-process-group', 'no-process-group', [CompletionResultType]::ParameterName, 'Don''t use a process group') diff --git a/completions/zsh b/completions/zsh index 6165bc97..a7ebb082 100644 --- a/completions/zsh +++ b/completions/zsh @@ -61,7 +61,7 @@ _watchexec() { '--ignore-nothing[Don'\''t ignore anything at all]' \ '-p[Wait until first change before running command]' \ '--postpone[Wait until first change before running command]' \ -'-n[Don'\''t use a shell]' \ +'-n[Shorthand for '\''--shell=none'\'']' \ '--no-environment[Deprecated shorthand for '\''--emit-events=none'\'']' \ '(--completions --manual)--only-emit-events[Only emit events to stdout, run no commands]' \ '--no-process-group[Don'\''t use a process group]' \ diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs index 3422de47..1960267c 100644 --- a/crates/cli/src/args.rs +++ b/crates/cli/src/args.rs @@ -979,10 +979,8 @@ pub struct Args { pub enum EmitEvents { #[default] Environment, - #[value(alias("stdin"))] Stdio, File, - #[value(alias("json-stdin"))] JsonStdio, JsonFile, None, diff --git a/doc/watchexec.1 b/doc/watchexec.1 index 95123b47..2bb507ef 100644 --- a/doc/watchexec.1 +++ b/doc/watchexec.1 @@ -248,15 +248,13 @@ Use with a unix shell and options: $ watchexec \-\-shell=\*(Aqzsh \-x \-o shwordsplit\*(Aq \-\- scr .TP \fB\-n\fR -Don\*(Aqt use a shell - -This is a shorthand for \*(Aq\-\-shell=none\*(Aq. +Shorthand for \*(Aq\-\-shell=none\*(Aq .TP \fB\-\-emit\-events\-to\fR=\fIMODE\fR Configure event emission -Watchexec emits event information when running a command, which can be used by the command -to target specific changed files. +Watchexec can emit event information when running a command, which can be used by the child +process to target specific changed files. One thing to take care with is assuming inherent behaviour where there is only chance. Notably, it could appear as if the `RENAMED` variable contains both the original and the new @@ -267,32 +265,14 @@ reliably and portably know which changed path is the old or new, "half" renames whether it was the old or new isn\*(Aqt known), rename events might split across two debouncing boundaries, and so on. -This option controls where that information is emitted. It defaults to \*(Aqenvironment\*(Aq, which -sets environment variables with the paths of the affected files, for filesystem events: +This option controls where that information is emitted. It defaults to \*(Aqnone\*(Aq, which doesn\*(Aqt +emit event information at all. The other options are \*(Aqenvironment\*(Aq (deprecated), \*(Aqstdio\*(Aq, +\*(Aqfile\*(Aq, \*(Aqjson\-stdio\*(Aq, and \*(Aqjson\-file\*(Aq. -$WATCHEXEC_COMMON_PATH is set to the longest common path of all of the below variables, -and so should be prepended to each path to obtain the full/real path. Then: - - \- $WATCHEXEC_CREATED_PATH is set when files/folders were created - \- $WATCHEXEC_REMOVED_PATH is set when files/folders were removed - \- $WATCHEXEC_RENAMED_PATH is set when files/folders were renamed - \- $WATCHEXEC_WRITTEN_PATH is set when files/folders were modified - \- $WATCHEXEC_META_CHANGED_PATH is set when files/folders\*(Aq metadata were modified - \- $WATCHEXEC_OTHERWISE_CHANGED_PATH is set for every other kind of pathed event - -Multiple paths are separated by the system path separator, \*(Aq;\*(Aq on Windows and \*(Aq:\*(Aq on unix. -Within each variable, paths are deduplicated and sorted in binary order (i.e. neither -Unicode nor locale aware). - -This is the legacy mode and will be deprecated and removed in the future. The environment of -a process is a very restricted space, while also limited in what it can usefully represent. -Large numbers of files will either cause the environment to be truncated, or may error or -crash the process entirely. - -Two new modes are available: \*(Aqstdio\*(Aq writes absolute paths to the stdin of the command, -one per line, each prefixed with `create:`, `remove:`, `rename:`, `modify:`, or `other:`, -then closes the handle; \*(Aqfile\*(Aq writes the same thing to a temporary file, and its path is -given with the $WATCHEXEC_EVENTS_FILE environment variable. +The \*(Aqstdio\*(Aq and \*(Aqfile\*(Aq modes are text\-based: \*(Aqstdio\*(Aq writes absolute paths to the stdin of +the command, one per line, each prefixed with `create:`, `remove:`, `rename:`, `modify:`, +or `other:`, then closes the handle; \*(Aqfile\*(Aq writes the same thing to a temporary file, and +its path is given with the $WATCHEXEC_EVENTS_FILE environment variable. There are also two JSON modes, which are based on JSON objects and can represent the full set of events Watchexec handles. Here\*(Aqs an example of a folder being created on Linux: @@ -349,7 +329,28 @@ line, then close stdin. The \*(Aqjson\-file\*(Aq mode will create a temporary fi events to it, and provide the path to the file with the $WATCHEXEC_EVENTS_FILE environment variable. -Finally, the special \*(Aqnone\*(Aq mode will disable event emission entirely. +Finally, the \*(Aqenvironment\*(Aq mode was the default until 2.0. It sets environment variables +with the paths of the affected files, for filesystem events: + +$WATCHEXEC_COMMON_PATH is set to the longest common path of all of the below variables, +and so should be prepended to each path to obtain the full/real path. Then: + + \- $WATCHEXEC_CREATED_PATH is set when files/folders were created + \- $WATCHEXEC_REMOVED_PATH is set when files/folders were removed + \- $WATCHEXEC_RENAMED_PATH is set when files/folders were renamed + \- $WATCHEXEC_WRITTEN_PATH is set when files/folders were modified + \- $WATCHEXEC_META_CHANGED_PATH is set when files/folders\*(Aq metadata were modified + \- $WATCHEXEC_OTHERWISE_CHANGED_PATH is set for every other kind of pathed event + +Multiple paths are separated by the system path separator, \*(Aq;\*(Aq on Windows and \*(Aq:\*(Aq on unix. +Within each variable, paths are deduplicated and sorted in binary order (i.e. neither +Unicode nor locale aware). + +This is the legacy mode, is deprecated, and will be removed in the future. The environment +is a very restricted space, while also limited in what it can usefully represent. Large +numbers of files will either cause the environment to be truncated, or may error or crash +the process entirely. The $WATCHEXEC_COMMON_PATH is also unintuitive, as demonstrated by the +multiple confused queries that have landed in my inbox over the years. .TP \fB\-\-only\-emit\-events\fR Only emit events to stdout, run no commands. diff --git a/doc/watchexec.1.md b/doc/watchexec.1.md index 7ea6fc2d..4d6030a8 100644 --- a/doc/watchexec.1.md +++ b/doc/watchexec.1.md @@ -391,16 +391,14 @@ Use with a unix shell and options: **-n** -: Dont use a shell - -This is a shorthand for \--shell=none. +: Shorthand for \--shell=none **\--emit-events-to**=*MODE* : Configure event emission -Watchexec emits event information when running a command, which can be -used by the command to target specific changed files. +Watchexec can emit event information when running a command, which can +be used by the child process to target specific changed files. One thing to take care with is assuming inherent behaviour where there is only chance. Notably, it could appear as if the \`RENAMED\` variable @@ -414,36 +412,14 @@ the old or new isnt known), rename events might split across two debouncing boundaries, and so on. This option controls where that information is emitted. It defaults to -environment, which sets environment variables with the paths of the -affected files, for filesystem events: +none, which doesnt emit event information at all. The other options are +environment (deprecated), stdio, file, json-stdio, and json-file. -\$WATCHEXEC_COMMON_PATH is set to the longest common path of all of the -below variables, and so should be prepended to each path to obtain the -full/real path. Then: - -\- \$WATCHEXEC_CREATED_PATH is set when files/folders were created - -\$WATCHEXEC_REMOVED_PATH is set when files/folders were removed - -\$WATCHEXEC_RENAMED_PATH is set when files/folders were renamed - -\$WATCHEXEC_WRITTEN_PATH is set when files/folders were modified - -\$WATCHEXEC_META_CHANGED_PATH is set when files/folders metadata were -modified - \$WATCHEXEC_OTHERWISE_CHANGED_PATH is set for every other -kind of pathed event - -Multiple paths are separated by the system path separator, ; on Windows -and : on unix. Within each variable, paths are deduplicated and sorted -in binary order (i.e. neither Unicode nor locale aware). - -This is the legacy mode and will be deprecated and removed in the -future. The environment of a process is a very restricted space, while -also limited in what it can usefully represent. Large numbers of files -will either cause the environment to be truncated, or may error or crash -the process entirely. - -Two new modes are available: stdio writes absolute paths to the stdin of -the command, one per line, each prefixed with \`create:\`, \`remove:\`, -\`rename:\`, \`modify:\`, or \`other:\`, then closes the handle; file -writes the same thing to a temporary file, and its path is given with -the \$WATCHEXEC_EVENTS_FILE environment variable. +The stdio and file modes are text-based: stdio writes absolute paths to +the stdin of the command, one per line, each prefixed with \`create:\`, +\`remove:\`, \`rename:\`, \`modify:\`, or \`other:\`, then closes the +handle; file writes the same thing to a temporary file, and its path is +given with the \$WATCHEXEC_EVENTS_FILE environment variable. There are also two JSON modes, which are based on JSON objects and can represent the full set of events Watchexec handles. Heres an example of @@ -478,7 +454,33 @@ command, one per line, then close stdin. The json-file mode will create a temporary file, write the events to it, and provide the path to the file with the \$WATCHEXEC_EVENTS_FILE environment variable. -Finally, the special none mode will disable event emission entirely. +Finally, the environment mode was the default until 2.0. It sets +environment variables with the paths of the affected files, for +filesystem events: + +\$WATCHEXEC_COMMON_PATH is set to the longest common path of all of the +below variables, and so should be prepended to each path to obtain the +full/real path. Then: + +\- \$WATCHEXEC_CREATED_PATH is set when files/folders were created - +\$WATCHEXEC_REMOVED_PATH is set when files/folders were removed - +\$WATCHEXEC_RENAMED_PATH is set when files/folders were renamed - +\$WATCHEXEC_WRITTEN_PATH is set when files/folders were modified - +\$WATCHEXEC_META_CHANGED_PATH is set when files/folders metadata were +modified - \$WATCHEXEC_OTHERWISE_CHANGED_PATH is set for every other +kind of pathed event + +Multiple paths are separated by the system path separator, ; on Windows +and : on unix. Within each variable, paths are deduplicated and sorted +in binary order (i.e. neither Unicode nor locale aware). + +This is the legacy mode, is deprecated, and will be removed in the +future. The environment is a very restricted space, while also limited +in what it can usefully represent. Large numbers of files will either +cause the environment to be truncated, or may error or crash the process +entirely. The \$WATCHEXEC_COMMON_PATH is also unintuitive, as +demonstrated by the multiple confused queries that have landed in my +inbox over the years. **\--only-emit-events**