{"id":13478442,"url":"https://github.com/watchexec/cargo-watch","last_synced_at":"2025-04-08T20:09:22.805Z","repository":{"id":19361555,"uuid":"22601397","full_name":"watchexec/cargo-watch","owner":"watchexec","description":"Watches over your Cargo project's source.","archived":false,"fork":false,"pushed_at":"2024-10-28T14:13:30.000Z","size":943,"stargazers_count":2767,"open_issues_count":29,"forks_count":82,"subscribers_count":11,"default_branch":"8.x","last_synced_at":"2024-10-29T11:12:34.914Z","etag":null,"topics":["cargo","cargo-command","command-line-tool","developer-tools","rust","watch-files"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/watchexec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-04T11:12:19.000Z","updated_at":"2024-10-28T15:19:38.000Z","dependencies_parsed_at":"2024-06-20T05:47:42.424Z","dependency_job_id":"c3ed0f0c-ec7f-409d-b9c1-1963facb8aa0","html_url":"https://github.com/watchexec/cargo-watch","commit_stats":{"total_commits":424,"total_committers":37,"mean_commits":11.45945945945946,"dds":"0.21226415094339623","last_synced_commit":"b905a3f982f21fcea5cb643f0dad073a0cac4b24"},"previous_names":["passcod/cargo-watch"],"tags_count":75,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watchexec%2Fcargo-watch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watchexec%2Fcargo-watch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watchexec%2Fcargo-watch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watchexec%2Fcargo-watch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/watchexec","download_url":"https://codeload.github.com/watchexec/cargo-watch/tar.gz/refs/heads/8.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247918921,"owners_count":21018044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cargo","cargo-command","command-line-tool","developer-tools","rust","watch-files"],"created_at":"2024-07-31T16:01:57.079Z","updated_at":"2025-04-08T20:09:22.787Z","avatar_url":"https://github.com/watchexec.png","language":"Rust","funding_links":[],"categories":["Rust","Catalog","Development tools"],"sub_categories":["automation","Build system"],"readme":"# $ cargo watch\n\n[![Crate release version](https://flat.badgen.net/crates/v/cargo-watch)](https://crates.io/crates/cargo-watch)\n[![Crate license: CC0 1.0](https://flat.badgen.net/github/license/watchexec/cargo-watch)](https://creativecommons.org/publicdomain/zero/1.0/)\n[![Crate download count](https://flat.badgen.net/crates/d/cargo-watch)](https://crates.io/crates/cargo-watch)\n[![CI status](https://github.com/watchexec/cargo-watch/actions/workflows/check.yml/badge.svg)](https://github.com/watchexec/cargo-watch/actions/workflows/check.yml)\n\nCargo Watch watches over your project's source for changes, and runs Cargo\ncommands when they occur.\n\nIf you've used [nodemon], [guard], or [entr], it will probably feel familiar.\n\n**I recommend [Bacon] or [Watchexec] instead.** (see below for more)\n\n[nodemon]: http://nodemon.io/\n[entr]: https://github.com/eradman/entr\n[guard]: http://guardgem.org/\n[Bacon]: https://dystroy.org/bacon/\n\n- In the public domain / licensed with CC0.\n\n## Maintenance\n\nCargo Watch is on life support: it will not receive further updates, but does remain available.\n\nI (@passcod) currently have very little time to dedicate to unpaid OSS.\nThere is a significant amount of work I deem required to get Watchexec (the library) to a good-enough state to bring its improvements to Cargo Watch, and that has been the case for years without a realistic end in sight.\nI have dwindling motivation in the face of having spent 10 years on or around this project and its dependencies (it was a long while ago, but once upon a time the Notify library was spun off from Cargo Watch!), when at the very start, this tool was only made to clear a quick hurdle that I'd encountered while trying to code _other, probably more interesting, yet now long-forgotten_ Rust adventures.\n\nHowever, not all is lost, dear users.\nFor almost the entire life of the project, I have had a thought: that someone with more resources, skill, time, and/or the benefit of hindsight would come around and make something _better_.\nGranted, I thought this would happen to Notify.\nBut Notify has persisted, has been passed on to live a long life, and instead the contender is [Bacon].\n\nI have had no involvement in Bacon.\nYet it is everything I have wanted to achieve in Cargo Watch.\nIndeed some five years ago I started development on a Cargo Watch replacement I called \"Overwatch\", which would have a TUI, a tasks file, a rich pager, and more long-desired features.\nThat never eventuated, though a lot of the low-level improvements that I wrote in preparation for Overwatch \"made it\" into Notify version 5 and the Watchexec library version 2.\nBacon today is what I wanted Overwatch to be.\n\nLet's face it: Cargo Watch has gone through too many incremental changes, with too little overarching design.\nIt sports no less than four different syntaxes to run commands.\nIts lackluster filtering options can be obnoxious to use.\nPager support is non-existent, sometimes requiring arcane invocations to get right.\nIt can conflict with Rust Analyzer (which didn't exist 10 years ago!), though that has improved a lot over the years.\n\nIt's time to let it go.\nUse [Bacon].\nRemember Cargo Watch.\n\n## Install\n\n\u003ca href=\"https://repology.org/project/cargo-watch/versions\"\u003e\u003cimg align=\"right\" src=\"https://repology.org/badge/vertical-allrepos/cargo-watch.svg\" alt=\"Packaging status\"\u003e\u003c/a\u003e\n\nWith [cargo-binstall](https://github.com/ryankurte/cargo-binstall):\n\n```console\n$ cargo binstall cargo-watch\n```\n\nFrom source:\n\n```console\n$ cargo install cargo-watch --locked\n```\n\nOr clone and build with `$ cargo build` then place in your $PATH.\n\nYou can also install from the pre-built binaries available **[on the release page][releases]**.\n\n[releases]: https://github.com/watchexec/cargo-watch/releases/latest\n\n### Auxiliary\n\nThis repository contains a [manual page](./cargo-watch.1) and\n[Zsh completions](./completions) that you may want to install.\n\n## Usage\n\nBy default, it runs `check`. You can easily override this, though:\n\n```\n$ cargo watch [-x command]...\n```\n\nA few examples:\n\n```\n# Run tests only\n$ cargo watch -x test\n\n# Run check then tests\n$ cargo watch -x check -x test\n\n# Run run with arguments\n$ cargo watch -x 'run -- --some-arg'\n\n# Run an arbitrary command\n$ cargo watch -- echo Hello world\n\n# Run with features passed to cargo\n$ cargo watch --features \"foo,bar\"\n```\n\nThere's a lot more you can do! Here's a copy of the help:\n\n```\nUSAGE:\n    cargo watch [FLAGS] [OPTIONS]\n\nFLAGS:\n    -c, --clear              Clear the screen before each run\n    -h, --help               Display this message\n        --ignore-nothing     Ignore nothing, not even target/ and .git/\n        --debug              Show debug output\n        --why                Show paths that changed\n    -q, --quiet              Suppress output from cargo-watch itself\n        --no-vcs-ignores       Don’t use .gitignore files\n        --no-dot-ignores          Don’t use .ignore files\n        --no-restart         Don’t restart command while it’s still running\n    -N, --notify             Send a desktop notification when watchexec notices a change\n                             (experimental, behaviour may change)\n        --poll               Force use of polling for file changes\n        --postpone           Postpone first run until a file changes\n        --skip-local-deps    Don't try to find local dependencies of the current crate and watch\n                             their working directories. Only watch the current directory.\n    -V, --version            Display version information\n        --watch-when-idle    Ignore events emitted while the commands run.\n\nOPTIONS:\n    -x, --exec \u003ccmd\u003e...            Cargo command(s) to execute on changes [default: check]\n    -s, --shell \u003ccmd\u003e...           Shell command(s) to execute on changes\n    -d, --delay \u003cdelay\u003e            File updates debounce delay in seconds [default: 0.5]\n        --features \u003cfeatures\u003e      List of features passed to cargo invocations\n    -i, --ignore \u003cpattern\u003e...      Ignore a glob/gitignore-style pattern\n    -B \u003crust-backtrace\u003e            Inject RUST_BACKTRACE=VALUE (generally you want to set it to 1)\n                                   into the environment\n        --use-shell \u003cuse-shell\u003e    Use a different shell. E.g. --use-shell=bash\n    -w, --watch \u003cwatch\u003e...         Watch specific file(s) or folder(s). Disables finding and\n                                   watching local dependencies.\n    -C, --workdir \u003cworkdir\u003e        Change working directory before running command [default: crate\n                                   root]\n\nARGS:\n    \u003ccmd:trail\u003e...    Full command to run. -x and -s will be ignored!\n\nCargo commands (-x) are always executed before shell commands (-s). You can use the `-- command`\nstyle instead, note you'll need to use full commands, it won't prefix `cargo` for you.\n\nBy default, the workspace directories of your project and all local dependencies are watched,\nexcept for the target/ and .git/ folders. Your .ignore and .gitignore files are used to filter\npaths.\n\nOn Windows, patterns given to -i have forward slashes (/) automatically\nconverted to backward ones (\\) to ease command portability.\n```\n\n### Ignore files\n\n`.gitignore` files are used by default to ignore paths to watch and trigger\nruns. To stop honouring them, pass `--no-vcs-ignores`.\n\n`.ignore` files in the same syntax are also used by default. This file can be\nused to specify files that should be ignored by cargo watch but checked into\ngit, without constantly adding `--ignore abc` options on the command-line. Do\nnote that `.ignore` files may also be used by other programs, like\n[ripgrep](https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md#automatic-filtering).\nTo stop honouring these, pass `--no-dot-ignores`.\n\nCargo watch also has an internal list of default ignores on top of those\nspecified in files, like `target/` and `.git/` and various other common types\n(logs, editor swap files, lockfiles, etc).\n\nTo skip absolutely all ignores, use the `--ignore-nothing` flag.\n\n### Ignore syntax\n\nSee the [Glob patterns page][globdoc] for a description of how they work in the\ncontext of this tool. That’s the syntax used for the `--ignore` option.\n\nAdditionally, some specific quirks and behaviours:\n\n- On Windows, patterns should be specified with Windows-style (`\\\\`) separators.\nUnix-style separators (`/`) would not match Windows paths, which could be\nconfusing and give the appearance of commandline ignores not working.\n\n- From Cargo Watch 7.0.0, `/` in commandline ignores are automatically translated\nto `\\\\` when running on Windows, but one should still try to write the correct\npatterns for the platform, as there may be more subtle differences.\n\n- From Cargo Watch 7.3.0, `--ignore` patterns were fixed to provide better\nexperience with directory matching. Previously, ignoring a folder would need\nunyieldy `-i folder/**` patterns; now that is handled internally, and only `-i\nfolder` is needed for the same effect.\n\n[globdoc]: https://watchexec.github.io/docs/glob-patterns.html\n\n### Reloading servers seamlessly\n\nCargo Watch pairs very well with [systemfd]/[Catflap], tools for Unixy platforms that\nlets one spawn a socket before the watcher runs that Rust servers can then bind\nto, avoiding request-dropping and the infamous ADDRINUSE error. For example:\n\n```\n$ systemfd --no-pid -s http::5000 -- cargo watch -x run\n```\n\n[Catflap]: https://github.com/watchexec/catflap\n[systemfd]: https://github.com/mitsuhiko/systemfd\n\nOf course, if you don't need to guard against these issues or don't want to\nmodify your program to grab sockets instead of ports, you can use Cargo Watch\nas-is: it will happily just restart your server normally.\n\n### Restarting an application only if the build/check succeeds\n\nSupervising and starting/restarting/stopping long-running processes is explicitly not within Cargo Watch's remit.\nInstead, you should use a process manager.\nOn most Linuxes, `systemd-run --user` is greatly useful here.\nOn other platforms, a tool such as [pm2] or [pmc] can be used.\n\n[pm2]: https://pm2.keymetrics.io\n[pmc]: https://lib.rs/crates/pmc\n\n#### With systemd-run\n\nStart the application service:\n\n```\n$ systemd-run --user --pty --unit myappserver cargo run\n```\n\nRestart after a successful compile:\n\n```\n$ cargo -x check -x build -s 'systemctl --user restart myappserver'\n```\n\n#### With [pm2]\n\nStart the application service:\n\n```\n$ pm2 start --name myappserver cargo run\n$ pm2 logs -f myappserver\n```\n\nRestart after a successful compile:\n\n```\n$ cargo -x check -x build -s 'pm2 restart myappserver'\n```\n\n#### Or with cargo watch alone\n\nThis uses a \"trigger file\" that's watched by a second cargo watch to manage a process.\n\nStart the application service:\n\n```\n$ touch .trigger\n$ cargo watch --no-vcs-ignores -w .trigger -x run\n```\n\nRestart after a successful compile:\n\n```\n$ cargo watch -x check -x build -s 'touch .trigger'\n```\n\nThe `--no-vcs-ignores` flag ensures that you can safely add `.trigger` to your\n`.gitignore` file to avoid mistakenly committing it.\n\n## Troubleshooting\n\nIn all cases, start by checking your version with `cargo watch --version` and,\nif necessary, upgrading to [the latest one][releases].\n\n### RLS is slow while using cargo watch, or vice versa, or it's waiting for the project lock a lot\n\nCargo builds (and checks, and clippy, and tests because the tests have to be\nbuilt) take out a lock on the project so two cargo instances don't run at the\nsame time.\n\nHowever, Rust Analyzer is much better at this, so use that instead of RLS.\n\n### On Windows 7 (or lower): \"failed to add to job object: Access denied (OS Error 5)\"\n\nCargo Watch versions 5.0.0 and up (and Watchexec versions 1.3.0 and up) **[do\nnot support Windows 7 or lower][i-69].** Support _will not_ be added. Issues for\nWindows \u003c=7 will be closed. If it works, lucky you, but that is not intentional.\n\n[i-69]: https://github.com/watchexec/cargo-watch/issues/69\n\n### I want to run cargo-watch directly, without going through cargo\n\nYou can! But you'll have to specify the `watch` subcommand as the first\nargument, like so:\n\n```\n$ /path/to/cargo-watch watch -x build\n```\n\n### I want to run cargo-watch outside of a Cargo project\n\nThat's not supported. If you have a good reason to use a Cargo-specific tool\noutside a Cargo project, please open an issue! Otherwise, you'll probably be\nbest served with using [Watchexec].\n\n### If file updates seems to never trigger\n\nTry using `--poll` to force the polling fallback.\n\nIf that still doesn't work, and you're using an editor that does \"safe saving\",\nlike IntelliJ / PyCharm, you may have to disable \"safe saving\" as that may\nprevent file notifications from being generated properly.\n\nAlso try using the `--why` option to see if the paths you expect are changing.\n\n### Linux: If it fails to watch some deep directories but not others / \"No space left on device\"\n\nYou may have hit the inotify watch limit. [Here's a summary of what this means\nand how to increase it.][inotify limit]\n\n[inotify limit]: https://watchexec.github.io/docs/inotify-limits.html\n\n### Docker: it's not responding correctly to signal or has trouble managing processes\n\nCargo Watch (and Watchexec underlying) does not currently support running as PID 1.\nIt will probably work for basic uses, but you should consider using a supervisor,\ninit, or shell to handle PID 1 concerns. With Docker, the `--init` option may be useful.\n\nSee [watchexec#140](https://github.com/watchexec/watchexec/issues/140) for more.\n\n### Docker: running cargo commands over a mount is very slow\n\nThis isn't really a Cargo Watch issue, but when your host system is not Linux,\nrunning commands from inside the container on a volume or bind mount from the\nhost will perform very badly due to filesystem indirection. Consider [building\noutside the mount if possible][i-219]:\n\n```dockerfile\n# ...\nRUN mkdir -p /build\nWORKDIR `/src`\nENTRYPOINT cargo watch -C /build --manifest-path=/src/Cargo.toml -- cargo run\n```\n\nOr similarly with [`CARGO_TARGET_DIR`](https://doc.rust-lang.org/cargo/reference/config.html#buildtarget-dir).\n\n```dockerfile\n# ...\nRUN mkdir -p /build\nWORKDIR `/src`\nENV CARGO_TARGET_DIR=/build\nENTRYPOINT cargo watch -- cargo run\n```\n\n[i-219]: https://github.com/watchexec/cargo-watch/issues/219\n\nYou may also have issues where it's the file updates that aren't triggering in\na timely manner, not the compilation taking a long time. In that case, you\nshould run Cargo Watch or [Watchexec] _outside_ of Docker, on the host, and\nsignal the container for restart or reload.\n\n### If you want to only recompile one Cargo workspace member crate\n\nWatching one or more specific workspace member [is not natively supported yet][i-52],\nalthough you can use `-w folder` to approximate it.\n\nWatching the entire workspace and running a command in one member is done via\nthe usual `-p` option _on the child command_:\n\n```\n$ cargo watch -x 'build -p subcrate'\n```\n\n[i-52]: https://github.com/watchexec/cargo-watch/issues/52\n\n### If it runs repeatedly without touching anything\n\nThat can happen when watching files that are modified by the command you're\nrunning.\n\nIf you're only running compiles or checks (i.e. any command that only affects\nthe target/ folder) and you're using `-w`, you might be confusing the\ntarget-folder-ignorer. Check your options and paths.\n\nYou can also use the `--watch-when-idle` flag to ignore any event that happens\nwhile the command is running.\n\n### If it runs repeatedly only touching ignored files\n\nMake sure the files you ignored are the only ones being touched. Use the\n`--why` option to see exactly which files were modified and triggered the\nrestart. Some programs and libraries create temporary files\nthat may not match a simple ignore pattern.\n\nAs above, you can also use the `--watch-when-idle` flag to help.\n\n### I don't have colour in my cargo output / for cargo test\n\nThis sometimes happens on some terminal configurations or for test harnesses.\nA quick workaround (instead of going down the rabbit hole of debugging your\nconsole settings) is to pass `--color=always` to the command. E.g.\n\n```\n$ cargo watch -x 'check --color=always'\n```\n\nFor test (and bench) commands, you'll need to pass the flag to the underlying\nprogram instead of cargo:\n\n```\n$ cargo watch -x 'test -- --color=always'\n```\n\n### I want to compile my build with additional features\n\n```\n$ cargo watch --features foo,bar\n```\n\nwill run `cargo check --features foo,bar` on every watched change.\n\nThe `--features` will be passed to every supported `cargo` subcommand.\n\n```\n$ cargo watch --features foo,bar -x build -x doc\n```\n\nwill run both `build` and `doc` with the `foo` and `bar` features.\n\n### Something not covered above / I have a feature request\n\nPlease [open an issue][watch-issues], or look through the existing ones. You\nmay also want to look through [issues for the Notify library][notify-issues]\nthis tool depends on, or the [issues for the Watchexec tool][watchexec-issues]\nthat we use under the covers (where I am also a maintainer).\n\nIf you want more verbose output, try running with the `--debug` flag. Note that\nthis will also enable debug mode for watchexec. When filing an issue, **make\nsure to include a log with `--debug` enabled so problems can be diagnosed.**\n\n**If your issue is a watchexec issue, open it there directly.** If you're not\nsure, feel free to open it here, but if it _is_ a watchexec issue, it will get\nclosed in favour of the upstream issue.\n\n[notify-issues]: https://github.com/notify-rs/notify/issues\n[watch-issues]: https://github.com/watchexec/cargo-watch/issues\n[watchexec-issues]: https://github.com/watchexec/watchexec/issues\n\n### I want to embed Cargo Watch in my own (Rust) tool\n\nIt is not recommended to do that directly. You may of course call `cargo-watch`\nas any other program, and technically it exposes an (undocumented) library that\ncould be directly / statically embedded. If you have no other option, that may\nbe your best bet.\n\nHowever, for most cases, consider building on top of [Watchexec] instead. That\nis itself built on [Notify], and both of these can be used as Rust libraries.\n\n- If you want to build a tool that runs, restarts, and otherwise manages\n  commands in response to file changes, you'll most probably want to use\n  **Watchexec**.\n\n- If you want to build a tool that responds to file changes, but does not need\n  to run commands, or does so in a way that is not well-supported by Watchexec,\n  then **Notify** is your ticket.\n\n[Notify]: https://github.com/notify-rs/notify\n[Watchexec]: https://github.com/watchexec/watchexec\n\n### Wait, is this just a wrapper on top of watchexec?\n\nKind of! [Watchexec] does a really good job of watching files and running\ncommands and all the details that go with this. Cargo Watch uses the Watchexec\nlibrary interface and calls it with its own custom options, defaults, and\nparticularities, so you can just run `cargo-watch` in your project and be in\nbusiness.\n\nWhen asking questions and/or filing bugs, keep in mind that Cargo Watch and\nWatchexec share the same maintainer at the moment (but Notify does not,\nanymore)!\n\n## About\n\nCreated by [Félix Saparelli][passcod] and [awesome contributors][contributors].\n\n[contributors]: https://github.com/watchexec/cargo-watch/network/members\n[passcod]: https://passcod.name\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatchexec%2Fcargo-watch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwatchexec%2Fcargo-watch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatchexec%2Fcargo-watch/lists"}