Advanced Tips for Working with pre-commit
As a senior or Python developer, refining your team’s pre-commit setup can drastically improve code quality, consistency, and onboarding speed. Below are key tips and techniques to supercharge your pre-commit experience.
1. Use Centralized Shared Configuration
Maintain a single .pre-commit-config.yaml in a shared internal repository and symlink or copy it into each repo via automation (e.g., cookiecutter or setup scripts). This ensures consistency across microservices or projects.
In a shared repo
repos:
- repo: <https://github.com/psf/black>
rev: 24.3.0
hooks:
- id: black
2. Pin Versions Explicitly for Reproducibility
Always pin hook versions using rev:. Never use rev: master or rev: main. It ensures that all contributors and CI environments use the same tool versions.
✅ Good:
- repo: <https://github.com/PyCQA/flake8>
rev: 6.1.0
🚫 Bad:
rev: master
3. Fail Fast and Fix Automatically
Use args to enforce automatic fixes when possible:
- repo: <https://github.com/psf/black>
rev: 24.3.0
hooks:
- id: black
args: [“—fast”]
Also add tools like isort, pyupgrade, autoflake, and ruff in auto-fix mode.
4. Use additional_dependencies to Customize Behavior
Need specific plugin versions or configs?
- repo: <https://github.com/pre-commit/mirrors-flake8>
rev: v6.1.0
hooks:
- id: flake8
additional_dependencies: [‘flake8-bugbear’, ‘flake8-docstrings’]
5. Create Local Hooks for Project-Specific Scripts
Use local hooks to lint .env files, check API contracts, or run custom project health checks.
- repo: local
hooks:
- id: check-env-file
name: “Check .env formatting”
entry: ./scripts/lint_env.sh
language: system
files:
6. Combine with CI for Full Coverage
Run pre-commit run —all-files in CI to enforce checks on pushed code, even if a dev forgot to install the hooks locally.
Example GitHub Action:
- name: Run Pre-Commit
run: |
pip install pre-commit
pre-commit run —all-files
7. Use Stages to Separate Expensive Checks
Some hooks are slow (e.g., full tests, security scans). Run them on manual or push stage only.
hooks:
- id: safety stages: [push]
8. Cache .pre-commit in CI to Speed Up Pipelines
In GitHub Actions:
- uses: actions/cache@v3
with:
path: ~/.cache/pre-commit
key: pre-commit-${{ hashFiles(‘.pre-commit-config.yaml’) }}
9. Document Setup Clearly for New Developers
Add a make install-hooks command or a setup.sh script:
!/bin/bash
pip install pre-commit
pre-commit install
pre-commit autoupdate
10. Use pre-commit autoupdate Regularly
Run pre-commit autoupdate monthly to keep dependencies fresh. Consider automating it via Dependabot or a weekly cron CI job.
Final Thoughts
pre-commit isn’t just about linting - it’s a platform for enforcing all kinds of code standards. Use it to maintain quality, speed up onboarding, and enforce consistent practices across your team and infrastructure.
For further reading:
pre-commit official docs Awesome pre-commit hooks Using pre-commit with poetry