Pre-commit hooks catch code quality issues before they're even committed, providing the fastest possible feedback loop — earlier and cheaper to fix than issues caught later in CI. This guide covers setting them up effectively.
Why Pre-Commit Is Faster Feedback Than CI
A CI pipeline check happens after you've already pushed code, potentially minutes later; a pre-commit hook runs locally in seconds, catching issues before they even leave your machine — complementary to, not a replacement for, CI-level checks (see How to Set Up Automated Testing in a CI Pipeline).
Installing the pre-commit Framework
pip install pre-commit --break-system-packagesCreating a .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-filesInstalling the Hooks into Your Git Repository
pre-commit installNow these checks run automatically before every commit, blocking the commit if any check fails.
Adding a Linter Hook
- repo: https://github.com/psf/black
rev: 24.1.1
hooks:
- id: blackAutomated code formatting (here, Python's Black formatter) as a pre-commit hook ensures consistent code style is enforced automatically, rather than relying on manual reviewer feedback for style issues.
Adding a Secrets Detection Hook
- repo: https://github.com/Yelp/detect-secrets
rev: v1.4.0
hooks:
- id: detect-secretsSee How to Secure API Keys and Prevent Credential Leakage — catching accidentally-included secrets at commit time, before they ever reach version control history, is far preferable to discovering and remediating an exposure after the fact.
Running Hooks Manually Against All Files
pre-commit run --all-filesUseful when first adopting pre-commit on an existing repository, to check/fix existing files rather than only newly-committed ones.
Balancing Hook Comprehensiveness with Speed
Pre-commit hooks should be fast — a slow pre-commit process (running the full test suite, for example) frustrates developers and gets bypassed; reserve genuinely slow checks for CI, keeping pre-commit hooks focused on fast, high-value checks (formatting, linting, secrets detection, basic syntax validation).
Handling Team Adoption
Ensure all team members actually install the hooks (pre-commit install) — consider documenting this in your project's onboarding/README, and potentially enforcing the same checks in CI as a backstop for anyone who bypasses or hasn't installed local hooks.
Allowing Deliberate Bypass When Genuinely Necessary
git commit --no-verify -m "Emergency hotfix"Occasionally a genuine emergency warrants bypassing hooks — understand this exists, but treat it as a rare exception, not a routine habit that undermines the value of having hooks in the first place.
Common Errors
Hooks installed but not actually running on commit — verify pre-commit install was actually run in this specific repository clone; the hook installation is per-clone, not automatically inherited from a cloned repository's configuration file alone.
Continue Reading
- How to Secure API Keys and Prevent Credential Leakage
- How to Set Up Automated Testing in a CI Pipeline
- How to Use Git Hooks for Automated Tasks
Browse more articles in DevOps & CI/CD.
