Skip to content
Velloreth
Developer Tools 5 min read

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

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-commit for linting and formatting.
  • Use pre-push for tests and type checks.
  • Use commit-msg to 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.

Frequently asked questions

What is a git hook?
A script that Git runs automatically at a specific point in the workflow, such as before a commit, after a commit, or before a push. The scripts live in .git/hooks and are named after the event.
Why are my git hooks not running?
The most common reasons are that the file is not executable, or that the hook name does not match the event exactly. Run chmod +x on the file and check the name against the list of hooks.
What is Husky?
A tool that installs git hooks from a committed configuration, so the whole team gets the same hooks. It solves the problem that .git/hooks is not committed and therefore not shared.
What is the difference between pre-commit and pre-push?
pre-commit runs before each commit and should be fast, so it is the place for linting and formatting. pre-push runs before a push and can be slower, so it is the place for the test suite.
How do I skip a hook?
Use git commit --no-verify or git push --no-verify. This is useful in an emergency, but a hook that is bypassed often is a hook that is too slow or too unreliable.
Can a hook be bypassed?
Yes. Client-side hooks are not enforced, because a developer can always use --no-verify or delete the hook. For enforcement, run the same checks in CI, which cannot be bypassed.