holocron/plugins/git/docs/research/docs/pre-commit/overview.md

topic, source_keys

topic	source_keys
overview	context7-pre-commit-com pre-commit-com

What pre-commit is

Pre-commit is a framework for managing and executing git hooks. Hooks run automatically at specific git lifecycle points (pre-commit, pre-push, commit-msg, etc.) against staged or changed files. Each hook is pulled from a versioned external git repo; pre-commit clones and caches it in ~/.cache/pre-commit (or $PRE_COMMIT_HOME) and manages isolated execution environments per hook. No system-wide language runtimes are required for most hooks.

Key concepts

Config file: .pre-commit-config.yaml at the repo root. This is the single source of truth for all hooks.

Hook repos vs local hooks: Most hooks live in external git repos (pinned by rev). Local hooks (repo: local) live in the same repo and run system tools or scripts directly.

rev must be immutable: Always use a tag or commit SHA, never a branch. autoupdate will not work correctly with branches.

File targeting: Hooks receive only the files that match their files regex AND types filter. pre-commit run --all-files bypasses staging and runs against all files in the tree.

Staged files only by default: When run via git hooks, pre-commit passes only staged files. This means fixers (e.g. trailing-whitespace) modify files but the commit is blocked — the user must re-stage and recommit.

PRE_COMMIT=1 is set in the environment whenever a hook is executing (since v2.5.0). Hooks can use this to detect they are running under pre-commit.

identify library determines file types. Inspect what tags a file has with identify-cli <file>. Types include: file, text, binary, executable, python, json, yaml, shell, javascript, typescript, markdown, toml, xml, etc.

Mental model for a skill/agent

A pre-commit agent operates on three artefacts:

1. .pre-commit-config.yaml — the config it creates or modifies
2. .pre-commit-hooks.yaml — a hook manifest if the agent is also authoring hooks in the repo
3. The git hooks in .git/hooks/ — installed by pre-commit install

The safe workflow for a skill:

1. Write or modify .pre-commit-config.yaml
2. Run pre-commit validate-config — abort if non-zero
3. Run pre-commit run --all-files — surface hook failures
4. Run pre-commit autoupdate if updating rev values
5. Run pre-commit install once to wire hooks into git

Cache and environment

Default cache: ~/.cache/pre-commit or $XDG_CACHE_HOME/pre-commit. Override: export PRE_COMMIT_HOME=/path/to/cache. Pre-create all environments: pre-commit install-hooks. Wipe and rebuild: pre-commit clean. Remove unused only: pre-commit gc.