watchexec

Call ls -la when any file in the current directory changes

$ watchexec [ls -la]

$ watchexec [[-e|--exts]] [js,css,html] make

$ watchexec [[-w|--watch]] [lib] [[-w|--watch]] [src] [make]

$ watchexec [[-r|--restart]] --stop-signal [SIGKILL] [my_server]

$ watchexec [[-r|--restart]] --stop-signal [SIGKILL] --poll [10000] [[-e|--exts]] [java] [command]

watchexec [options] -- <command> [<args>...]

-w, --watch
    Specify paths or files to monitor for changes. Can be used multiple times.

-e, --exts
    Filter watched files by a comma-separated list of extensions (e.g., 'rs,toml,json').

-i, --ignore
    Define paths or files to explicitly exclude from monitoring. Can be used multiple times.

-f, --filter
    Apply Gitignore-style patterns to filter watched paths. Can be used multiple times.

--clear
    Clear the terminal screen before each command execution.

-r, --restart
    Kill the previous command instance and restart it upon changes.

-s, --signal
    Send a specified signal (e.g., SIGTERM, SIGKILL) to the child process on exit or restart.

-p, --poll
    Use polling instead of native file system events for monitoring. Useful for network drives or environments where native events are unreliable.

-d, --debounce
    Set a delay in milliseconds to wait for events to settle before executing the command. Default is 500ms.

--shell
    Specify the shell used to run the command (e.g., /bin/bash, cmd.exe).

--no-meta
    Do not pass metadata about the change (like changed file paths) to the executed command via environment variables.

--postpone
    Wait for the first file change before initially running the command. By default, the command runs once on startup.

watchexec is a modern, cross-platform command-line tool that monitors files and directories for changes, then executes a specified command. It is widely used in development workflows to automate tasks like recompiling code, restarting servers, or running tests automatically when source files are modified. Designed for efficiency, it intelligently debounces file system events to prevent excessive command executions and offers robust filtering capabilities to include or exclude specific paths. It supports various events including creation, modification, and deletion across different operating systems. Its reliability and ease of use make it an invaluable utility for improving developer productivity.

File system event reliability can vary between operating systems and file systems (e.g., network mounts, WSL). The --poll option can mitigate this but might consume more resources.
Complex commands passed after -- may require careful shell escaping, especially on Windows or when using specific shells.
Monitoring a very large number of files or deeply nested directories can increase resource usage and potentially impact performance.

watchexec is frequently used to automate development tasks, significantly improving developer feedback loops:

• Automatically recompiling code (e.g., watchexec -w src -e rs -- cargo build)
• Restarting web servers or backend services on code changes.
• Running test suites upon file modifications.
• Triggering linters or formatters on save.
• Automating deployment steps during local development.

The --signal option is crucial for managing long-running processes. It allows watchexec to send a specific signal (like SIGTERM for graceful shutdown or SIGKILL for immediate termination) to the child process when files change or watchexec itself exits, ensuring proper resource cleanup and preventing orphaned processes.

watchexec was developed to provide a modern, robust, and cross-platform file watcher, addressing limitations of existing tools like platform specificity or performance issues. Written in Rust, it leverages efficient native file system APIs where available and provides a consistent experience across Linux, macOS, and Windows. Its design prioritizes reliability and ease of integration into various development workflows since its initial release around 2017.

watch(1), entr(1), inotifywait(1), fswatch(1)