159 lines
6.8 KiB
Markdown
159 lines
6.8 KiB
Markdown
watchexec(1) -- execute commands when watched files change
|
|
==========================================================
|
|
|
|
## SYNOPSIS
|
|
|
|
watchexec [`--exts` | `-e` <extensions>]... [`--filter` | `-f` <pattern>]... [`--ignore` | `-i` <pattern>]... [`--watch` | `-w` <path>]... [`--restart` | `-r`] [`--clear` | `-c`] [`--postpone` | `-p`] [`--force-poll` <interval>] [`--debounce` | `-d` <interval>] [`--no-vcs-ignore`] [`--no-default-ignore`] [`--verbose` | `-v`] [`--changes-only`] [`--version` | `-V`] [--] <command> [<argument>...]
|
|
|
|
## 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.
|
|
|
|
At startup, the specified <command> (passing any supplied <argument>s) is run once, and watchexec begins monitoring for changes.
|
|
|
|
## OPTIONS
|
|
|
|
* <command>:
|
|
Command to run when watched files are modified, and at startup, unless `--postpone` is specified. All <argument>s are passed to <command>. If you pass flags to the command, you should separate it with `--`, for example: `watchexec -w src -- rsync -a src dest`.
|
|
|
|
Behaviour depends on the value of `--shell`: for all except `none`, every part of <command> is joined together into one string with a single ascii space character, and given to the shell as described. For `none`, each distinct element of <command> is passed as per the execvp(3) convention: first argument is the program, as a file or searched in the `PATH`, rest are arguments.
|
|
|
|
* `-e`, `--exts` <extensions>:
|
|
Comma-separated list of file extensions to filter by. Leading dots (.rs) are allowed. (This is a shorthand for `-f`).
|
|
|
|
* `-f`, `--filter` <pattern>:
|
|
Ignores modifications from paths that do not match <pattern>. This option can be specified multiple times, where a match on any given pattern causes the path to trigger <command>.
|
|
|
|
* `-s`, `--signal`:
|
|
Sends the specified signal (e.g. `SIGKILL`) to the command. Defaults to `SIGTERM`.
|
|
|
|
* `--shell` <shell>:
|
|
Change the shell used to run the command. Set to `none` to run the command directly without a shell.
|
|
|
|
The special value `powershell` will use Microsoft Powershell's calling convention, otherwise `SHELL -c COMMAND`.
|
|
|
|
On Windows, the additional `cmd` special value uses CMD.EXE calling convention.
|
|
|
|
The `none` value is especially useful in combination with `--signal`, as the signal is then sent directly to the running command. While `--shell=none` is a little more performant than the default, it prevents using shell-features like pipes and redirects.
|
|
|
|
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 `-c` is added, and finally the `COMMAND`.
|
|
|
|
See the [EXAMPLES] for uses of each of these.
|
|
|
|
* `--no-shell`:
|
|
Deprecated. Alias for `--shell=none`.
|
|
|
|
* `-n`:
|
|
Shorthand for `--shell=none`.
|
|
|
|
* `--no-meta`:
|
|
Ignore metadata changes.
|
|
|
|
* `--no-environment`:
|
|
Do not set WATCHEXEC_*_PATH environment variables for the command.
|
|
|
|
* `-i`, `--ignore` <pattern>:
|
|
Ignores modifications from paths that match <pattern>. This option can be specified multiple times, and a match on any pattern causes the path to be ignored.
|
|
|
|
* `-w`, `--watch` <path>:
|
|
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 <command> to be executed.
|
|
|
|
* `-r`, `--restart`:
|
|
Terminates the command if it is still running when subsequent file modifications are detected. By default, sends `SIGTERM`; use `--signal` to change that.
|
|
|
|
* `-W`, `--watch-when-idle`:
|
|
Ignore events while the process is still running. This is distinct from `--restart` 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.
|
|
|
|
This behaviour will become the default in v2.0.
|
|
|
|
* `--no-process-group`:
|
|
Do not use a process group when running <command>.
|
|
|
|
* `-c`, `--clear`:
|
|
Clears the screen before executing <command>.
|
|
|
|
* `-p`, `--postpone`:
|
|
Postpone execution of <command> until the first file modification is detected.
|
|
|
|
* `--force-poll` <interval>:
|
|
Poll for changes every <interval> ms instead of using system-specific notification mechanisms (such as inotify). This is useful when you are monitoring NFS shares.
|
|
|
|
* `-d`, `--debounce`:
|
|
Set the timeout between detected change and command execution, to avoid restarting too frequently when there are many events; defaults to 100ms.
|
|
|
|
* `--no-vcs-ignore`:
|
|
Skip loading of version control system (VCS) ignore files. By default, watchexec loads .gitignore files in the current directory (or parent directories) and uses them to populate the ignore list.
|
|
|
|
* `--no-default-ignore`:
|
|
Skip default ignore statements. By default, watchexec ignores common temporary files for you, for example `*.swp`, `*.pyc`, and `.DS_Store`.
|
|
|
|
* `-v`, `--verbose`:
|
|
Prints diagnostic messages to STDERR.
|
|
|
|
* `--changes-only`:
|
|
Prints the paths that have changed as diagnostics to STDERR, but not everything else that `--verbose` prints.
|
|
|
|
* `-V`, `--version`:
|
|
Print the version of watchexec.
|
|
|
|
* `-h`, `--help`:
|
|
Print a help message.
|
|
|
|
## ENVIRONMENT
|
|
|
|
Processes started by watchexec have environment variables set describing the modification(s) observed. Which variable is set depends on how many modifications were observed and/or what type they were.
|
|
|
|
If a single file changed (depending on the event type):
|
|
|
|
* `$WATCHEXEC_CREATED_PATH`, the path of the file that was created
|
|
* `$WATCHEXEC_REMOVED_PATH`, the path of the file that was removed
|
|
* `$WATCHEXEC_RENAMED_PATH`, the path of the file that was renamed
|
|
* `$WATCHEXEC_WRITTEN_PATH`, the path of the file that was modified
|
|
* `$WATCHEXEC_META_CHANGED_PATH`, the path of the file whose metadata changed
|
|
|
|
If multiple files changed:
|
|
|
|
* `$WATCHEXEC_COMMON_PATH`, the longest common path of all of the files that triggered a change
|
|
|
|
## EXAMPLES
|
|
|
|
Rebuild a project when source files change:
|
|
|
|
$ watchexec make
|
|
|
|
Watch all HTML, CSS, and JavaScript files for changes:
|
|
|
|
$ watchexec -e html,css,js make
|
|
|
|
Run tests when source files change, clearing the screen each time:
|
|
|
|
$ watchexec -c make test
|
|
|
|
Launch and restart a node.js server:
|
|
|
|
$ watchexec -r node app.js
|
|
|
|
Watch lib and src directories for changes, rebuilding each time:
|
|
|
|
$ watchexec -w lib -w src make
|
|
|
|
Use without shell:
|
|
|
|
$ watchexec -n -- zsh -x -o shwordsplit scr
|
|
|
|
Use with powershell (default on windows from 2.0):
|
|
|
|
$ watchexec --shell=powershell -- test-connection localhost
|
|
|
|
Use with cmd (default on windows until 2.0):
|
|
|
|
$ watchexec --shell=cmd -- dir
|
|
|
|
Use with a different unix shell:
|
|
|
|
$ watchexec --shell=bash -- 'echo $BASH_VERSION'
|
|
|
|
Use with a unix shell and options:
|
|
|
|
$ watchexec --shell='zsh -x -o shwordsplit' -- scr
|