⚙️ Options

See Configuration for the complete configuration system (hierarchy, file discovery, merging).

Global Hook Settings

Skip All Hooks

Disable all hooks globally.

Default: false

hooks:
  skip_all: true

export GUARDY_HOOKS_SKIP_ALL=true

guardy hooks --skip-all

Parallel Execution

Run hook commands in parallel.

Default: true

hooks:
  parallel: true

export GUARDY_HOOKS_PARALLEL=true

guardy hooks --parallel

Continue on Error

Continue executing other hooks even if one fails.

Default: false

hooks:
  continue_on_error: true

export GUARDY_HOOKS_CONTINUE_ON_ERROR=true

Auto Stage

Automatically stage files modified by hook commands.

Default: false

hooks:
  auto_stage: true

export GUARDY_HOOKS_AUTO_STAGE=true

Per-Hook Configuration

Configure individual hooks (pre-commit, commit-msg, pre-push, etc).

Hook-Level Parallel

Override global parallel setting for a specific hook.

Default: Inherits from global parallel setting

hooks:
  pre-commit:
    parallel: true  # Run commands in parallel for this hook

Skip Hook

Disable a specific hook without removing its configuration.

Default: false

hooks:
  pre-commit:
    skip: true  # Skip this hook entirely

Built-in Actions

Use Guardy's built-in actions (scan_secrets, conventional_commits).

hooks:
  pre-commit:
    builtin: ["scan_secrets"]

  commit-msg:
    builtin: ["conventional_commits"]

Conventional Commits Config

Configure the conventional_commits builtin.

hooks:
  commit-msg:
    builtin: ["conventional_commits"]
    conventional-commits:
      allowed_types: ["feat", "fix", "docs", "chore"]
      enforce_scope: true

Custom Commands

Define custom commands to run in hooks.

Basic Command

hooks:
  pre-commit:
    commands:
      format:
        run: dprint fmt
        description: "Format code with dprint"

File Globbing

Run commands only on matching files.

Default: [] (empty - matches all files)

hooks:
  pre-commit:
    commands:
      typescript-check:
        run: tsc --noEmit
        glob: "src/**/*.{ts,tsx}"

Stage Fixed Files

Auto-stage files modified by the command.

Default: false

hooks:
  pre-commit:
    commands:
      format:
        run: prettier --write
        glob: "*.{js,ts,json}"
        stage_fixed: true

Continue on Error

Don't fail the hook if this command fails.

Default: false

hooks:
  pre-commit:
    commands:
      lint:
        run: cargo clippy
        continue_on_error: true

All Files vs Staged

Process all files instead of just staged ones.

Default: false (only staged files)

hooks:
  pre-commit:
    commands:
      check:
        run: cargo check
        all_files: true  # Run on all files, not just staged

Command Priority

Control execution order (lower priority runs first).

Default: 0

hooks:
  pre-commit:
    commands:
      format:
        run: dprint fmt
        priority: 1  # Runs first

      lint:
        run: cargo clippy
        priority: 2  # Runs after format

Environment Variables

Set environment variables for a command.

hooks:
  pre-commit:
    commands:
      test:
        run: cargo test
        env:
          RUST_LOG: debug
          DATABASE_URL: "sqlite::memory:"

Working Directory

Set custom working directory for command execution.

hooks:
  pre-commit:
    commands:
      frontend-build:
        run: npm run build
        root: "./frontend"

Conditional Execution

Skip or only run commands based on conditions.

hooks:
  pre-commit:
    commands:
      rust-check:
        run: cargo check
        only: ["*.rs"]  # Only run if .rs files changed

      docs-build:
        run: mdbook build
        skip: ["main"]  # Skip on main branch

Interactive Commands

Allow command to receive stdin/stdout.

Default: false

hooks:
  pre-commit:
    commands:
      manual-review:
        run: review-script
        interactive: true

Custom Failure Message

Show custom message when command fails.

hooks:
  pre-commit:
    commands:
      security-check:
        run: guardy scan
        fail_text: "Security vulnerabilities detected! Please fix before committing."

Hook Scripts

Execute script files (Lefthook compatibility).

hooks:
  pre-commit:
    scripts:
      "validate.js":
        runner: node
        env:
          NODE_ENV: development

      "check.py":
        runner: python3

Complete Example

hooks:
  # Global settings
  parallel: true
  continue_on_error: false

  # Pre-commit hook
  pre-commit:
    parallel: true
    builtin: ["scan_secrets"]
    commands:
      format:
        run: dprint fmt
        glob: ["*.{ts,js,json,md}"]
        stage_fixed: true
        priority: 1

      lint:
        run: cargo clippy
        glob: ["*.rs"]
        priority: 2

  # Commit message validation
  commit-msg:
    builtin: ["conventional_commits"]
    conventional-commits:
      allowed_types: ["feat", "fix", "docs", "chore", "test"]
      enforce_scope: false

  # Pre-push hook
  pre-push:
    commands:
      test:
        run: cargo test
        all_files: true
        fail_text: "Tests failed! Fix before pushing."

⚙️ Options

On this page