50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
---
|
|
topic: overview
|
|
source_keys:
|
|
- 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`.
|