---
slug: "husky-rs"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/pplmx/husky-rs@main/README.md"
repo: "https://github.com/pplmx/husky-rs"
source_file: "README.md"
branch: "main"
---
# husky-rs

[![CI](https://github.com/pplmx/husky-rs/workflows/CI/badge.svg)](https://github.com/pplmx/husky-rs/actions)
[![Coverage](https://codecov.io/gh/pplmx/husky-rs/graph/badge.svg)](https://codecov.io/gh/pplmx/husky-rs)
[![Crates.io](https://img.shields.io/crates/v/husky-rs.svg)](https://crates.io/crates/husky-rs)
[![Documentation](https://docs.rs/husky-rs/badge.svg)](https://docs.rs/husky-rs)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](#license)

`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:

   ```sh
   # 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:

   ```sh
   mkdir -p .husky
   ```

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

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

4. Install hooks:

   ```sh
   cargo build
   ```

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

   ```sh
   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](https://github.com/j178/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)

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

Configure hook types via standard prek settings:

```yaml
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](https://github.com/pplmx/husky-rs/blob/HEAD/docs/usage.md#switching-modes) 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](https://git-scm.com/docs/githooks).

If you encounter any unsupported hooks, please [open an issue](https://github.com/pplmx/husky-rs/issues).

### Configuration

To skip hook installation (useful in CI environments):

```sh
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:

```sh
cargo install husky-rs
```

The CLI provides helpful commands:

```sh
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:

```rust
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](https://docs.rs/husky-rs) 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](https://github.com/pplmx/husky-rs/blob/HEAD/docs/usage.md) - Installation, configuration, and advanced usage
- [Examples](https://github.com/pplmx/husky-rs/blob/HEAD/docs/examples.md) - 13 ready-to-use hook examples
- [Troubleshooting](https://github.com/pplmx/husky-rs/blob/HEAD/docs/troubleshooting.md) - Solutions to common issues
- [Development](https://github.com/pplmx/husky-rs/blob/HEAD/docs/development.md) - Contributing guide

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/pplmx/husky-rs/blob/HEAD/CONTRIBUTING.md) 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](https://github.com/pplmx/husky-rs/tree/HEAD/LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](https://github.com/pplmx/husky-rs/tree/HEAD/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](https://github.com/pplmx/husky-rs/blob/HEAD/CHANGELOG.md).

## Acknowledgments

- Inspired by [cargo-husky](https://github.com/rhysd/cargo-husky)
- Thanks to the Rust community for their amazing tools and libraries