Cargo Watch watches over your project’s source for changes, and runs Cargo commands when they occur.
Cargo is the Rust package manager. Cargo downloads your Rust package’s dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io - https://crates.io/, the Rust community’s package registry.
- Install Rust and Cargo
The easiest way to get Cargo is to install the current stable release of Rust by using rustup. Installing Rust using rustup will also install cargo.
On Linux and macOS systems, this is done as follows:
curl https://sh.rustup.rs -sSf | sh
It will download a script, and start the installation. If everything goes well, you’ll see this appear:
Rust is installed now. Great!
Installed with the following command:
cargo install cargo-watch
By default, it runs
check. You can easily override this, though:
cargo watch [-x command]...
There’s a lot more you can do! Here’s a copy of the help:
cargo watch -h
.gitignore files are used by default to ignore paths to watch and trigger runs. To stop honouring them, pass
.ignore files in the same syntax are also used by default. This file can be used to specify files that should be ignored by cargo watch but checked into git, without constantly adding
--ignore abc options on the command-line. Do note that
.ignore files may also be used by other programs, like
ripgrep. To stop honouring these, pass
Cargo watch also has an internal list of default ignores on top of those specified in files, like
target/ and .git/`` and various other common types (logs, editor swap files, lockfiles, etc).
To skip absolutely all ignores, use the
See the glob::Pattern docs for a more detailed specification of the glob matching syntax used for
On Windows, patterns should be specified with Windows-style (
\\) separators. Unix-style separators (
/) would not match Windows paths, which could be confusing and give the appearance of commandline ignores not working.
From Cargo Watch 7.0.0,
/ in commandline ignores are automatically translated to
\\ when running on Windows, but one should still try to write the correct patterns for the platform, as there may be more subtle differences.
From Cargo Watch 7.3.0,
--ignore patterns were fixed to provide better experience with directory matching. Previously, ignoring a folder would need unyieldy
-i folder/** patterns; now that is handled internally, and only
-i folder is needed for the same effect.
Reloading servers seamlessly
Cargo Watch pairs very well with systemfd/Catflap, tools for Unixy platforms that lets one spawn a socket before the watcher runs that Rust servers can then bind to, avoiding request-dropping and the infamous ADDRINUSE error. For example:
systemfd --no-pid -s http::5000 -- cargo watch -x run
Of course, if you don’t need to guard against these issues or don’t want to modify your program to grab sockets instead of ports, you can use Cargo Watch as-is: it will happily just restart your server normally.
Restarting an application only if the build/check succeeds
Brought up by @LeDominikFeature Suggestion: conditional run · Issue #75 · watchexec/cargo-watch - https://github.com/watchexec/cargo-watch/issues/75, here’s a pattern that may be very useful: you’re working on a server or app, but want it to keep running while you’re writing a new feature or fixing a bug, potentially causing the code not to compile anymore in the meantime.
In this case, you can use this strategy: run a first cargo watch with check, build, test, or whatever you want, and append
-s 'touch .trigger' (or equivalent for your platform). Then, run a second cargo watch simultaneously that only watches that
.trigger file. For example:
cargo watch -x check -s 'touch .trigger'
cargo watch --no-gitignore -w .trigger -x run
--no-gitignore flag ensures that you can safely add
.trigger to your
.gitignore file to avoid mistakenly committing it.
I want to embed Cargo Watch in my own (Rust) tool
It is not recommended to do that directly. You may of course call cargo-watch as any other program, and technically it exposes an (undocumented) library that could be directly / statically embedded. If you have no other option, that may be your best bet.
However, for most cases, consider building on top of Watchexec - https://watchexec.github.io/ instead. That is itself built on Notify | notify-rs/notify: 🔭 Cross-platform filesystem notification library for Rust. - https://github.com/notify-rs/notify, and both of these can be used as Rust libraries.
If you want to build a tool that runs, restarts, and otherwise manages commands in response to file changes, you’ll most probably want to use Watchexec.
If you want to build a tool that responds to file changes, but does not need to run commands, or does so in a way that is not well-supported by Watchexec, then Notify is your ticket.
See Troubleshooting - https://github.com/watchexec/cargo-watch#troubleshooting to leran more.