Blog Set up a pre-commit hook that saves you from yourself
Set up a pre-commit hook that saves you from yourself
TL;DR A pre-commit hook runs a script before each commit and blocks it if the checks fail. Use it to lint, format, run quick tests, and scan for secrets or stray debug statements, so problems are caught before they enter your history rather than in CI or review.
The best time to catch a mistake is before it enters your git history. A pre-commit hook is the checkpoint that does it: a script git runs before every commit, blocking the commit if something is wrong. Set it up once and it quietly saves you from a whole category of small embarrassments.
What a pre-commit hook is
Git runs certain scripts automatically at points in its workflow. The pre-commit hook runs just before a commit is created. If it exits with an error, the commit is cancelled and nothing enters history. It is the last gate between your working changes and the permanent record.
What to put in it
Keep it to fast, high-value checks:
- Lint and format the staged files, so style problems never get committed.
- Scan for secrets. Catch an accidentally pasted API key or password before it lands in history, where removing it is painful.
- Catch stray debug code. Block a commit that contains a leftover
console.logor debugger statement. - Quick tests, if they run fast enough not to be annoying.
The rule is speed. A hook that takes ten seconds is one people will start bypassing, and a bypassed check is no check at all.
Setting one up
The pragmatic way is a hook manager that installs the hook from your project config, so every contributor gets it automatically when they install dependencies, rather than each person wiring up git by hand. You define the checks in a config file, and the manager runs them on the staged files before each commit. That consistency, everyone getting the same hook, is most of the value.
The escape hatch matters
Leave a way out:
git commit --no-verify
This skips the hook, which you want available for genuine emergencies. But treat it as the rare exception. If skipping becomes routine, the checks are either too slow or too strict, and either way they have stopped protecting anyone.
Why it beats catching it later
The same lint error caught in a pre-commit hook, in CI, and in code review costs wildly different amounts. In the hook it is a two-second fix before you even commit. In CI it is a failed pipeline and a context switch. In review it is a human's time spent on something a machine should have caught. The pre-commit hook moves the catch as early as it can possibly go, which is exactly where you want it.
FAQ
What is a git pre-commit hook?
It is a script git runs automatically before creating a commit. If the script exits with an error, the commit is aborted. It is your last checkpoint to catch problems before they become part of the repository history.
What should a pre-commit hook check?
Fast, high-value checks: linting and formatting, a scan for secrets or API keys, stray debug statements like console.log, and optionally quick tests. Keep it fast, since a slow hook that people bypass is worse than none.
Can I skip the hook when I need to?
Yes, git commit --no-verify skips it. That escape hatch is important, so the hook does not trap you in an emergency, but it should be the rare exception, not the habit, or the checks lose their value.