customizing-precommit.md

Customizing the pre-commit hook

Forge ships no config system for the pre-commit hook. The hook file is a plain bash script and is yours to edit.

Fork-friendly note. This file documents the canonical pattern. Forks that ship a different default sequence can replace it; the structural conventions (marker line, repo-specific extensions before/after forge-precommit) stay useful.

To add a repo-specific step, open .githooks/pre-commit:

#!/usr/bin/env bash
# forge:precommit-managed v1
# Pre-commit dispatcher. Generated by install-forge-githooks.
# ... comments ...
set -euo pipefail
forge-precommit "$@"

Add bash lines before forge-precommit to run them first (failure aborts before forge's checks); add lines after to run only if forge's checks passed.

#!/usr/bin/env bash
# forge:precommit-managed v1
set -euo pipefail

# Repo-specific: run mypy on changed Python files (runs first)
mypy --strict $(git diff --cached --name-only --diff-filter=ACM | grep '\.py$') || exit 1

# Repo-specific: secret scan
gitleaks protect --staged --quiet || exit 1

# Forge's canonical sequence
forge-precommit "$@"

# Anything below runs only if forge-precommit succeeded
./scripts/my-post-check.sh

The # forge:precommit-managed v1 marker on line 2 tells install-forge-githooks the file was originally forge-generated. The version token lets the installer upgrade an outdated managed hook automatically while honoring user edits — delete or change the marker and the file is considered yours, never touched without --force.