Skip to main content

Advanced Tips for Working with pre-commit

· 3 min read
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

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:

- repo: <https://github.com/PyCQA/flake8>
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: ^\.env$

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