watchexec(1) - execute commands when watched files change

watchexec(1)
watchexec(1)

NAME

watchexec - execute commands when watched files change

SYNOPSIS

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.
-e, --exts extensions: Comma-separated list of file extensions to filter by. Leading dots are allowed (.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 child process. Defaults to SIGTERM.
-n, --no-shell: Execute command directly, do not wrap it in sh -c resp. cmd.exe /C. This is especially useful in combination with --signal, as the signal is then send directly to the specified command. While --no-shell is a little more performant than the default, it prevents using shell-features like pipes and redirects.
-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 child process group if it is still running when subsequent file modifications are detected. By default, sends SIGTERM; use --kill to send SIGKILL.
-c, --clear: Clears the screen before executing command.
-p, --postpone: Postpone execution of command until the first file modification is detected.
-d, --debug: Prints diagnostic messages to STDERR
--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.
--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.

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

August 2018
watchexec(1)