Set rev in your pre-commit configuration to a tag or full commit SHA, never a branch. The pre-commit site says it assumes rev is an immutable ref and caches on that basis. Then run pre-commit autoupdate on a schedule to move hooks to their latest tags, and review the diff like any other dependency change.
Hooks are code you run on every commit
Pre-commit hooks execute on developer machines and in CI. They are linters and formatters that can read your whole working tree. Their versions deserve the same care as libraries, yet the config file is often untouched for years.
What rev means
According to the pre-commit documentation, rev is the revision or tag that pre-commit clones. It assumes the value is an immutable ref, such as a tag or SHA, and will cache based on that. A branch name or HEAD is not supported and only represents the state of that mutable ref at install time. It also will not update automatically. The tool intentionally provides no facility for an unpinned latest version.
What autoupdate does
The docs describe pre-commit autoupdate as auto-updating the config to the latest versions of the hook repositories. By default each repository moves to its latest tag on the default branch. Options change that:
| Option | Effect |
|---|---|
| bleeding-edge | Update to the newest commit on the default branch |
| freeze | Write commit hashes into rev in place of tag names |
| repo | Limit the update to specific repositories |
When tags tie, pre-commit prefers tags containing a dot.
Tag or frozen SHA
Tags are readable but can in principle be moved by the hook's maintainer. A frozen SHA is exact. Running autoupdate with freeze gives you the exact commit and a comment of the tag name, which is a good compromise.
pre-commit autoupdate --freeze
A routine
- Run autoupdate with freeze monthly, or let a bot do it.
- Open a pull request with the changed rev lines.
- Read what changed in each hook before merging, especially new hooks that call the network.
- Run pre-commit run on all files once, and fix any new findings in a separate commit.
- Keep language runtimes for hooks documented, since some hooks build their own environments.
Dependabot lists pre-commit among its supported ecosystems for version updates, so you can automate step one without custom scripts.
What not to do
Do not point rev at main to avoid maintenance. It looks convenient and gives you the least predictable build. Do not skip the review step either, because a formatter update can touch hundreds of files.
Safeguard's pull request gates and dependency scanning run alongside hooks, catching what a local check does not. Try a free scan at gold.safeguard.sh/scan.
Common mistakes
The usual ones are pointing rev at a branch, never running autoupdate and merging an autoupdate pull request without reading it. A formatter bump can rewrite many files, so land that change on its own to keep history readable.
Quick check
Can rev be a branch name?
The pre-commit documentation says using a branch name or HEAD is not supported and only reflects the state at installation time.
What does autoupdate freeze do?
It writes commit hashes into rev in place of tag names.
Sources
Last reviewed: 19 October 2026.
