Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

RustyHook uses a YAML-based configuration file to define hooks and their behavior. This guide explains how to configure RustyHook for your project.

Configuration File Location

By default, RustyHook looks for configuration in the following locations (in order of precedence):

  1. Path specified by --config command-line option
  2. Path specified by RUSTYHOOK_CONFIG environment variable
  3. .rustyhook/config.yaml in the current directory
  4. .rustyhook/config.yml in the current directory
  5. .pre-commit-config.yaml (compatibility mode)

Basic Configuration Structure

A basic RustyHook configuration file looks like this:

# .rustyhook/config.yaml
hooks:
  - id: ruff
    language: python
    version: "==0.4.0"
    entry: "ruff check"
    files: "\\.py$"

  - id: biome
    language: node
    version: "^1.6.2"
    entry: "biome lint"
    files: "\\.(ts|js|json)$"

Hook Configuration Options

Each hook in the hooks array can have the following properties:

PropertyRequiredDescription
idYesUnique identifier for the hook
languageYesLanguage runtime (python, node, ruby, system)
entryYesCommand to execute
filesNoRegex pattern for files to include
excludeNoRegex pattern for files to exclude
argsNoAdditional arguments to pass to the command
versionNoVersion requirement for the tool
pass_filenamesNoWhether to pass filenames to the command (default: true)
always_runNoRun even when no matching files are changed (default: false)
verboseNoShow verbose output for this hook (default: false)
stagesNoGit stages to run on (pre-commit, pre-push, etc.)
fail_fastNoStop execution on first failure (default: false)
envNoEnvironment variables to set
working_dirNoDirectory to run the hook in

Language-Specific Configuration

Python

hooks:
  - id: ruff
    language: python
    version: "==0.4.0"  # Pinned version
    entry: "ruff check"
    files: "\\.py$"
    args: ["--fix"]

Python hooks use virtualenv to create isolated environments. The version field specifies the package version to install with pip.

Node.js

hooks:
  - id: eslint
    language: node
    version: "^8.0.0"  # Semver compatible version
    entry: "eslint"
    files: "\\.(js|jsx|ts|tsx)$"
    args: ["--fix"]

Node hooks use npm to install packages. The version field specifies the package version to install with npm.

Ruby

hooks:
  - id: rubocop
    language: ruby
    version: "~> 1.0"  # Compatible version
    entry: "rubocop"
    files: "\\.(rb)$"
    args: ["--auto-correct"]

Ruby hooks use bundler to install gems. The version field specifies the gem version to install with bundler.

System

hooks:
  - id: shellcheck
    language: system
    entry: "shellcheck"
    files: "\\.(sh)$"

System hooks use commands available on the system PATH. No environment setup is performed.

Advanced Configuration

Global Settings

You can specify global settings that apply to all hooks:

default_stages: [pre-commit, pre-push]
fail_fast: true
exclude: "^vendor/"

hooks:
  # Hook definitions...

Environment Variables

You can set environment variables for hooks:

hooks:
  - id: my-hook
    language: system
    entry: "./my-script.sh"
    env:
      DEBUG: "true"
      NODE_ENV: "development"

Working Directory

You can specify a working directory for hooks:

hooks:
  - id: frontend-lint
    language: node
    entry: "eslint"
    files: "\\.(js|jsx)$"
    working_dir: "./frontend"

Multiple Configurations

For monorepos, you can have multiple configuration files in different directories. RustyHook will use the closest configuration file to the Git root.

Configuration Templates

RustyHook provides templates to help you get started:

# Create a basic configuration
rh init

# Create a configuration with more examples
rh init --template full

Migrating from pre-commit

If you're migrating from pre-commit, you can convert your existing configuration:

rh convert --from-precommit > .rustyhook/config.yaml

Next Steps