diff --git a/completions/elvish b/completions/elvish index feffd1e7..f373240a 100644 --- a/completions/elvish +++ b/completions/elvish @@ -65,7 +65,7 @@ set edit:completion:arg-completer[watchexec] = {|@words| 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 --no-environment 'Shorthand for ''--emit-events=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' cand -1 'Testing only: exit Watchexec after the first run' diff --git a/completions/fish b/completions/fish index 3a6a01fa..b39801cb 100644 --- a/completions/fish +++ b/completions/fish @@ -33,7 +33,7 @@ complete -c watchexec -l no-discover-ignore -d 'Don\'t discover ignore files at 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 -l no-environment -d 'Shorthand for \'--emit-events=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' complete -c watchexec -s 1 -d 'Testing only: exit Watchexec after the first run' diff --git a/completions/nu b/completions/nu index 67444385..483edadd 100644 --- a/completions/nu +++ b/completions/nu @@ -48,7 +48,7 @@ module completions { --poll: string # Poll for filesystem changes --shell: string # Use a different shell -n # Don't use a shell - --no-environment # Shorthand for '--emit-events=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 --env(-E): string # Add env vars to the command diff --git a/completions/powershell b/completions/powershell index 553cd03e..0b80d6e4 100644 --- a/completions/powershell +++ b/completions/powershell @@ -68,7 +68,7 @@ Register-ArgumentCompleter -Native -CommandName 'watchexec' -ScriptBlock { [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('--no-environment', 'no-environment', [CompletionResultType]::ParameterName, 'Shorthand for ''--emit-events=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') [CompletionResult]::new('-1', '1', [CompletionResultType]::ParameterName, 'Testing only: exit Watchexec after the first run') diff --git a/completions/zsh b/completions/zsh index 1afdc507..6165bc97 100644 --- a/completions/zsh +++ b/completions/zsh @@ -62,7 +62,7 @@ _watchexec() { '-p[Wait until first change before running command]' \ '--postpone[Wait until first change before running command]' \ '-n[Don'\''t use a shell]' \ -'--no-environment[Shorthand for '\''--emit-events=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]' \ '-1[Testing only\: exit Watchexec after the first run]' \ diff --git a/crates/cli/README.md b/crates/cli/README.md index 41dd1f75..4c689e35 100644 --- a/crates/cli/README.md +++ b/crates/cli/README.md @@ -37,7 +37,7 @@ Example use cases: These variables may contain multiple paths: these are separated by the platform's path separator, as with the `PATH` system environment variable. On Unix that is `:`, and on Windows `;`. Within each variable, paths are deduplicated and sorted in binary order (i.e. neither Unicode nor locale aware). - This can be disabled or limited with `--no-environment` (doesn't set any of these variables) and `--no-meta` (ignores metadata changes). + This can be disabled with `--emit-events=none` or changed to JSON events on STDIN with `--emit-events=json-stdio`. ## Anti-Features diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs index a9500aad..bfb667cf 100644 --- a/crates/cli/src/args.rs +++ b/crates/cli/src/args.rs @@ -468,30 +468,28 @@ pub struct Args { )] pub shell: Option, - /// Don't use a shell - /// - /// This is a shorthand for '--shell=none'. + /// Shorthand for '--shell=none' #[arg( short = 'n', help_heading = OPTSET_COMMAND, )] pub no_shell: bool, - /// Shorthand for '--emit-events=none' + /// Deprecated shorthand for '--emit-events=none' /// /// This is the old way to disable event emission into the environment. See '--emit-events' for - /// more. + /// more. Will be removed at next major release. #[arg( long, help_heading = OPTSET_COMMAND, - // TODO: deprecate then remove + hide = true, // deprecated )] pub no_environment: bool, /// 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 @@ -502,32 +500,14 @@ pub struct Args { /// whether it was the old or new isn't 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: + /// This option controls where that information is emitted. It defaults to 'none', which doesn't + /// 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. Here's an example of a folder being created on Linux: @@ -584,13 +564,33 @@ pub struct Args { /// 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. - // TODO: when deprecating, make the none mode the default. + /// 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. #[arg( long, help_heading = OPTSET_COMMAND, verbatim_doc_comment, - default_value = "environment", + default_value = "none", hide_default_value = true, value_name = "MODE", required_if_eq("only_emit_events", "true"), diff --git a/doc/watchexec.1 b/doc/watchexec.1 index e7278ad8..95123b47 100644 --- a/doc/watchexec.1 +++ b/doc/watchexec.1 @@ -4,7 +4,7 @@ .SH NAME watchexec \- Execute commands when watched files change .SH SYNOPSIS -\fBwatchexec\fR [\fB\-w\fR|\fB\-\-watch\fR] [\fB\-c\fR|\fB\-\-clear\fR] [\fB\-o\fR|\fB\-\-on\-busy\-update\fR] [\fB\-r\fR|\fB\-\-restart\fR] [\fB\-s\fR|\fB\-\-signal\fR] [\fB\-\-stop\-signal\fR] [\fB\-\-stop\-timeout\fR] [\fB\-\-map\-signal\fR] [\fB\-d\fR|\fB\-\-debounce\fR] [\fB\-\-stdin\-quit\fR] [\fB\-\-no\-vcs\-ignore\fR] [\fB\-\-no\-project\-ignore\fR] [\fB\-\-no\-global\-ignore\fR] [\fB\-\-no\-default\-ignore\fR] [\fB\-\-no\-discover\-ignore\fR] [\fB\-\-ignore\-nothing\fR] [\fB\-p\fR|\fB\-\-postpone\fR] [\fB\-\-delay\-run\fR] [\fB\-\-poll\fR] [\fB\-\-shell\fR] [\fB\-n \fR] [\fB\-\-no\-environment\fR] [\fB\-\-emit\-events\-to\fR] [\fB\-\-only\-emit\-events\fR] [\fB\-E\fR|\fB\-\-env\fR] [\fB\-\-no\-process\-group\fR] [\fB\-N\fR|\fB\-\-notify\fR] [\fB\-\-color\fR] [\fB\-\-timings\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-bell\fR] [\fB\-\-project\-origin\fR] [\fB\-\-workdir\fR] [\fB\-e\fR|\fB\-\-exts\fR] [\fB\-f\fR|\fB\-\-filter\fR] [\fB\-\-filter\-file\fR] [\fB\-j\fR|\fB\-\-filter\-prog\fR] [\fB\-i\fR|\fB\-\-ignore\fR] [\fB\-\-ignore\-file\fR] [\fB\-\-fs\-events\fR] [\fB\-\-no\-meta\fR] [\fB\-\-print\-events\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-log\-file\fR] [\fB\-\-manual\fR] [\fB\-\-completions\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICOMMAND\fR] +\fBwatchexec\fR [\fB\-w\fR|\fB\-\-watch\fR] [\fB\-c\fR|\fB\-\-clear\fR] [\fB\-o\fR|\fB\-\-on\-busy\-update\fR] [\fB\-r\fR|\fB\-\-restart\fR] [\fB\-s\fR|\fB\-\-signal\fR] [\fB\-\-stop\-signal\fR] [\fB\-\-stop\-timeout\fR] [\fB\-\-map\-signal\fR] [\fB\-d\fR|\fB\-\-debounce\fR] [\fB\-\-stdin\-quit\fR] [\fB\-\-no\-vcs\-ignore\fR] [\fB\-\-no\-project\-ignore\fR] [\fB\-\-no\-global\-ignore\fR] [\fB\-\-no\-default\-ignore\fR] [\fB\-\-no\-discover\-ignore\fR] [\fB\-\-ignore\-nothing\fR] [\fB\-p\fR|\fB\-\-postpone\fR] [\fB\-\-delay\-run\fR] [\fB\-\-poll\fR] [\fB\-\-shell\fR] [\fB\-n \fR] [\fB\-\-emit\-events\-to\fR] [\fB\-\-only\-emit\-events\fR] [\fB\-E\fR|\fB\-\-env\fR] [\fB\-\-no\-process\-group\fR] [\fB\-N\fR|\fB\-\-notify\fR] [\fB\-\-color\fR] [\fB\-\-timings\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-bell\fR] [\fB\-\-project\-origin\fR] [\fB\-\-workdir\fR] [\fB\-e\fR|\fB\-\-exts\fR] [\fB\-f\fR|\fB\-\-filter\fR] [\fB\-\-filter\-file\fR] [\fB\-j\fR|\fB\-\-filter\-prog\fR] [\fB\-i\fR|\fB\-\-ignore\fR] [\fB\-\-ignore\-file\fR] [\fB\-\-fs\-events\fR] [\fB\-\-no\-meta\fR] [\fB\-\-print\-events\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-log\-file\fR] [\fB\-\-manual\fR] [\fB\-\-completions\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICOMMAND\fR] .SH DESCRIPTION Execute commands when watched files change. .PP @@ -252,11 +252,6 @@ Don\*(Aqt use a shell This is a shorthand for \*(Aq\-\-shell=none\*(Aq. .TP -\fB\-\-no\-environment\fR -Shorthand for \*(Aq\-\-emit\-events=none\*(Aq - -This is the old way to disable event emission into the environment. See \*(Aq\-\-emit\-events\*(Aq for more. -.TP \fB\-\-emit\-events\-to\fR=\fIMODE\fR Configure event emission diff --git a/doc/watchexec.1.md b/doc/watchexec.1.md index 0f3dec82..7ea6fc2d 100644 --- a/doc/watchexec.1.md +++ b/doc/watchexec.1.md @@ -12,18 +12,17 @@ watchexec - Execute commands when watched files change \[**\--no-global-ignore**\] \[**\--no-default-ignore**\] \[**\--no-discover-ignore**\] \[**\--ignore-nothing**\] \[**-p**\|**\--postpone**\] \[**\--delay-run**\] \[**\--poll**\] -\[**\--shell**\] \[**-n **\] \[**\--no-environment**\] -\[**\--emit-events-to**\] \[**\--only-emit-events**\] -\[**-E**\|**\--env**\] \[**\--no-process-group**\] -\[**-N**\|**\--notify**\] \[**\--color**\] \[**\--timings**\] -\[**-q**\|**\--quiet**\] \[**\--bell**\] \[**\--project-origin**\] -\[**\--workdir**\] \[**-e**\|**\--exts**\] \[**-f**\|**\--filter**\] -\[**\--filter-file**\] \[**-j**\|**\--filter-prog**\] -\[**-i**\|**\--ignore**\] \[**\--ignore-file**\] \[**\--fs-events**\] -\[**\--no-meta**\] \[**\--print-events**\] -\[**-v**\|**\--verbose**\]\... \[**\--log-file**\] \[**\--manual**\] -\[**\--completions**\] \[**-h**\|**\--help**\] -\[**-V**\|**\--version**\] \[*COMMAND*\] +\[**\--shell**\] \[**-n **\] \[**\--emit-events-to**\] +\[**\--only-emit-events**\] \[**-E**\|**\--env**\] +\[**\--no-process-group**\] \[**-N**\|**\--notify**\] \[**\--color**\] +\[**\--timings**\] \[**-q**\|**\--quiet**\] \[**\--bell**\] +\[**\--project-origin**\] \[**\--workdir**\] \[**-e**\|**\--exts**\] +\[**-f**\|**\--filter**\] \[**\--filter-file**\] +\[**-j**\|**\--filter-prog**\] \[**-i**\|**\--ignore**\] +\[**\--ignore-file**\] \[**\--fs-events**\] \[**\--no-meta**\] +\[**\--print-events**\] \[**-v**\|**\--verbose**\]\... +\[**\--log-file**\] \[**\--manual**\] \[**\--completions**\] +\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \[*COMMAND*\] # DESCRIPTION @@ -396,13 +395,6 @@ Use with a unix shell and options: This is a shorthand for \--shell=none. -**\--no-environment** - -: Shorthand for \--emit-events=none - -This is the old way to disable event emission into the environment. See -\--emit-events for more. - **\--emit-events-to**=*MODE* : Configure event emission