2022-09-18 23:27:03 +02:00
[](https://github.com/watchexec/watchexec/actions/workflows/tests.yml)
2021-05-08 17:39:13 +02:00
# Watchexec
2016-10-15 20:03:23 +02:00
2016-09-18 22:42:11 +02:00
Software development often involves running the same commands over and over. Boring!
2023-11-28 12:30:33 +01:00
`watchexec` is a simple, standalone tool that watches a path and runs a command whenever it detects modifications.
2016-09-18 22:42:11 +02:00
Example use cases:
* Automatically run unit tests
* Run linters/syntax checkers
2023-01-06 15:20:16 +01:00
* Rebuild artifacts
2016-09-18 22:42:11 +02:00
2021-05-08 17:39:13 +02:00
2017-03-27 10:56:06 +02:00
## Features
2016-09-18 22:42:11 +02:00
2021-05-08 17:39:13 +02:00
* Simple invocation and use, does not require a cryptic command line involving `xargs`
2020-07-03 13:55:54 +02:00
* Runs on OS X, Linux, and Windows
2016-11-17 14:46:23 +01:00
* Monitors current directory and all subdirectories for changes
2016-09-18 22:42:11 +02:00
* Coalesces multiple filesystem events into one, for editors that use swap/backup files during saving
2021-05-08 17:39:13 +02:00
* Loads `.gitignore` and `.ignore` files
* Uses process groups to keep hold of forking programs
2023-11-28 12:30:33 +01:00
* Provides the paths that changed in environment variables or STDIN
2021-05-08 17:39:13 +02:00
* Does not require a language runtime, not tied to any particular language or ecosystem
2022-06-17 01:58:52 +02:00
* [And more! ](./crates/cli/#features )
2016-09-18 22:42:11 +02:00
2016-09-22 16:03:23 +02:00
2021-05-08 17:39:13 +02:00
## Quick start
2016-09-18 22:42:11 +02:00
2021-05-08 17:39:13 +02:00
Watch all JavaScript, CSS and HTML files in the current directory and all subdirectories for changes, running `npm run build` when a change is detected:
2016-12-15 01:45:31 +01:00
2021-05-08 17:39:13 +02:00
$ watchexec -e js,css,html npm run build
2016-12-15 01:45:31 +01:00
2016-09-24 19:52:54 +02:00
Call/restart `python server.py` when any Python file in the current directory (and all subdirectories) changes:
2021-05-08 17:39:13 +02:00
$ watchexec -r -e py -- python server.py
2019-10-28 02:51:04 +01:00
2022-06-17 01:58:52 +02:00
More usage examples: [in the CLI README ](./crates/cli/#usage-examples )!
2020-10-01 23:23:07 +02:00
2021-05-08 17:39:13 +02:00
## Install
2016-10-17 17:53:43 +02:00
2021-09-28 14:43:36 +02:00
< a href = "https://repology.org/project/watchexec/versions" > < img align = "right" src = "https://repology.org/badge/vertical-allrepos/watchexec.svg" alt = "Packaging status" > < / a >
2022-12-02 23:44:04 +01:00
- With [your package manager ](./doc/packages.md ) for Arch, Debian, Homebrew, Nix, Scoop, Chocolatey…
2022-09-07 02:24:44 +02:00
- From binary with [Binstall ](https://github.com/cargo-bins/cargo-binstall ): `cargo binstall watchexec-cli`
- As [pre-built binary package from Github ](https://github.com/watchexec/watchexec/releases/latest )
2023-03-02 03:33:39 +01:00
- From source with Cargo: `cargo install --locked watchexec-cli`
2019-04-17 12:16:35 +02:00
2023-03-05 02:57:34 +01:00
All options in detail: [in the CLI README ](./crates/cli/#installation ),
in the online help (`watchexec -h`, `watchexec --help` , or `watchexec --manual` ),
2023-12-09 10:30:58 +01:00
and [in the manual page ](./doc/watchexec.1.md ).
2022-04-15 05:47:44 +02:00
2019-10-21 15:15:37 +02:00
2022-02-08 02:59:41 +01:00
## Augment
Watchexec pairs well with:
- [checkexec ](https://github.com/kurtbuilds/checkexec ): to run only when source files are newer than a target file
- [just ](https://github.com/casey/just ): a modern alternative to `make`
- [systemfd ](https://github.com/mitsuhiko/systemfd ): socket-passing in development
2019-04-17 12:16:35 +02:00
2021-05-08 17:39:13 +02:00
## Extend
2016-09-18 22:42:11 +02:00
2023-11-28 12:30:33 +01:00
- [watchexec library ](./crates/lib/ ): to create more specialised watchexec-powered tools.
- [watchexec-events ](./crates/events/ ): event types for watchexec.
- [watchexec-signals ](./crates/signals/ ): signal types for watchexec.
- [watchexec-supervisor ](./crates/supervisor/ ): process lifecycle manager (the _exec_ part of watchexec).
2021-05-08 17:39:13 +02:00
- [clearscreen ](https://github.com/watchexec/clearscreen ): to clear the (terminal) screen on every platform.
2021-07-21 14:13:59 +02:00
- [command group ](https://github.com/watchexec/command-group ): to run commands in process groups.
2022-06-15 05:25:05 +02:00
- [ignore files ](./crates/ignore-files/ ): to find, parse, and interpret ignore files.
- [project origins ](./crates/project-origins/ ): to find the origin(s) directory of a project.
2021-07-21 14:13:59 +02:00
- [notify ](https://github.com/notify-rs/notify ): to respond to file modifications (third-party).
2023-11-28 12:30:33 +01:00
### Downstreams
Selected downstreams of watchexec and associated crates:
- [cargo watch ](https://github.com/watchexec/cargo-watch ): a specialised watcher for Rust/Cargo projects.
- [cargo lambda ](https://github.com/cargo-lambda/cargo-lambda ): a dev tool for Rust-powered AWS Lambda functions.
- [create-rust-app ](https://create-rust-app.dev ): a template for Rust+React web apps.
- [dotter ](https://github.com/supercuber/dotter ): a dotfile manager.
- [ghciwatch ](https://github.com/mercurytechnologies/ghciwatch ): a specialised watcher for Haskell projects.
- [tectonic ](https://tectonic-typesetting.github.io/book/latest/ ): a TeX/LaTeX typesetting system.
