pre-commit Hooks
You know the feeling: you push, the CI goes red, and the failure is something tiny - a stray trailing space, an unformatted file, a debug print you forgot, an AWS key you pasted into a config to test. Five minutes of waiting to learn you broke a rule a machine could have caught in half a second. pre-commit hooks move that check to the moment you commit, on your machine, before the mistake ever leaves your laptop.
This guide is about stopping the bad commit at the door - automatically, the same way for everyone on the team, with one small config file checked into the repo.
How to read this
Go in order. Phase 1 builds the mental model: what a git hook actually is, and why a framework sits on top of it. Phase 2 is the everyday loop: writing .pre-commit-config.yaml, installing, and what happens on each commit. Phase 3 is the reality: bypassing, CI enforcement, and the gotchas that bite teams. If you only have ten minutes, read Phase 1 - the rest will make sense once the model clicks.
The phases
- Phase 1: What a Hook Actually Is - the mental model: git hooks, and the framework that tames them.
- Phase 2: The Config and the Commit Loop -
.pre-commit-config.yaml, installing, and running on staged files. - Phase 3: Bypassing, CI, and the Gotchas - fixing vs failing, enforcement, and what breaks in real teams.