rhysd/ cargo-husky
About the developer
135 Stars 
10 Forks 
MIT License 
92 Commits 
15 Opened issues 
Description
Setup Git hooks automatically for cargo projects with :dog:
Services available
Contributors list
Husky for Cargo :dog:
cargo-husky is a crate for Rust project managed by cargo. In short, cargo-husky is a Rust version of husky.
cargo-husky is a development tool to set Git hooks automatically on
cargo test. By hooking
pre-pushand running
cargo testautomatically, it prevents broken codes from being pushed to a remote repository.
Usage
Please add
cargo-huskycrate to
[dev-dependencies]section of your project's
Cargo.toml.
[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.
e.g.
#!/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 #set -e
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
cargo-huskyfrom your
[dev-dependencies]and remove hook scripts from
.git/hooks.
Customize behavior
Behavior of cargo-husky can be customized by feature flags of
cargo-huskypackage. You can specify them in
[dev-dependencies.cargo-husky]section of
Cargo.tomlinstead of adding
cargo-huskyto
[dev-dependencies]section.
e.g.
[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
cargo testand
cargo clippy.
All features are follows:
| Feature | Description | Default | |--------------------|---------------------------------------------------------------------|----------| |
run-for-all| Add
--alloption to command to run it for all crates in workspace | Enabled | |
prepush-hook| Generate
pre-pushhook script | Enabled | |
precommit-hook| Generate
pre-commithook script | Disabled | |
postmerge-hook| Generate
post-mergehook script | Disabled | |
run-cargo-test| Run
cargo testin hook scripts | Enabled | |
run-cargo-check| Run
cargo checkin hook scripts | Disabled | |
run-cargo-clippy| Run
cargo clippy -- -D warningsin hook scripts | Disabled | |
run-cargo-fmt| Run
cargo fmt -- --checkin hook scripts | Disabled | |
user-hooks| See below section | Disabled |
User Hooks
If generated hooks by
run-cargo-testor
run-cargo-clippyfeatures are not sufficient for you, you can create your own hook scripts and tell cargo-husky to put them into
.git/hooksdirectory.
- Create
.cargo-husky/hooks
directory at the same directory where.git
directory is put. - Create hook files such as
pre-push
,pre-commit
, ... as you like. - Give an executable permission to the files (on *nix OS).
- Write
features = ["user-hooks"]
to[dev-dependencies.cargo-husky]
section of yourCargo.toml
. - Check whether it works by removing an existing
target
directory and runcargo test
.
e.g.
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
.cargo-husky/hooksdirectory.
Ignore Installing Hooks
When you don't want to install hooks for some reason, please set
$CARGO_HUSKY_DONT_INSTALL_HOOKSenvironment variable.
CARGO_HUSKY_DONT_INSTALL_HOOKS=true cargo test
How It Works
husky utilizes npm's hook scripts, but cargo does not provide such hooks. Instead, cargo-husky sets Git hook automatically on running tests by cargo's build script feature.
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.
If
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.
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.