1. watchexec(1)
3. watchexec(1)

NAME

watchexec - 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 arguments) 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 arguments 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.

-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.

The none value is especially useful in combination with --signal, as the signal is then send directly to the specified command. While --shell=none is a little more performant than the default, it prevents using shell-features like pipes and redirects.

--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.

-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 150ms.

--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

2. April 2021
3. watchexec(1)