Awesome Open Source
Awesome Open Source

Husky for Cargo šŸ¶

Crates.io Build Status on Linux/macOS Build status on Windows

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-push and running cargo test automatically, it prevents broken codes from being pushed to a remote repository.

Usage

Please add cargo-husky crate 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 test by 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 test when

  • 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-husky from your [dev-dependencies] and remove hook scripts from .git/hooks.

Japanese blogpost

Customize behavior

Behavior of cargo-husky can be customized by feature flags of cargo-husky package. You can specify them in [dev-dependencies.cargo-husky] section of Cargo.toml instead of adding cargo-husky to [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-commit script which runs cargo test and cargo clippy.

All features are follows:

Feature Description Default
run-for-all Add --all option to command to run it for all crates in workspace Enabled
prepush-hook Generate pre-push hook script Enabled
precommit-hook Generate pre-commit hook script Disabled
postmerge-hook Generate post-merge hook script Disabled
run-cargo-test Run cargo test in hook scripts Enabled
run-cargo-check Run cargo check in hook scripts Disabled
run-cargo-clippy Run cargo clippy -- -D warnings in hook scripts Disabled
run-cargo-fmt Run cargo fmt -- --check in hook scripts Disabled
user-hooks See below section Disabled

User Hooks

If generated hooks by run-cargo-test or run-cargo-clippy features are not sufficient for you, you can create your own hook scripts and tell cargo-husky to put them into .git/hooks directory.

  1. Create .cargo-husky/hooks directory at the same directory where .git directory is put.
  2. Create hook files such as pre-push, pre-commit, ... as you like.
  3. Give an executable permission to the files (on *nix OS).
  4. Write features = ["user-hooks"] to [dev-dependencies.cargo-husky] section of your Cargo.toml.
  5. Check whether it works by removing an existing target directory and run cargo 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-hooks feature is enabled, other all features are disabled. You need to prepare all hooks in .cargo-husky/hooks directory.

Ignore Installing Hooks

When you don't want to install hooks for some reason, please set $CARGO_HUSKY_DONT_INSTALL_HOOKS environment 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-husky crate is added to dev-dependencies section, it is compiled at running tests. At the timing, build script is run and sets Git hook automatically. The build script find the .git directory to put hooks based on $OUT_DIR environment 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.

License

MIT


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
rust (4,317)Ā 
git (776)Ā 
hook (122)Ā 
cargo (66)Ā 
development-tools (31)Ā 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising šŸ“¦Ā 10
All Projects
Application Programming Interfaces šŸ“¦Ā 124
Applications šŸ“¦Ā 192
Artificial Intelligence šŸ“¦Ā 78
Blockchain šŸ“¦Ā 73
Build Tools šŸ“¦Ā 113
Cloud Computing šŸ“¦Ā 80
Code Quality šŸ“¦Ā 28
Collaboration šŸ“¦Ā 32
Command Line Interface šŸ“¦Ā 49
Community šŸ“¦Ā 83
Companies šŸ“¦Ā 60
Compilers šŸ“¦Ā 63
Computer Science šŸ“¦Ā 80
Configuration Management šŸ“¦Ā 42
Content Management šŸ“¦Ā 175
Control Flow šŸ“¦Ā 213
Data Formats šŸ“¦Ā 78
Data Processing šŸ“¦Ā 276
Data Storage šŸ“¦Ā 135
Economics šŸ“¦Ā 64
Frameworks šŸ“¦Ā 215
Games šŸ“¦Ā 129
Graphics šŸ“¦Ā 110
Hardware šŸ“¦Ā 152
Integrated Development Environments šŸ“¦Ā 49
Learning Resources šŸ“¦Ā 166
Legal šŸ“¦Ā 29
Libraries šŸ“¦Ā 129
Lists Of Projects šŸ“¦Ā 22
Machine Learning šŸ“¦Ā 347
Mapping šŸ“¦Ā 64
Marketing šŸ“¦Ā 15
Mathematics šŸ“¦Ā 55
Media šŸ“¦Ā 239
Messaging šŸ“¦Ā 98
Networking šŸ“¦Ā 315
Operating Systems šŸ“¦Ā 89
Operations šŸ“¦Ā 121
Package Managers šŸ“¦Ā 55
Programming Languages šŸ“¦Ā 245
Runtime Environments šŸ“¦Ā 100
Science šŸ“¦Ā 42
Security šŸ“¦Ā 396
Social Media šŸ“¦Ā 27
Software Architecture šŸ“¦Ā 72
Software Development šŸ“¦Ā 72
Software Performance šŸ“¦Ā 58
Software Quality šŸ“¦Ā 133
Text Editors šŸ“¦Ā 49
Text Processing šŸ“¦Ā 136
User Interface šŸ“¦Ā 330
User Interface Components šŸ“¦Ā 514
Version Control šŸ“¦Ā 30
Virtualization šŸ“¦Ā 71
Web Browsers šŸ“¦Ā 42
Web Servers šŸ“¦Ā 26
Web User Interface šŸ“¦Ā 210