Setup Git hooks automatically for cargo projects with :dog:
cargo-husky is a development tool to set Git hooks automatically on
cargo test. By hooking
cargo testautomatically, it prevents broken codes from being pushed to a remote repository.
[dev-dependencies]section of your project's
[dev-dependencies] cargo-husky = "1"
Then run tests in your project directory.
$ cargo test
Check Git hook was generated at
.git/hooks/pre-push. cargo-husky generates a hook script which runs
cargo testby default.
#!/bin/sh # # This hook was set by cargo-husky v1.0.0: https://github.com/rhysd/cargo-husky#readme # Generated by script /path/to/cargo-husky/build.rs # Output at /path/to/target/debug/build/cargo-husky-xxxxxx/out #
echo '+cargo test' cargo test
Note: cargo-husky does nothing on
cargo testwhen - hook script was already generated by the same version of cargo-husky - another hook script put by someone else is already there
To uninstall cargo-husky, please remove
[dev-dependencies]and remove hook scripts from
Behavior of cargo-husky can be customized by feature flags of
cargo-huskypackage. You can specify them in
Cargo.tomlinstead of adding
[dev-dependencies.cargo-husky] version = "1" default-features = false # Disable features which are enabled by default features = ["precommit-hook", "run-cargo-test", "run-cargo-clippy"]
This configuration generates
.git/hooks/pre-commitscript which runs
All features are follows:
| Feature | Description | Default | |--------------------|---------------------------------------------------------------------|----------| |
--alloption to command to run it for all crates in workspace | Enabled | |
pre-pushhook script | Enabled | |
pre-commithook script | Disabled | |
post-mergehook script | Disabled | |
cargo testin hook scripts | Enabled | |
cargo checkin hook scripts | Disabled | |
cargo clippy -- -D warningsin hook scripts | Disabled | |
cargo fmt -- --checkin hook scripts | Disabled | |
user-hooks| See below section | Disabled |
If generated hooks by
run-cargo-clippyfeatures are not sufficient for you, you can create your own hook scripts and tell cargo-husky to put them into
.cargo-husky/hooksdirectory at the same directory where
.gitdirectory is put.
pre-commit, ... as you like.
features = ["user-hooks"]to
[dev-dependencies.cargo-husky]section of your
targetdirectory and run
your-repository/ ├── .git └── .cargo-husky └── hooks ├── post-merge └── pre-commit
[dev-dependencies.cargo-husky] version = "1" default-features = false features = ["user-hooks"]
cargo-husky inserts an information header to copied hook files in
.git/hooks/in order to detect self version update.
Note that, when
user-hooksfeature is enabled, other all features are disabled. You need to prepare all hooks in
When you don't want to install hooks for some reason, please set
CARGO_HUSKY_DONT_INSTALL_HOOKS=true cargo test
Build scripts are intended to be used for building third-party non-Rust code such as C libraries. They are automatically run on compiling crates.
cargo-huskycrate is added to
dev-dependenciessection, it is compiled at running tests. At the timing, build script is run and sets Git hook automatically. The build script find the
.gitdirectory to put hooks based on
$OUT_DIRenvironment variable which is automatically set by
cargo-husky puts Git hook file only once for the same version. When it is updated to a new version, it overwrites the existing hook by detecting itself was updated.
cargo-husky is developed on macOS and tested on Linux/macOS/Windows with 'stable' channel Rust toolchain.