Git Hooks: Automating Checks Before Commit and Push
Hooks run scripts at points in the Git workflow. Learn the useful ones, how to share them, and why Husky exists.
By Velloreth
What hooks are
A hook is a script Git runs at a specific point in the workflow. The scripts live in .git/hooks and are named after the event.
ls .git/hooks
# applypatch-msg.sample
# commit-msg.sample
# pre-commit.sample
# pre-push.sample
# ...
The .sample files are examples. Remove the suffix and make the file executable to activate it.
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
The useful hooks
pre-commit — runs before a commit is created. The place for fast checks: linting, formatting, and a quick test subset.
commit-msg — runs after the message is written. The place to validate the message format, such as enforcing Conventional Commits.
pre-push — runs before a push. The place for slower checks: the full test suite, a build, or a type check.
post-commit — runs after a commit. The place for notifications or a status update.
post-checkout — runs after a checkout. The place to reinstall dependencies when the lockfile changes.
pre-rebase — runs before a rebase. The place to block a rebase of a protected branch.
post-merge — runs after a merge. The place to reinstall dependencies.
A pre-commit hook
#!/bin/sh
# .git/hooks/pre-commit
# Run the linter on staged files
npx lint-staged
A more complete version that checks only staged files:
#!/bin/sh
set -e
# Get the list of staged files
staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|jsx|tsx)$' || true)
if [ -z "$staged" ]; then
exit 0
fi
echo "$staged" | xargs npx eslint
The set -e makes the script exit on the first error, which is what you want: a failing check should block the commit.
A commit-msg hook
#!/bin/sh
# .git/hooks/commit-msg
# Enforce Conventional Commits
pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.+\))?!?: .+'
if ! head -1 "$1" | grep -qE "$pattern"; then
echo "Commit message does not follow Conventional Commits."
echo "Example: feat(auth): add password reset"
exit 1
fi
The hook receives the path to the message file as $1.
A pre-push hook
#!/bin/sh
# .git/hooks/pre-push
set -e
npm run typecheck
npm test
This is slower, which is why it belongs in pre-push rather than pre-commit.
The sharing problem
.git/hooks is not committed. It is inside .git, which is not part of the repository. So a hook you write is local to your machine, and your teammates do not get it.
The solutions:
A setup script. Commit a scripts/setup-hooks.sh and document that it must be run after cloning.
#!/bin/sh
cp scripts/hooks/* .git/hooks/
chmod +x .git/hooks/*
A tool like Husky. Husky installs hooks from a committed configuration.
npm install --save-dev husky
npx husky init
This creates .husky/pre-commit, which is committed.
# .husky/pre-commit
npx lint-staged
Husky sets core.hooksPath to .husky, so Git looks there instead of .git/hooks.
A tool like pre-commit (the Python one) manages hooks from a YAML config.
# .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
lint-staged
A common pattern: run checks only on the files being committed.
{
"lint-staged": {
"*.{js,ts}": ["eslint --fix", "prettier --write"],
"*.css": ["stylelint --fix"]
}
}
This is much faster than checking the whole project, which matters because a slow pre-commit hook gets bypassed.
Hooks are not enforcement
Client-side hooks can always be bypassed.
git commit --no-verify
git push --no-verify
A developer can also delete the hook, or never run the setup script. So a hook is a convenience, not a guarantee.
For enforcement, run the same checks in CI. CI cannot be bypassed, and it runs on every pull request. The hook gives fast local feedback; CI is the gate.
The pattern that works: the hook catches problems before they are committed, and CI catches anything that slipped through. Both run the same checks, so there is no surprise.
Keeping hooks fast
A slow hook is a hook that gets bypassed.
Run checks only on changed files. lint-staged does this.
Run the fast checks in pre-commit and the slow ones in pre-push.
Cache aggressively. A type checker that re-checks the whole project on every commit is slow; an incremental one is fast.
Fail fast. Order the checks so the quickest and most likely to fail runs first.
Give a clear error. A hook that fails with a cryptic message is worse than no hook.
Server-side hooks
The hooks described so far are client-side, and they run on the developer’s machine. Server-side hooks run on the Git server and cannot be bypassed by the developer.
pre-receive — runs once when a push arrives, before any ref is updated. It can reject the whole push.
update — runs once per ref being updated. It can reject individual refs.
post-receive — runs after the refs are updated. The place for deployment, notifications, and CI triggers.
Server-side hooks are how a Git host enforces policy: requiring a signed commit, blocking a force-push to a protected branch, or rejecting a commit that fails a check. They are not available on a hosted service like GitHub, which provides its own branch protection and required status checks instead.
The distinction matters: a client-side hook is a convenience for the developer, and a server-side hook is a policy. If you need a rule that cannot be bypassed, it must be enforced on the server or in CI.
Practical guidance
- Use
pre-commitfor linting and formatting. - Use
pre-pushfor tests and type checks. - Use
commit-msgto enforce a message convention. - Share hooks with Husky or a setup script.
- Run checks only on changed files with lint-staged.
- Keep hooks fast — a slow hook gets bypassed.
- Enforce in CI, because hooks can be bypassed.
- Make the hook executable with
chmod +x.
For the related guides, see git-commit-messages-guide and git-branching-strategies. For the broader context, git-aliases-and-config and code-review-checklist.
Quotable summary
A hook is a script in .git/hooks that Git runs at a specific point, such as before a commit or before a push. Hooks are not committed, so they must be shared through a tool like Husky or a setup script, which is why Husky exists. pre-commit is the right place for fast checks like linting and formatting, and pre-push is the right place for slower checks like the test suite. A hook that is slow or unreliable gets bypassed with —no-verify, so keep it fast and correct. Client-side hooks are not enforcement, because a developer can always bypass or delete them, so run the same checks in CI, which cannot be bypassed.