CheatPress

watchexec Run on file change

Version 2.8.0 · source

watchexec, Postcard, light preview Light · Postcard 102 × 152 mm · PDF watchexec, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF watchexec, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
watchexec, A5, light preview Light · A5 148 × 210 mm · PDF watchexec, A5, dark preview Dark · A5 148 × 210 mm · PDF watchexec, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
watchexec, A4, light preview Light · A4 210 × 297 mm · PDF watchexec, A4, dark preview Dark · A4 210 × 297 mm · PDF watchexec, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
watchexec, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF watchexec, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF watchexec, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
watchexec, A3, light preview Light · A3 297 × 420 mm · PDF watchexec, A3, dark preview Dark · A3 297 × 420 mm · PDF watchexec, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
watchexec, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF watchexec, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF watchexec, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
watchexec, Letter, light preview Light · Letter 8.5 × 11 in · PDF watchexec, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF watchexec, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
watchexec, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF watchexec, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF watchexec, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

watchexec <cmd>
Run on any change
watchexec -e py pytest
Only Python files
watchexec -r -- <server>
Restart on change
watchexec -w src <cmd>
Watch one folder
watchexec -c <cmd>
Clear screen first
watchexec -p <cmd>
Wait for first change
watchexec -i "*.log" <cmd>
Ignore files
watchexec -n <cmd>
Run without a shell

Concepts

  1. File event save, create, delete
  2. Filters paths, ignores, -e, -f
  3. Command start or restart
  4. Wait for next change

Running

watchexec <cmd> [args]
Run a command whenever files change
watchexec -- <cmd> --flag
Stop option parsing before the command
watchexec -p <cmd>
Postpone: skip the initial run
watchexec -r <cmd>
Restart the command on change
watchexec -c <cmd>
Clear the screen before each run
watchexec -n <cmd>
No shell: run the program directly
watchexec --shell <shell> <cmd>
Choose the shell, e.g. bash or zsh
watchexec -E <KEY=VALUE> <cmd>
Set an env var for the command only
watchexec --workdir <dir> <cmd>
Run the command in another directory
watchexec -I <cmd>
Interactive: r restart, s stop, p pause, q quit
watchexec --exit-on-error <cmd>
Quit when the command fails
watchexec --timeout <time> <cmd>
Stop a run that takes too long
watchexec --delay-run <time> <cmd>
Sleep before each run
watchexec --timings <cmd>
Print how long each run took
watchexec -q <cmd>
Hide watchexec's own start/stop messages
watchexec -N <cmd>
Desktop notification when the run starts or ends
watchexec --bell <cmd>
Ring the terminal bell when done

What to watch

-w <path>
Watch a file or directory (repeatable)
-W <dir>
Watch a directory without recursion
-e <ext,ext>
Only react to these extensions
Give them without dots: -e rs,toml
-f <glob>
Only react to paths matching a pattern
-i <glob>
Ignore paths matching a pattern
--ignore-file <path>
Load ignore patterns from a file
--filter-file <path>
Load filter patterns from a file
-F <file>
Read watch paths from a file (- for stdin)
--no-vcs-ignore
Watch files that .gitignore excludes
--no-default-ignore
Also watch .git, swap files, .DS_Store
--no-discover-ignore
Skip loading every ignore file
--ignore-nothing
Ignore no files, not even defaults
--project-origin <dir>
Override the detected project root
--fs-events <list>
Filter by event: create, remove, rename, modify, access
--no-meta
Skip metadata-only events
-j <expr>
Filter events with a jaq program

Busy and signals

-o <mode>
If busy: do-nothing, queue, restart or signal
-r
Same as -o restart
-s <signal>
Send a signal to the running command on change
--stop-signal <signal>
Signal used to stop it (default SIGTERM)
--stop-timeout <time>
Grace time before a force kill (default 10s)
--map-signal <in:out>
Translate a received signal to another
--wrap-process <mode>
auto, group, session or none
--stdin-quit
Exit when stdin closes

Debounce and polling

-d <time>
Wait for quiet before acting (default 50ms)
--poll [interval]
Poll instead of OS events (network drives)
--no-follow-symlinks
Do not follow directory symlinks

Changed paths

--emit-events-to <mode>
none, environment, stdio, file, json-stdio, json-file
--emit-events-to=json-stdio
Send events as JSON lines on stdin
--emit-events-to=environment
Set WATCHEXEC_*_PATH variables (deprecated)
Variables: WATCHEXEC_COMMON_PATH plus _CREATED_, _REMOVED_, _RENAMED_, _WRITTEN_, _META_CHANGED_ and _OTHERWISE_CHANGED_PATH
--print-events
Print the events that triggered a run
--only-emit-events
Emit events only; run no command

Setup and debug

watchexec --completions <shell>
Print shell completions
watchexec --manual
Show the full manual
watchexec -v / -vvvv
More diagnostic logging
WATCHEXEC_LOG=<level>
Set log level (beats -v)
--log-file [path]
Write JSON logs to a file
--color <mode>
auto, always or never (NO_COLOR works too)
watchexec @<argfile>
Load arguments from a file, one per line
watchexec -V
Show the version

Recipes

Run tests on Rust changes
watchexec -c -e rs,toml -- cargo test
Dev server with restart
watchexec -r -e py,html -- python manage.py runserver --noreload
Rebuild assets, skip output
watchexec -w src -i "dist/**" -e js,css -- npm run build
Debounced build, then notify
watchexec -d 500 -N -p -e md -- make site