husky-rs

husky-rs is a Git hooks management tool for Rust projects, inspired by Husky.

Features

• 🚀 Zero-configuration - Just add the dependency and create hooks
• ⚡ Automatic installation - Hooks configure on cargo build or cargo test
• 🔄 Smart rerun detection - No need for cargo clean when updating hooks
• 🦀 prek integration - Supports prek.toml and pre-commit YAML configs
• 🎯 All 27 Git hooks supported - Client-side and server-side hooks
• 🌍 Cross-platform - Works on Unix-like systems and Windows
• 🛠️ Optional CLI tool - husky init, husky add, husky list commands
• 📚 Optional library API - Helper functions for advanced use cases

Quick Start

1. Adding husky-rs to your project:

   You have several options:

   # Option 1: Add as a Regular Dependency
   cargo add husky-rs
   
   # Option 2: Add as a Dev Dependency
   cargo add --dev husky-rs
   
   # Option 3: Use the Main Branch
   cargo add --git https://github.com/pplmx/husky-rs --branch main
   cargo add --dev --git https://github.com/pplmx/husky-rs --branch main
   

2. Create hooks directory:

   mkdir -p .husky
   

3. Add a hook (e.g., pre-commit):

   echo '#!/bin/sh\necho "Running pre-commit hook"' > .husky/pre-commit
   

4. Install hooks:

   cargo build
   

   Or if you're using as a dev-dependency:

   cargo test
   

Tip: If you add this library to the [dependencies] section, both cargo build and cargo test will work. However, if it's added under [dev-dependencies], only cargo test will function as expected.

Usage

prek Compatibility

If the repository contains prek.toml, .pre-commit-config.yaml, or .pre-commit-config.yml, husky-rs delegates hook installation completely to prek in native mode:

• Clears core.hooksPath (if previously set)
• Runs prek install --git-dir .git → shims go to .git/hooks/
• Pre-existing .husky/ directories are ignored (left on disk, not used)

cargo install prek
# Or, if cargo-binstall is available: cargo binstall prek
cargo build

Configure hook types via standard prek settings:

default_install_hook_types: [pre-commit, commit-msg, pre-push]
repos:
  # ...

If prek is unavailable, the config is invalid, or installation fails, the Cargo build fails with the underlying prek error. Set NO_HUSKY_HOOKS=1 to skip installation explicitly.

When no supported prek config exists, husky-rs retains its original standalone .husky/ behavior. See the usage guide for migration steps.

Supported Git Hooks

In standalone mode, husky-rs supports all standard Git hooks by setting core.hooksPath to .husky. This means you can also place helper scripts (e.g., .husky/_helpers.sh) in the same directory and source them from your hooks.

For a complete list, refer to the Git documentation.

If you encounter any unsupported hooks, please open an issue.

Configuration

To skip hook installation (useful in CI environments):

NO_HUSKY_HOOKS=1 cargo build

You can also set this in your environment or CI configuration.

Optional Tools

CLI Tool

For added convenience, install the husky command-line tool:

cargo install husky-rs

The CLI provides helpful commands:

husky init              # Create .husky directory
husky add pre-commit    # Add hook from smart template
husky list              # List all installed hooks
husky help              # Show help

Note: The CLI is completely optional - the core functionality works without it!

Library API

For advanced use cases, husky-rs exposes utility functions:

use husky_rs::{hooks_dir, should_skip_installation, is_valid_hook_name};

// Check if hook installation should be skipped
if !should_skip_installation() {
    let hooks_path = hooks_dir(".");
    println!("Hooks directory: {}", hooks_path.display());
}

// Validate a hook name
if is_valid_hook_name("pre-commit") {
    println!("Valid hook!");
}

See API documentation for more details.

Note: You don't need to call any functions for basic usage - just add the dependency!

Best Practices

• Keep hooks lightweight to avoid slowing down Git operations
• Use hooks for tasks like running tests, linting code, and validating commit messages
• Non-zero exit status in a hook script will abort the Git operation

Documentation

📖 Complete guides for all users:

• Usage Guide - Installation, configuration, and advanced usage
• Examples - 13 ready-to-use hook examples
• Troubleshooting - Solutions to common issues
• Development - Contributing guide

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to submit pull requests, report issues, or suggest improvements.

License

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Changelog

For a detailed history of changes to this project, please refer to our CHANGELOG.md.

Acknowledgments

• Inspired by cargo-husky
• Thanks to the Rust community for their amazing tools and libraries