cargo-watch.1

.\" generated with Ronn/v0.7.3
.\" https://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "CARGO\-WATCH" "1" "January 2024" "" ""
.
.SH "NAME"
\fBcargo\-watch\fR \- watches over your Cargo project\'s source
.
.SH "SYNOPSIS"
cargo watch [options] [\fB\-\-exec\fR | \fB\-x\fR \fIcargo subcommand\fR]\.\.\. [\fB\-\-shell\fR | \fB\-s\fR \fIcommand\fR]\.\.\. [\-\- \fIcommand\fR\.\.\.] cargo watch [\fB\-\-version\fR | \fB\-V\fR] cargo watch [\fB\-\-help\fR | \fB\-h\fR]
.
.SH "DESCRIPTION"
Watches over your project\'s source for changes, and runs Cargo commands when they occur\.
.
.SH "COMMANDS"
.
.TP
\fIcargo subcommand\fR
Cargo subcommand to run when watched files are modified, and at startup, unless \fB\-\-postpone\fR is specified\.
.
.P
This is essentially the same as \fB<command>\fR but with \fBcargo\fR prepended, except that in addition, cargo\-specific options are applied, such as \fB\-\-features\fR\.
.
.TP
\fIcommand\fR
Command to run when watched files are modified, and at startup, unless \fB\-\-postpone\fR is specified\.
.
.P
All commands passed are joined together with \fB&&\fR\.
.
.P
Cargo commands (\fB\-x\fR) are always executed before shell commands (\fB\-s\fR)\.
.
.P
If a trailing command is given with \fB\-\- <command>\fR, it supersedes all other commands\.
.
.SH "OPTIONS"
.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display this message\.
.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version information\.
.
.TP
\fB\-\-debug\fR
Show debug output\.
.
.TP
\fB\-\-why\fR
Show paths that changed\.
.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Suppress output from cargo\-watch itself\.
.
.TP
\fB\-\-skip\-local\-deps\fR
Don\'t try to find local dependencies of the current crate and watch their working directories\. Only watch the current directory\.
.
.TP
\fB\-w\fR, \fB\-\-watch\fR \fIwatch\fR\.\.\.
Watch specific file(s) or folder(s)\. Disables finding and watching local dependencies\.
.
.P
By default, the workspace directories of your project and all local dependencies are watched, except for the target/ and \.git/ folders\. Your \.ignore and \.gitignore files are used to filter paths\.
.
.TP
\fB\-i\fR, \fB\-\-ignore\fR \fIpattern\fR\.\.\.
Ignore a glob/gitignore\-style pattern\.
.
.P
On Windows, patterns given to \-i have forward slashes (/) automatically converted to backward ones () to ease command portability\.
.
.TP
\fB\-\-no\-vcs\-ignores\fR
Don’t use \.gitignore files\.
.
.TP
\fB\-\-no\-dot\-ignores\fR
Don’t use \.ignore files\.
.
.TP
\fB\-\-ignore\-nothing\fR
Ignore nothing, not even target/ and \.git/\.
.
.TP
\fB\-c\fR, \fB\-\-clear\fR
Clear the screen before each run\.
.
.TP
\fB\-E\fR, \fB\-\-env\-var\fR \fIkey\fR=\fIvalue\fR
Inject an environment variable\.
.
.TP
\fB\-\-env\-file\fR \fIpath\fR
Inject environment variables from a dotenv\-style file\.
.
.TP
\fB\-B\fR \fIvalue\fR
Inject \fBRUST_BACKTRACE=<value>\fR into the environment\.
.
.P
This is useful when panics are handled and you want a backtrace to be printed: usually you’d have to add \fBRUST_BACKTRACE=1\fR yourself, this shortens it to \fB\-B1\fR!
.
.TP
\fB\-L\fR \fIvalue\fR
Inject \fBRUST_LOG=<value>\fR into the environment\.
.
.TP
\fB\-\-experimental\-\-env\-changes\fR
Unstable option which will set \fBWATCHEXEC_*\fR environment variables on the command to gather information on the files changes cargo watch saw\. Do not rely on this, may disappear or change without notice\.
.
.P
Note that the files listed are not guaranteed to be the full list of files changed, nor indeed to even have been changed at all, and that this may vary between platforms\. In general, finding the list of files that changed is best done by other tools such as \fBfind\fR, to list out all the files with a modification date greater than the last known execution\.
.
.TP
\fB\-C\fR, \fB\-\-workdir\fR \fIpath\fR
Change the working directory to the \fIpath\fR given\.
.
.P
The default is the crate root, as found by \fBcargo locate\-project\fR\.
.
.TP
\fB\-\-postpone\fR
Postpone first run until a file changes\.
.
.TP
\fB\-\-poll\fR
Force use of polling for file changes\.
.
.TP
\fB\-\-no\-process\-group\fR
By default, Cargo Watch uses a process group to run the command(s)\. This disables that behaviour\.
.
.TP
\fB\-d\fR, \fB\-\-delay\fR \fIdelay\fR
File updates debounce delay in seconds (default: 0\.5)\.
.
.TP
\fB\-\-no\-restart\fR
Don’t restart command while it’s still running\.
.
.TP
\fB\-\-watch\-when\-idle\fR
Ignore events emitted while the commands run\.
.
.TP
\fB\-\-features\fR \fIfeatures\fR
List of features passed to cargo invocations\.
.
.P
The features will be passed to every supported cargo subcommand\. For example, with this command:
.
.IP "" 4
.
.nf

$ cargo watch \-\-features foo,bar \-x clean \-x build \-x doc
.
.fi
.
.IP "" 0
.
.P
Both \fBbuild\fR and \fBdoc\fR will be run with the \fBfoo\fR and \fBbar\fR features, but \fBclean\fR won\'t\.
.
.TP
\fB\-\-use\-shell\fR \fIuse\-shell\fR
Use a different shell\. E\.g\. \fB\-\-use\-shell=bash\fR\. On Windows, try \fB\-\-use\-shell=powershell\fR\.
.
.P
The special value \fBnone\fR will use no shell, but will only work with a trailing command, not \fB\-x\fR or \fB\-s\fR\.
.
.SH "EXAMPLES"
Run \fBcargo check\fR on file save:
.
.IP "" 4
.
.nf

$ cargo watch
.
.fi
.
.IP "" 0
.
.P
Run tests only:
.
.IP "" 4
.
.nf

$ cargo watch \-x test
.
.fi
.
.IP "" 0
.
.P
Run check then tests:
.
.IP "" 4
.
.nf

$ cargo watch \-x check \-x test
.
.fi
.
.IP "" 0
.
.P
Run run with arguments:
.
.IP "" 4
.
.nf

$ cargo watch \-x \'run \-\- \-\-some\-arg\'
.
.fi
.
.IP "" 0
.
.P
Run an arbitrary command:
.
.IP "" 4
.
.nf

$ cargo watch \-\- echo Hello world
.
.fi
.
.IP "" 0
.
.P
Run with features passed to cargo:
.
.IP "" 4
.
.nf

$ cargo watch \-\-features \'foo,bar\'
.
.fi
.
.IP "" 0
.
.SH "DETAILS"
.
.SS "Ignore files"
\fB\.gitignore\fR files are used by default to ignore paths to watch and trigger runs\. To stop honouring them, pass \fB\-\-no\-vcs\-ignores\fR\.
.
.P
\fB\.ignore\fR 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 \fB\-\-ignore abc\fR options on the command\-line\. Do note that \fB\.ignore\fR files may also be used by other programs, like ripgrep(1)\. To stop honouring these, pass \fB\-\-no\-dot\-ignores\fR\.
.
.P
Cargo watch also has an internal list of default ignores on top of those specified in files, like \fBtarget/\fR and \fB\.git/\fR and various other common types (logs, editor swap files, lockfiles, etc)\.
.
.P
To skip absolutely all ignores, use the \fB\-\-ignore\-nothing\fR flag\.
.
.SS "Ignore syntax"
See the \fBglob::Pattern\fR docs0 \fIhttps://doc\.rust\-lang\.org/glob/glob/struct\.Pattern\.html\fR for a more detailed specification of the glob matching syntax used for \fB\-\-ignore\fR\.
.
.P
On Windows, patterns should be specified with Windows\-style (\fB\e\e\fR) separators\. Unix\-style separators (\fB/\fR) would not match Windows paths, which could be confusing and give the appearance of commandline ignores not working\. For convenience \fB/\fR in commandline ignores are automatically translated to \fB\e\e\fR when running on Windows, but one should still try to write the correct patterns for the platform, as there may be more subtle differences\.
.
.SH "BUGS"
Please open an issue1 \fIhttps://github\.com/watchexec/cargo\-watch/issues\fR, or look through the existing ones\.
.
.P
If you want more verbose output, try running with the \fB\-\-debug\fR flag\. Note that this will also enable debug mode for watchexec\. When filing an issue, \fBmake sure to include a log with \fB\-\-debug\fR enabled so problems can be diagnosed\fR, as well as your \fB\-\-version\fR and OS\.
.
.P
\fBIf your issue is a watchexec (our main upstream) issue, open it there2 \fIhttps://github\.com/watchexec/watchexec/issues\fR directly\.\fR If you\'re not sure, feel free to open it on the cargo\-watch issue tracker, but if it \fIis\fR a watchexec issue, it will transferred over anyway\.
.
.SS "KNOWN BUGS"
In 7\.8\.0, the \fB\-\-workdir\fR option changes the directory before any other options are processed, so e\.g\. \fB\-\-watch\fR paths may not work as expected\. This is fixed upstream in Watchexec library 2\.
.
.P
In 8\.x, the \fB\-B\fR, \fB\-L\fR, \fB\-E\fR, \fB\-\-env\-var\fR, \fB\-\-env\-file\fR options inject environment variables into the main cargo\-watch process, which may be unsound in some situations and may also affect cargo\-watch itself\. This is fixed upstream in Watchexec library 2\.
.
.SH "TROUBLESHOOTING"
Always start by checking your version with \fBcargo watch \-\-version\fR and, if necessary, upgrading to the latest one by checking the website linked above\.
.
.SS "RLS is slow while using cargo watch, or vice versa, or it\'s waiting for the project lock a lot"
Cargo builds (and checks, and clippy, and tests because the tests have to be built) take out a lock on the project so two cargo instances don\'t run at the same time\.
.
.P
However, Rust Analyzer is much better at this, so use that instead of RLS\.
.
.SS "File updates seems to never trigger"
Try using \fB\-\-poll\fR to force the polling fallback\.
.
.P
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\.
.
.P
Also try using the \fB\-\-why\fR option to see if the paths you expect are changing\.
.
.SS "It runs repeatedly without touching anything"
That can happen when watching files that are modified by the command you\'re running\.
.
.P
If you\'re only running compiles or checks (i\.e\. any command that only affects the target/ folder) and you\'re using \fB\-w\fR, you might be confusing the target\-folder\-ignorer\. Check your options and paths\.
.
.P
You can also use the \fB\-\-watch\-when\-idle\fR flag to ignore any event that happens while the command is running\. \fBThis will become the default in 8\.0\.\fR
.
.SS "It runs repeatedly only touching ignored files"
Make sure the files you ignored are the only ones being touched\. Use the \fB\-\-why\fR option to see exactly which files were modified and triggered the restart\. Some programs and libraries create temporary files that may not match a simple ignore pattern\.
.
.P
As above, you can also use the \fB\-\-watch\-when\-idle\fR flag to help\.
.
.SS "I don\'t have colour in my cargo output / for cargo test"
This sometimes happens on some terminal configurations or for test harnesses\. A quick workaround (instead of going down the rabbit hole of debugging your console settings) is to pass \fB\-\-color=always\fR to the command\. E\.g\.
.
.IP "" 4
.
.nf

$ cargo watch \-x \'check \-\-color=always\'
.
.fi
.
.IP "" 0
.
.P
For test (and bench) commands, you\'ll need to pass the flag to the underlying program instead of cargo:
.
.IP "" 4
.
.nf

$ cargo watch \-x \'test \-\- \-\-color=always\'
.
.fi
.
.IP "" 0
.
.SH "AUTHOR"
Written and maintained by Félix Saparelli\.
.
.P
https://passcod\.name
.
.P
Project homepage:
.
.P
https://watchexec\.github\.io/#cargo\-watch
.
.P
Public domain\.