Cheatpre-commit Git hook manager
Light · Postcard
102 × 152 mm · PDF
Dark · Postcard
102 × 152 mm · PDF
Ink saver · Postcard
102 × 152 mm · PDF
Light · A4 landscape
297 × 210 mm · PDF
Dark · A4 landscape
297 × 210 mm · PDF
Ink saver · A4 landscape
297 × 210 mm · PDF
Light · A3 landscape
420 × 297 mm · PDF
Dark · A3 landscape
420 × 297 mm · PDF
Ink saver · A3 landscape
420 × 297 mm · PDF
Start here
pip install pre-commit
Install the tool
pre-commit sample-config > .pre-commit-config.yaml
Create a config
pre-commit install
Hook into git commit
pre-commit run --all-files
Check every file
pre-commit run <hook-id>
Run one hook
pre-commit autoupdate
Bump hook versions
SKIP=<hook-id> git commit
Skip a hook once
git commit --no-verify
Skip all hooks
Concepts
- git commit staged files
- pre-commit reads config
- Hooks cached envs
- Commit or abort
Install & Setup
pip install pre-commit
Install with pip
pre-commit --version
Show the version
pre-commit install
Install the git pre-commit hook
Run once per clone; the hook lives in .git/hooks.
pre-commit install --install-hooks
Install hook and build environments
pre-commit install -t <hook-type>
Install another hook type
E.g. pre-push or commit-msg.
pre-commit install-hooks
Build environments only
pre-commit uninstall
Remove the git hook
pre-commit sample-config
Print a starter config
pre-commit init-templatedir <dir>
Hooks for every new clone
Pair with git config init.templateDir.
pre-commit install -f
Overwrite an existing hook
Running
pre-commit runRun hooks on staged files
pre-commit run --all-files
Run on every tracked file
pre-commit run <hook-id>
Run a single hook
pre-commit run <hook-id> --all-files
One hook on all files
pre-commit run --files <file>...
Run on named files
pre-commit run --from-ref <ref> --to-ref
<ref>
Run on files changed between refs
Typical CI use: --from-ref origin/main --to-ref HEAD.
pre-commit run --show-diff-on-failure
Print the diff after failures
pre-commit run --hook-stage <stage>
Run hooks of one stage
Use manual for hooks that never run automatically.
pre-commit run -v
Show output of passing hooks
pre-commit run --fail-fast
Stop at the first failure
pre-commit -c <file> run
Use another config file
-c is a global option and goes before run.
Skipping
SKIP=<id>,<id> git commit
Skip hooks by id
Ids are comma-separated; other hooks still run.
git commit --no-verify
Skip all git hooks
Also skips non-pre-commit hooks.
SKIP=<id> pre-commit run -a
Skip a hook in a manual run
Updating & Cache
pre-commit autoupdate
Bump every rev to the latest tag
pre-commit autoupdate --repo <url>
Update one repo only
pre-commit autoupdate --freeze
Pin commit SHAs, keep tag as comment
pre-commit autoupdate --bleeding-edge
Use latest HEAD, not latest tag
pre-commit autoupdate -j <n>
Update repos in parallel
pre-commit try-repo <repo> <hook-id>
Test a hook repo without adding it
Uses the repo's HEAD unless --ref is given.
pre-commit clean
Delete the whole cache
pre-commit gcDelete unused cached repos
pre-commit validate-config <file>
Check a config file
pre-commit migrate-config
Convert old list-style config
pre-commit validate-manifest <file>
Check .pre-commit-hooks.yaml
Config file
| Key | Meaning |
|---|---|
repos |
list of hook sources (required) |
default_stages |
stages hooks use by default |
default_install_hook_types |
what install sets up |
default_language_version |
e.g. python: python3.12 |
files / exclude |
global regex filters |
fail_fast |
stop after first failing hook |
minimum_pre_commit_version |
refuse older versions |
| Key | Meaning |
|---|---|
repo |
git URL, local or meta |
rev |
tag or SHA to use, not a branch |
hooks |
list of hook mappings |
| Key | Meaning |
|---|---|
id |
which hook (required) |
args |
extra arguments before filenames |
files / exclude |
regex on file paths |
types / types_or |
filter by file type |
stages |
git stages it runs on |
additional_dependencies |
extra packages for the env |
always_run |
run even without matching files |
pass_filenames |
local hooks: pass files or not |
language_version |
override the runtime version |
| Stage | Fires on |
|---|---|
pre-commit |
git commit (default) |
commit-msg |
after message is written |
pre-push |
git push |
pre-merge-commit |
before a merge commit |
manual |
only if you ask for it |
Local & meta hooks
repo: localHooks defined in your own repo
Needs id, name, entry, language and files or types.
language: unsupported
Run a tool already on the PATH
Older configs say system; same meaning.
repo: metaBuilt-in checks of the config itself
check-hooks-apply
Meta hook: every hook matches files
check-useless-excludes
Meta hook: every exclude matches
CI
pre-commit run --all-files --show-diff-on-failure
Typical CI step
pre-commit run --from-ref origin/main --to-ref HEAD
Check only the changed files
PRE_COMMIT_HOME=<dir>
Move the cache directory
Default is ~/.cache/pre-commit; cache it between CI runs.
Recipes
# .pre-commit-config.yamlrepos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v5.0.0 hooks: - id: end-of-file-fixer - id: trailing-whitespace - id: check-yaml - repo: local hooks: - id: pytest name: pytest entry: pytest -q language: unsupported pass_filenames: false stages: [pre-push]pre-commit installpre-commit run --all-filesgit add -ugit commit -m "Apply pre-commit fixes"pre-commit try-repo <url> <hook-id> --all-files
