Why Your Team Needs pre-commit

It’s easy to overlook pre-commit when you’re already using GitHub and have a continuous integration (CI) pipeline humming along. Why add another tool to your stack? Isn’t this just another layer of complexity?

In fact, when used well, pre-commit can be the simplest and most effective way to eliminate whole categories of bugs, style issues, and config drift before they even enter your Git history. pre-commit is not a replacement for CI; it’s a way to shift quality left, right into your fingertips as you write and commit code.

Let’s take a closer look.

pre-commit is a simple and effective way to improve code quality for your whole team.

What is pre-commit, and what does it actually do?

pre-commit is a framework for managing and maintaining hooks for your Git repositories. Git itself allows you to define “hooks” at various points in your workflow, like right before you make a commit (pre-commit), after you push (post-push), and more. These are just scripts that Git runs automatically.

The pre-commit framework makes it dead simple to:

• Set up a shared list of checks across your team

• Automatically run those checks before every commit

• Keep those checks up to date and versioned, just like your code

So what kinds of things should you run at commit time? Think of anything you’d normally catch in a code review, or worse, in CI: formatting issues, unused imports, syntax errors, inconsistent line endings, leftover debug statements.

With pre-commit, those problems are fixed or flagged before the code is even committed.

How does pre-commit fit into GitHub and CI?

Let’s say your team already uses GitHub Actions to run linters and tests on pull requests. That’s great, but there are two big problems with doing everything in CI:

1. Feedback is slow
   A GitHub Action might take a few minutes to run. pre-commit runs instantly, in your terminal, before the code leaves your machine.

2. CI doesn’t prevent bad commits
   If you commit broken code and forget to push, the code still lives in your history. Or if the CI flags it after you open a PR, now you're juggling comments, review delays, and annoying rebase steps.

With pre-commit, these problems mostly go away. You’ll likely still want to use GitHub Actions to double-check things (especially if someone bypasses the hooks), but by that point, most issues will already be fixed locally.

You can even run the same pre-commit config in CI, so there’s no duplication of effort.

OK, but how do I convince the rest of my team to use this?

The best way is to start by using it yourself and sharing the wins. Show them:

• How pre-commit auto-fixes formatting with tools like isort and linters

• How it prevents you from committing bad code by accident

• How easy it is to set up—literally two commands to install and configure

Then make it a team habit. Add your .pre-commit-config.yaml file to the repo, and run pre-commit install as part of your project’s setup instructions. You can even enforce it with a CI check using pre-commit run --all-files to ensure everything passes on every pull request.

Want to really lock it in? Add a make lint or make format command to your Makefile that runs the hooks locally, and include it in your pre-merge checklist.

Click here to learn about how to improve how code reviews work in your team.

Step-by-step: Using pre-commit on your laptop

Here’s how to get up and running in five minutes:

1. Install pre-commit

pip install pre-commit

2. Create a config file

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/psf/black
    rev: 24.3.0
    hooks:
      - id: black
  - repo: https://github.com/pre-commit/mirrors-isort
    rev: v5.12.0
    hooks:
      - id: isort
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.0
    hooks:
      - id: ruff

3. Install the hooks

pre-commit install

4. Test it out

git commit -m "Test pre-commit"

If you’ve got any formatting issues, they’ll be fixed or blocked before the commit goes through.

5. Run on all files (for bootstrapping)

pre-commit run --all-files

When we say “bootstrapping” here, we mean applying your hooks to all files in your repo the first time you set up pre-commit. This brings the entire codebase up to standard right away, so future commits start clean.

Now every time you commit, your code will be checked automatically. It’s like having a mini CI pipeline built into your terminal.

Why this matters for your team

If everyone on your team is using pre-commit, the benefits compound:

• Cleaner commits and less noisy diffs

• Fewer "oops" moments caught in PRs

• Less back-and-forth during code reviews

• Confidence that code is consistently formatted and error-free

And when paired with tools like isort and linters, pre-commit helps enforce a strong baseline of code quality across your whole stack. These tools work together to sort imports, enforce consistent formatting, and catch subtle bugs and performance issues—all without manual effort.

It’s a small investment up front, but it pays off with every commit.

Want to spend less time fixing code style and more time writing great code?
Open a free Caparra account to get access to DevOps tools, tutorials like this, and the latest in automation to help your team focus on what really matters.