watchexec/doc/watchexec.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "WATCHEXEC" "1" "April 2022" "" ""
.
.SH "NAME"
\fBwatchexec\fR \- execute commands when watched files change
.
.SH "SYNOPSIS"
watchexec [\fB\-\-exts\fR | \fB\-e\fR \fIextensions\fR]\.\.\. [\fB\-\-filter\fR | \fB\-f\fR \fIpattern\fR]\.\.\. [\fB\-\-ignore\fR | \fB\-i\fR \fIpattern\fR]\.\.\. [\fB\-\-watch\fR | \fB\-w\fR \fIpath\fR]\.\.\. [\fB\-\-restart\fR | \fB\-r\fR] [\fB\-\-clear\fR | \fB\-c\fR] [\fB\-\-postpone\fR | \fB\-p\fR] [\fB\-\-force\-poll\fR \fIinterval\fR] [\fB\-\-debounce\fR | \fB\-d\fR \fIinterval\fR] [\fB\-\-no\-vcs\-ignore\fR] [\fB\-\-no\-default\-ignore\fR] [\fB\-\-verbose\fR | \fB\-v\fR | \fB\-vv\fR | \fB\-vvv\fR | \fB\-vvvv\fR] [\fB\-\-changes\-only\fR] [\fB\-\-version\fR | \fB\-V\fR] [\-\-] \fIcommand\fR [\fIargument\fR\.\.\.]
.
.SH "DESCRIPTION"
Recursively monitors the current directory for changes, executing the command when a filesystem change is detected\. By default, watchexec uses efficient kernel\-level mechanisms to watch for changes\.
.
.P
At startup, the specified \fIcommand\fR (passing any supplied \fIargument\fRs) is run once, and watchexec begins monitoring for changes\.
.
.SH "OPTIONS"
.
.TP
\fIcommand\fR
Command to run when watched files are modified, and at startup, unless \fB\-\-postpone\fR is specified\. All \fIargument\fRs are passed to \fIcommand\fR\. If you pass flags to the command, you should separate it with \fB\-\-\fR, for example: \fBwatchexec \-w src \-\- rsync \-a src dest\fR\.
.
.P
Behaviour depends on the value of \fB\-\-shell\fR: for all except \fBnone\fR, every part of \fIcommand\fR is joined together into one string with a single ascii space character, and given to the shell as described\. For \fBnone\fR, each distinct element of \fIcommand\fR is passed as per the execvp(3) convention: first argument is the program, as a file or searched in the \fBPATH\fR, rest are arguments\.
.
.TP
\fB\-e\fR, \fB\-\-exts\fR \fIextensions\fR
Comma\-separated list of file extensions to filter by\. Leading dots (\.rs) are allowed\. (This is a shorthand for \fB\-f\fR)\.
.
.TP
\fB\-f\fR, \fB\-\-filter\fR \fIpattern\fR
Ignores modifications from paths that do not match \fIpattern\fR\. This option can be specified multiple times, where a match on any given pattern causes the path to trigger \fIcommand\fR\.
.
.TP
\fB\-s\fR, \fB\-\-signal\fR
Sends the specified signal (e\.g\. \fBSIGKILL\fR) to the command\. Defaults to \fBSIGTERM\fR\.
.
.TP
\fB\-\-shell\fR \fIshell\fR
Change the shell used to run the command\. Set to \fBnone\fR to run the command directly without a shell\.
.
.P
The special value \fBpowershell\fR will use Microsoft Powershell\'s calling convention, otherwise \fBSHELL \-c COMMAND\fR\.
.
.P
On Windows, the additional \fBcmd\fR special value uses CMD\.EXE calling convention\.
.
.P
The \fBnone\fR value is especially useful in combination with \fB\-\-signal\fR, as the signal is then sent directly to the running command\. While \fB\-\-shell=none\fR is a little more performant than the default, it prevents using shell\-features like pipes and redirects\.
.
.P
If not a special value, the string provided may contain arguments to the shell as long as that is kept simple: the string is split along whitespace, and used as per execvp(3): first is shell program, rest are arguments to the shell, then \fB\-c\fR is added, and finally the \fBCOMMAND\fR\.
.
.P
See the \fIEXAMPLES\fR for uses of each of these\.
.
.TP
\fB\-\-no\-shell\fR
Deprecated\. Alias for \fB\-\-shell=none\fR\.
.
.TP
\fB\-n\fR
Shorthand for \fB\-\-shell=none\fR\.
.
.TP
\fB\-\-no\-meta\fR
Ignore metadata changes\.
.
.TP
\fB\-\-no\-environment\fR
Do not set WATCHEXEC\fI*\fRPATH environment variables for the command\.
.
.TP
\fB\-i\fR, \fB\-\-ignore\fR \fIpattern\fR
Ignores modifications from paths that match \fIpattern\fR\. This option can be specified multiple times, and a match on any pattern causes the path to be ignored\.
.
.TP
\fB\-w\fR, \fB\-\-watch\fR \fIpath\fR
Monitor a specific path for changes\. By default, the current working directory is watched\. This may be specified multiple times, where a change in any watched directory (and subdirectories) causes \fIcommand\fR to be executed\.
.
.TP
\fB\-r\fR, \fB\-\-restart\fR
Terminates the command if it is still running when subsequent file modifications are detected\. By default, sends \fBSIGTERM\fR; use \fB\-\-signal\fR to change that\.
.
.TP
\fB\-W\fR, \fB\-\-watch\-when\-idle\fR
Ignore events while the process is still running\. This is distinct from \fB\-\-restart\fR in that with this option, events received while the command is running will not trigger a new run immediately after the current command is done\.
.
.P
This behaviour will become the default in v2\.0\.
.
.TP
\fB\-\-no\-process\-group\fR
Do not use a process group when running \fIcommand\fR\.
.
.TP
\fB\-c\fR, \fB\-\-clear\fR
Clears the screen before executing \fIcommand\fR\.
.
.TP
\fB\-p\fR, \fB\-\-postpone\fR
Postpone execution of \fIcommand\fR until the first file modification is detected\.
.
.TP
\fB\-\-force\-poll\fR \fIinterval\fR
Poll for changes every \fIinterval\fR ms instead of using system\-specific notification mechanisms (such as inotify)\. This is useful when you are monitoring NFS shares\.
.
.TP
\fB\-d\fR, \fB\-\-debounce\fR
Set the timeout between detected change and command execution, to avoid restarting too frequently when there are many events; defaults to 100ms\.
.
.TP
\fB\-\-no\-vcs\-ignore\fR
Skip loading of version control system (VCS) ignore files\. By default, watchexec loads \.gitignore, \.hgignore, and other such files in the current directory (or child directories as applicable) and uses them to filter change events\.
.
.TP
\fB\-\-no\-project\-ignore\fR, \fB\-\-no\-ignore\fR (deprecated alias)
Skip loading of project\-local ignore files (include VCS ignore files)\. By default, watchexec loads \.ignore, \.gitignore, \.hgignore, and other such files in the current directory (or child directories as applicable) and uses them to filter change events\.
.
.TP
\fB\-\-no\-default\-ignore\fR
Skip default ignore statements\. By default, watchexec ignores common temporary files for you, for example \fB*\.swp\fR, \fB*\.pyc\fR, and \fB\.DS_Store\fR, as well as the data directories of known VCS: \fB\.bzr\fR, \fB_darcs\fR, \fB\.fossil\-settings\fR, \fB\.git\fR, \fB\.hg\fR, \fB\.pijul\fR, and \fB\.svn\fR\.
.
.TP
\fB\-\-no\-global\-ignore\fR
Skip loading of global ignore files\. By default, watchexec loads $HOME/\.gitignore and other such global files and uses them to filter change events\.
.
.TP
\fB\-v\fR, \fB\-\-verbose\fR, \fB\-vv\fR, etc
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\-\-print\-events\fR, \fB\-\-changes\-only\fR (deprecated alias)
Prints the events (changed paths, etc) that have triggered an action to STDERR\.
.
.TP
\fB\-N\fR, \fB\-\-notify\fR
Sends desktop notifications on command start and command end\.
.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print the version of watchexec\.
.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print a help message\.
.
.SH "PATHS"
By default, Watchexec watches the current directory\. This can be changed with the \fB\-\-watch\fR option, which can be passed multiple times\.
.
.P
Upon starting, Watchexec resolves a "project origin" from the watched paths\. To do so, it recurses up every parent directory from each watched path, looking for file and directory patterns which indicate a project origin among many different software systems, such as a Git repo, Cargo crate, licensing files, readmes, workspace configuration, etc\. For the full current list, consult the source at \fBlib/src/project\.rs\fR\.
.
.P
Once it has a list of "potential project origins", it resolves the common prefix they all have, and uses this as the overall project origin\. Note that the home directory is excluded from potential origins unless it\'s explicitly requested as a watched path\.
.
.P
The overall project origin is used to find and resolve ignore files, such that in most cases it acts as one would expect for a tool that runs anywhere inside a project\.
.
.P
For this reason, it is not recommended to use Watchexec for watching disparate folders in a filesystem, where those would resolve to a too\-broad project origin\.
.
.SH "ENVIRONMENT"
In variables that contain lists of paths, the separator is as for the \fB$PATH\fR environment variable (a colon, or semicolon on Windows)\.
.
.SS "Set on child processes"
Processes started by watchexec have environment variables set describing the changes observed\.
.
.P
\fB$WATCHEXEC_COMMON_PATH\fR 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:
.
.IP "\(bu" 4
\fB$WATCHEXEC_CREATED_PATH\fR is set when files/folders were created
.
.IP "\(bu" 4
\fB$WATCHEXEC_REMOVED_PATH\fR is set when files/folders were removed
.
.IP "\(bu" 4
\fB$WATCHEXEC_RENAMED_PATH\fR is set when files/folders were renamed
.
.IP "\(bu" 4
\fB$WATCHEXEC_WRITTEN_PATH\fR is set when files/folders were modified
.
.IP "\(bu" 4
\fB$WATCHEXEC_META_CHANGED_PATH\fR is set when files/folders\' metadata were modified
.
.IP "\(bu" 4
\fB$WATCHEXEC_OTHERWISE_CHANGED_PATH\fR is set for every other kind of pathed event
.
.IP "" 0
.
.P
These variables may contain multiple paths: these are separated by the platform\'s path separator, as with the \fBPATH\fR system environment variable\. On Unix that is \fB:\fR, and on Windows \fB;\fR\. Within each variable, paths are deduplicated and sorted in binary order (i\.e\. neither Unicode nor locale aware)\.
.
.P
One thing to take care of is assuming inherent behaviour where there is only chance\. Notably, it could appear as if the \fBRENAMED\fR variable contains both the original and the new path being renamed\. In previous versions, it would even appear on some platforms as if the original always came before the new\. However, none of this was true\. It\'s impossible to reliably and portably know which changed path is the old or new, "half" renames may appear (only the original, only the new), "unknown" renames may appear (change was a rename, but whether it was the old or new isn\'t known), rename events might split across two debouncing boundaries, and so on\.
.
.P
This variable group can be disabled or limited with \fB\-\-no\-environment\fR (doesn\'t set any of these variables) and \fB\-\-no\-meta\fR (ignores metadata changes)\.
.
.SS "Read upon startup"
.
.IP "\(bu" 4
\fB$WATCHEXEC_FILTERER\fR: select the filterer implementation: \fBglobset\fR (default), or \fBtagged\fR (experimental)\.
.
.IP "\(bu" 4
\fB$WATCHEXEC_IGNORE_FILES\fR: a list of paths to additional ignore files to be loaded\.
.
.IP "\(bu" 4
\fB$WATCHEXEC_FILTER_FILES\fR: a list of paths to additional "Tagged" filter files to be loaded (when enabled)\.
.
.IP "\(bu" 4
\fB$RUST_LOG\fR: use for advanced verbose logging configuration\. Refer to tracing\-subscriber for documentation\.
.
.IP "" 0
.
.SH "FILES"
.
.SS "Supported project ignore files"
.
.IP "\(bu" 4
Git: \fB\.gitignore\fR at project root and child directories, \fB\.git/info/exclude\fR, and the file pointed to by \fBcore\.excludesFile\fR in \fB\.git/config\fR\.
.
.IP "\(bu" 4
Mercurial: \fB\.hgignore\fR at project root and child directories\.
.
.IP "\(bu" 4
Bazaar: \fB\.bzrignore\fR at project root\.
.
.IP "\(bu" 4
Darcs: \fB_darcs/prefs/boring\fR
.
.IP "\(bu" 4
Fossil: \fB\.fossil\-settings/ignore\-glob\fR
.
.IP "\(bu" 4
Ripgrep/Watchexec/generic: \fB\.ignore\fR at project root and child directories\.
.
.IP "" 0
.
.P
Note that VCS ignore files (Git, Mercurial, Bazaar, Darcs, Fossil) are only used if the corresponding VCS is discovered to be in use for the project/origin\. For example, a \fB\.bzrignore\fR in a Git repository will be discarded\.
.
.SS "Supported global ignore files"
.
.IP "\(bu" 4
Git (if core\.excludesFile is set): the file at that path
.
.IP "\(bu" 4
Git (otherwise): the first found of \fB$XDG_CONFIG_HOME/git/ignore\fR, \fB%APPDATA%/\.gitignore\fR, \fB%USERPROFILE%/\.gitignore\fR, \fB$HOME/\.config/git/ignore\fR, \fB$HOME/\.gitignore\fR\.
.
.IP "\(bu" 4
Bazaar: the first found of \fB%APPDATA%/Bazzar/2\.0/ignore\fR, \fB$HOME/\.bazaar/ignore\fR\.
.
.IP "\(bu" 4
Watchexec: the first found of \fB$XDG_CONFIG_HOME/watchexec/ignore\fR, \fB%APPDATA%/watchexec/ignore\fR, \fB%USERPROFILE%/\.watchexec/ignore\fR, \fB$HOME/\.watchexec/ignore\fR\.
.
.IP "" 0
.
.P
Note that like for project files, Git and Bazaar global files will only be used for the corresponding VCS as used in the project\.
.
.SH "EXAMPLES"
Rebuild a project when source files change:
.
.IP "" 4
.
.nf

$ watchexec make
.
.fi
.
.IP "" 0
.
.P
Watch all HTML, CSS, and JavaScript files for changes:
.
.IP "" 4
.
.nf

$ watchexec \-e html,css,js make
.
.fi
.
.IP "" 0
.
.P
Run tests when source files change, clearing the screen each time:
.
.IP "" 4
.
.nf

$ watchexec \-c make test
.
.fi
.
.IP "" 0
.
.P
Launch and restart a node\.js server:
.
.IP "" 4
.
.nf

$ watchexec \-r node app\.js
.
.fi
.
.IP "" 0
.
.P
Watch lib and src directories for changes, rebuilding each time:
.
.IP "" 4
.
.nf

$ watchexec \-w lib \-w src make
.
.fi
.
.IP "" 0
.
.P
Use without shell:
.
.IP "" 4
.
.nf

$ watchexec \-n \-\- zsh \-x \-o shwordsplit scr
.
.fi
.
.IP "" 0
.
.P
Use with powershell (default on windows from 2\.0):
.
.IP "" 4
.
.nf

$ watchexec \-\-shell=powershell \-\- test\-connection localhost
.
.fi
.
.IP "" 0
.
.P
Use with cmd (default on windows until 2\.0):
.
.IP "" 4
.
.nf

$ watchexec \-\-shell=cmd \-\- dir
.
.fi
.
.IP "" 0
.
.P
Use with a different unix shell:
.
.IP "" 4
.
.nf

$ watchexec \-\-shell=bash \-\- \'echo $BASH_VERSION\'
.
.fi
.
.IP "" 0
.
.P
Use with a unix shell and options:
.
.IP "" 4
.
.nf

$ watchexec \-\-shell=\'zsh \-x \-o shwordsplit\' \-\- scr
.
.fi
.
.IP "" 0