My Pre-commit File I Use on Every Project

Just copy/paste my file.

Introduction

Imagine this: your code review gets derailed by trailing whitespaces, variable typos, or leftover commented-out code. Embarrassing, right? There’s a better way to keep your repo clean.

With a killer .pre-commit-config.yaml setup, you can catch these issues before they ever hit the repo.

Here’s my battle-tested configuration that’ll stop mistakes in their tracks and enforce code standards like a pro.

My Supercharged Pre-Commit Hooks

First, make sure you’ve installed pre-commit with pip install pre-commit and initialized it with pre-commit install. Then, drop this configuration into a .pre-commit-config.yaml file at the root of your project.

Here’s the lineup of hooks I swear by:

• Standard Checks (pre-commit-hooks): These cover basics like detecting merge conflicts, validating TOML files, ensuring Python syntax is correct, and more. Hooks like check-ast, check-merge-conflict, and check-toml keep your files in check.

• Actionlint (actionlint-py): Validates GitHub Actions workflows for errors before they bite.

• Gitleaks (gitleaks): It scans for accidental secret leaks-don’t let API keys slip into your commits.

• Mypy (mirrors-mypy): This static type checker catches type-related bugs in Python’s dynamic world.

• Interrogate (econchick/interrogate): Checks for missing docstrings, because undocumented code is a sin. Configured with pyproject.toml for custom rules.

• Pydoclint (jsh9/pydoclint): It ensures your docstrings match function signatures-no mismatches allowed.

• Ruff (astral-sh/ruff-pre-commit): It’s a lightning-fast linter and formatter with ruff-format and ruff hooks to keep your code polished.

• Typos (crate-ci/typos): Catches spelling errors with a low false-positive rate. Super fast, zero excuses.

• Commitizen (commitizen-tools/commitizen): It enforces consistent commit messages for cleaner history.

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: check-ast
      - id: check-merge-conflict
      - id: check-case-conflict
      - id: check-docstring-first
      - id: check-toml
      - id: debug-statements
      - id: name-tests-test
        args: ["--pytest-test-first"]

  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.6.14
    hooks:
      - id: uv-lock

  - repo: https://github.com/Mateusz-Grzelinski/actionlint-py
    rev: v1.7.7.23
    hooks:
      - id: actionlint

  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.3
    hooks:
      - id: gitleaks

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: "v1.15.0"
    hooks:
      - id: mypy

  - repo: https://github.com/econchick/interrogate
    rev: 1.7.0
    hooks:
      - id: interrogate
        args: ["-i", "-c", "pyproject.toml"]
        pass_filenames: false

  - repo: https://github.com/jsh9/pydoclint
    rev: 0.6.5
    hooks:
      - id: pydoclint
        args: ["--config", "./pyproject.toml"]

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.11.5
    hooks:
      - id: ruff-format
      - id: ruff

  - repo: https://github.com/crate-ci/typos
    rev: v1.31.1
    hooks:
      - id: typos
        args: []
        pass_filenames: false

  - repo: https://github.com/commitizen-tools/commitizen
    rev: v4.6.0
    hooks:
      - id: commitizen

Conclusion

I hope you saw some new and important hooks you can use for your next project. Especially very small and fast hooks like typos are a no-brainer for me. If you have some additional hooks write it in the comments!