mirror of
https://github.com/watchexec/watchexec.git
synced 2024-11-16 17:18:30 +01:00
Deprecate --no-environment and --emit-events-to=environment
This commit is contained in:
Félix Saparelli
parent
4acec80f43
commit
ee3c7f682e
9 changed files with 54 additions and 67 deletions
|
|
@ -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'
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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')
|
||||
|
|
|
|||
|
|
@ -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]' \
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -468,30 +468,28 @@ pub struct Args {
|
|||
)]
|
||||
pub shell: Option<String>,
|
||||
|
||||
/// 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"),
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue