Pre-commit hooks: catch mistakes before they reach the repo
Short answer: A pre-commit hook is a script Git runs every time someone commits. If it fails, the commit stops. Use it to run fast checks, such as formatting, linting, catching debug leftovers and obvious secrets, on the files being committed, so problems are fixed on the developer's machine in seconds instead of in code review or production. Manage hooks with a shared tool so the whole team runs the same checks, keep them quick, and repeat the important checks in CI because hooks can be skipped.
Why catch problems at commit time
Small teams lose time to the same avoidable issues: a pull request full of formatting changes, a stray console.log, a missing semicolon that breaks the build, a .env file committed by accident. Each is easy to fix but annoying to find later, and some, like a committed API key, are expensive.
Pre-commit hooks move the cheapest checks to the earliest possible moment. The developer sees the problem before the code leaves their machine, while the change is fresh in their mind.
How Git hooks work
Git's documentation on hooks describes them as programs in a hooks directory that run at certain points in Git's workflow. The pre-commit hook runs before Git asks for the commit message; if it exits with a non-zero status, the commit is aborted. The same documentation notes it can be bypassed with git commit --no-verify.
By default, hooks live in .git/hooks, which isn't part of the repository, so they aren't shared with teammates. Git's core.hooksPath setting lets you point to a different folder, which can be committed. Most teams use a hook manager instead.
Use a hook manager
Hook managers keep hook configuration in the repository and install it for each developer. Popular options include:
- pre-commit, a language-agnostic framework. Its documentation describes adding a
.pre-commit-config.yamlfile listing the hooks, runningpre-commit installonce to set up the Git hook, and then checks run automatically on every commit.pre-commit autoupdateupdates hook versions. - Husky with lint-staged, common in JavaScript projects, which installs hooks through the package manager and runs tools only on staged files.
- Lefthook and similar tools, which work across languages.
Pick the one that fits your stack. What matters is that hook setup is part of the repository and one command away for a new developer.
What to run in a pre-commit hook
Good candidates are fast and focused on the changed files:
- Formatting with your project's formatter, such as Prettier or Black, ideally fixing files automatically.
- Linting for obvious errors, such as unused variables or calls to undefined functions.
- Trailing whitespace, merge conflict markers and large files.
- Debug leftovers, like
debuggerstatements orconsole.login production code. - Secret detection, using a scanner that looks for key patterns and high-entropy strings.
- Config file syntax, such as checking YAML and JSON parse.
An illustrative pre-commit configuration using its standard hooks repository:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-merge-conflict
- id: check-added-large-files
Pin versions with rev and update them deliberately.
What not to run
Keep slow work out of the hook:
- Full test suites, which can take minutes.
- Type checks across the whole project, if they're slow.
- Builds, end-to-end tests and deployments.
If a hook takes more than a few seconds, people start using --no-verify, and then it protects nothing. Run the slow checks in CI and, if useful, in a pre-push hook.
Make failures easy to understand
A hook that fails with a wall of output gets bypassed. Configure tools to print the file and line, and fix what they can automatically, so the developer just re-stages and commits again. Add a line to the README explaining what each hook checks and how to run them all manually, for example with pre-commit run --all-files. When a check proves noisy, with false alarms that waste time, tune or remove it rather than letting the team learn to ignore failures.
Keep CI as the source of truth
Because hooks can be skipped, not installed, or run with outdated versions, CI should run the same checks on every pull request. Many hook managers can run in CI with the same configuration file, so the rules are identical locally and on the server. Then:
- The hook gives fast, local feedback.
- CI enforces the rule for everyone.
If CI fails on something the hook would have caught, that's a sign someone hasn't installed hooks; make installation part of the onboarding steps.
Rolling hooks out to an existing project
Adding a formatter hook to an old codebase can produce huge changes the first time it touches each file. A smoother path:
- Agree on the tools and settings with the team.
- Format the whole codebase in one dedicated commit, separate from feature work.
- Optionally record that commit in a file your Git hosting uses to ignore it in blame views.
- Add the hooks and CI checks.
- Add more checks gradually, starting with the least disruptive.
A worked example
Take a hypothetical Hobart tourism-booking startup with three developers. Code reviews were dominated by formatting comments, and twice in a month a test API key was committed and had to be rotated. The team added a pre-commit configuration with a formatter, a linter on staged files, standard file checks and a secret scanner, documented pre-commit install in the README and ran the same configuration in CI. Formatting comments disappeared from reviews, and the next accidental key was stopped before the commit was created.
FAQ
Can developers skip the hooks?
Yes, with --no-verify. That's why CI must run the same checks.
Do hooks work on Windows?
Most hook managers support Windows, macOS and Linux. Test with your team's machines.
Should hooks fix files automatically?
For formatting, yes; it saves time. For linting, report problems and let the developer decide.
Will hooks slow down every commit?
Only slightly if you keep them to fast, staged-file checks.
If your team keeps catching the same mistakes in review, ask us to set up commit checks.