pre-commit repos and rev: Pinning Hook Versions

Each entry under repos has a repo url and a rev that pins the exact version of those hooks.

Pinning rev is what makes pre-commit reproducible. The rev is a git tag or commit sha that pre-commit checks out before building the hook environment.

What it does

pre-commit clones each repo url and checks out rev. The hooks listed for that repo come from its .pre-commit-hooks.yaml at that ref. Because rev is pinned, every machine and every CI run uses the identical hook version.

Common usage

.pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0            # a tag
    hooks:
      - id: check-yaml
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: 1c4f4a4f8f...     # a frozen commit sha (from --freeze)
    hooks:
      - id: ruff

Keys

Key	What it does
repo	Git url of the hook repository
rev	Tag or commit sha to check out
hooks	List of hook ids to enable from that repo
repo: local	Special value for hooks defined inline in this repo
repo: meta	Built-in meta hooks (check-hooks-apply, check-useless-excludes)

In CI

Keep rev pinned, never floating, so a new upstream release cannot silently change a build. Let pre-commit autoupdate move pins forward in a reviewable pull request. Caching ~/.cache/pre-commit on the rev means the checked-out hook envs persist between jobs.

Common errors in CI

"[INFO] Initializing environment" followed by "fatal: reference is not a tree" means rev points at a sha or tag that no longer exists (deleted or force-pushed); update it. "Using a v2 ... mutable reference" warnings appear if rev is a branch name instead of a tag; pin to a tag or sha. An unreachable repo url fails the clone on offline runners.