$ cargo watch

Cargo Watch watches over your project's source for changes, and runs Cargo commands when they occur.

If you've used [nodemon], [gulp], [guard], [watchman], or similar others, it will probably feel familiar.

Install

$ cargo install cargo-watch

To upgrade:

$ cargo install --force cargo-watch

Or clone and build with $ cargo build then place in your $PATH.

Usage

By default, it runs check (which is available since Rust 1.16). You can easily override this, though:

$ cargo watch [-x command]...

A few examples:

```

Run tests only

$ cargo watch -x test

Run check then tests

$ cargo watch -x check -x test

Run run with arguments

$ cargo watch -x 'run -- --some-arg'

Run an arbitrary command

$ cargo watch -s 'echo Hello world' ```

There's a lot more you can do! Here's a copy of the help:

``` USAGE: cargo watch [FLAGS] [OPTIONS]

FLAGS: -c, --clear Clear the screen before each run -h, --help Display this message --ignore-nothing Ignore nothing, not even target/ and .git/ --no-gitignore Don’t use .gitignore files --poll Force use of polling for file changes --postpone Postpone first run until a file changes -q, --quiet Suppress output from cargo-watch itself -V, --version Display version information

OPTIONS: -x, --exec ... Cargo command(s) to execute on changes [default: check] -s, --shell ... Shell command(s) to execute on changes -d, --delay File updates debounce delay in seconds [default: 1] -i, --ignore ... Ignore a glob/gitignore-style pattern -w, --watch ... Watch specific file(s) or folder(s) [default: .]

Cargo commands (-x) are always executed before shell commands (-s).

By default, your entire project is watched, except for the target/ and .git/ folders, and your .gitignore files are used to filter paths. ```

Contributing

The cargo-watch team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! The Contributor Guide has all the information you need for everything from reporting bugs to contributing entire new features. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear. <sub>{attribution}</sub>

Troubleshooting

In all cases, start by checking your version with cargo watch --version and, if necessary, upgrading to the latest one.

If running cargo watch errors with "Found argument 'build' which wasn't expected" (or similar)

You're probably using version 4 (or higher) but using the version 3 (or lower) style of arguments. The interface changed! Refer to the sections above for new usage guidelines, or to the help message:

$ cargo watch --help

I want to run cargo-watch directly, without going through cargo

You can! But you'll have to specify the watch subcommand as the first argument, like so:

$ /path/to/cargo-watch watch -x build

If file updates seems to never trigger

Try using --poll to force the polling fallback.

If that still doesn't work, and you're using an editor that does "safe saving", like IntelliJ / PyCharm, you may have to disable "safe saving" as that may prevent file notifications from being generated properly.

Linux: If it fails to watch some deep directories but not others

You may have hit the inotify watch limit. You can either increase the limit (instructions are on the previous link and at this Guard wiki page), or you can stop whatever it is that's consuming so many inotify watches.

If you want to only recompile one Cargo workspace

Cargo workspaces are not natively supported yet.

However, as you can run "arbitrary commands" with the -s option, you can write workspace-aware commands manually.

If it runs repeatedly without touching anything

That can happen when watching files that are modified by the command you're running.

If you're only running compiles or checks (i.e. any command that only affects the target/ folder) and you're using -w, you might be confusing the target-folder-ignorer. Check your options and paths.

Something not covered above / I have a feature request

Please open an issue, or look through the existing ones. You may also want to look through issues for the Notify library this tool depends on.

If you want more verbose output, try running with the RUST_LOG=cargo_watch=info environment variable. You can switch info to debug or even trace (caution: very busy output!) for even more messages.

Note that -q will hide some error-level messages, even with RUST_LOG.

About

Created by Félix Saparelli and awesome contributors.