holocron/plugins/git/docs/research/docs/pre-commit/cli-reference.md

topic, source_keys

topic	source_keys
cli-reference	context7-pre-commit-com pre-commit-com

Exit codes

Code	Meaning
0	All hooks passed
1	Hook(s) failed or files were modified
3	Unexpected internal error
130	Interrupted (Ctrl+C)

pre-commit run

Run hooks against files.

pre-commit run                                   # staged files only (normal commit flow)
pre-commit run --all-files                       # entire working tree
pre-commit run check-yaml                        # single hook by ID
pre-commit run --files path/to/file.py           # specific files
pre-commit run --from-ref HEAD~3 --to-ref HEAD   # diff range (CI use)
pre-commit run --hook-stage pre-push             # specific lifecycle stage
pre-commit run --show-diff-on-failure            # print diff when hook fails
pre-commit run --verbose                         # always show hook output

For CI, prefer --from-ref/--to-ref over --all-files on large repos. Cache $PRE_COMMIT_HOME keyed on .pre-commit-config.yaml hash.

pre-commit install

Wire pre-commit into .git/hooks/.

pre-commit install                               # default: pre-commit stage
pre-commit install -f                            # overwrite existing hooks
pre-commit install --install-hooks              # pre-create all environments now
pre-commit install -t pre-commit -t pre-push    # multiple stages
pre-commit install --allow-missing-config       # silently skip if no config file

Must be run once per clone. Re-run after changing default_install_hook_types.

pre-commit uninstall

pre-commit uninstall
pre-commit uninstall -t pre-push

pre-commit autoupdate

Update rev values in .pre-commit-config.yaml to the latest tag.

pre-commit autoupdate                            # latest tag for all repos
pre-commit autoupdate --bleeding-edge           # use default branch HEAD
pre-commit autoupdate --freeze                  # pin to commit SHA (reproducible)
pre-commit autoupdate --repo https://github.com/pre-commit/pre-commit-hooks  # single repo
pre-commit autoupdate -j 4                      # parallel fetches (v3.3.0+)

This modifies .pre-commit-config.yaml in-place. A skill updating an existing config should call this rather than manually editing rev values.

pre-commit validate-config

Validate .pre-commit-config.yaml schema. Non-zero exit means the file is invalid.

pre-commit validate-config
pre-commit validate-config path/to/other-config.yaml

A skill must call this after writing or modifying a config before considering the task complete.

pre-commit validate-manifest

Validate a .pre-commit-hooks.yaml hook definition file.

pre-commit validate-manifest .pre-commit-hooks.yaml

pre-commit try-repo

Test a hook repo without adding it to the config.

pre-commit try-repo https://github.com/pre-commit/pre-commit-hooks
pre-commit try-repo ../local-hook-repo --all-files --verbose
pre-commit try-repo ../hook-repo specific-hook-id --verbose

Supports all run options. Use this in a skill to smoke-test a hook before writing it to config.

pre-commit sample-config

Print a minimal starter config to stdout.

pre-commit sample-config > .pre-commit-config.yaml

pre-commit install-hooks

Pre-create all hook environments without running any hooks.

pre-commit install-hooks

pre-commit gc

Remove unused cached hook environments (safe to run at any time).

pre-commit gc

pre-commit clean

Wipe all cached environments. Forces full rebuild on next run.

pre-commit clean

SKIP environment variable

Skip specific hooks by ID without modifying config. Comma-separated, exact IDs, no spaces.

SKIP=flake8,check-yaml git commit -m "wip"

CI recipe

# GitHub Actions
- name: Cache pre-commit envs
  uses: actions/cache@v3
  with:
    path: ~/.cache/pre-commit
    key: pre-commit|${{ hashFiles('.pre-commit-config.yaml') }}

- name: Run pre-commit
  run: pre-commit run --from-ref ${{ github.event.pull_request.base.sha }} --to-ref HEAD