watchexec/doc/watchexec.1.ronn

159 lines
6.8 KiB
Plaintext
Raw Normal View History

2016-10-29 19:08:55 +02:00
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>...]
2016-10-29 19:08:55 +02:00
## DESCRIPTION
2016-11-17 14:46:23 +01:00
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.
2016-10-29 19:08:55 +02:00
At startup, the specified <command> (passing any supplied <argument>s) is run once, and watchexec begins monitoring for changes.
## OPTIONS
2017-02-05 19:29:38 +01:00
* <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`.
2016-10-29 19:08:55 +02:00
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.
2016-10-29 19:08:55 +02:00
* `-e`, `--exts` <extensions>:
2019-10-10 12:39:13 +02:00
Comma-separated list of file extensions to filter by. Leading dots (.rs) are allowed. (This is a shorthand for `-f`).
2016-10-29 19:08:55 +02:00
* `-f`, `--filter` <pattern>:
2017-02-05 19:29:38 +01:00
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>.
2016-10-29 19:08:55 +02:00
2017-03-26 18:25:13 +02:00
* `-s`, `--signal`:
Sends the specified signal (e.g. `SIGKILL`) to the command. Defaults to `SIGTERM`.
2021-04-10 16:51:20 +02:00
* `--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.
2021-04-16 16:11:16 +02:00
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.
2021-04-10 16:51:20 +02:00
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.
2021-04-10 16:51:20 +02:00
* `--no-shell`:
Deprecated. Alias for `--shell=none`.
* `-n`:
Shorthand for `--shell=none`.
2017-04-06 22:51:52 +02:00
* `--no-meta`:
Ignore metadata changes.
2020-06-23 13:43:55 +02:00
* `--no-environment`:
Do not set WATCHEXEC_*_PATH environment variables for the command.
2020-06-23 13:43:55 +02:00
2017-02-05 19:29:38 +01:00
* `-i`, `--ignore` <pattern>:
2016-10-29 19:08:55 +02:00
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.
2017-02-05 19:29:38 +01:00
* `-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.
2016-10-29 19:08:55 +02:00
* `-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.
2016-10-29 19:08:55 +02:00
2021-07-21 14:56:35 +02:00
* `--no-process-group`:
Do not use a process group when running <command>.
2016-10-29 19:08:55 +02:00
* `-c`, `--clear`:
Clears the screen before executing <command>.
* `-p`, `--postpone`:
Postpone execution of <command> until the first file modification is detected.
* `--force-poll` <interval>:
2016-11-17 14:46:23 +01:00
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.
2016-10-29 19:08:55 +02:00
* `-d`, `--debounce`:
2021-07-21 13:44:24 +02:00
Set the timeout between detected change and command execution, to avoid restarting too frequently when there are many events; defaults to 100ms.
2016-10-29 19:08:55 +02:00
* `--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.
2017-04-26 03:15:40 +02:00
* `--no-default-ignore`:
Skip default ignore statements. By default, watchexec ignores common temporary files for you, for example `*.swp`, `*.pyc`, and `.DS_Store`.
2017-04-26 03:15:40 +02:00
* `-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.
2016-10-29 19:08:55 +02:00
## 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
2016-10-29 19:08:55 +02:00
## 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
2017-02-05 19:29:38 +01:00
Launch and restart a node.js server:
2016-10-29 19:08:55 +02:00
$ watchexec -r node app.js
2017-02-05 19:29:38 +01:00
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