Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Hooks

pre-commit hook

Reference for the pre-commit hook: when it runs, what it receives, how to check the staged content, the commit -a index trap, --no-verify and exit codes.

The pre-commit hook runs when you start git commit, before Git asks for a commit message and before anything is recorded. It takes no arguments and gets no standard input; its job is to inspect what is about to be committed and exit non-zero to stop it. Typical uses are linters, formatters in check mode, scans for secrets or leftover debug statements, and quick unit tests.

Because it runs on every commit, it must be fast. Slow checks belong in pre-push or in continuous integration.

Terminal
#!/bin/sh
# .git/hooks/pre-commit (executable)
git diff --cached --check || exit 1

Try it

Bash Block whitespace errors in staged changes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Which index does the hook see?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Text
.git/hooks/pre-commit
Item Detail
Arguments None.
Standard input Not used.
Working directory Root of the working tree.
Exit status 0 continues; non-zero aborts the commit before the message editor opens.
Skipped by git commit --no-verify (-n).
Also runs for git commit --amend, and commits made by many tools through git commit. Not for git commit-tree or commits created by rebase, cherry-pick and merge (merges have pre-merge-commit).
Output Printed to the terminal; the hook may also print to stdout or stderr.

Environment: GIT_INDEX_FILE names the index the commit will use: .git/index for a plain commit, .git/index.lock for git commit -a, and a temporary next-index file for git commit <paths> (see the second example). GIT_EDITOR is set to : when the commit has a message from -m.

Usage notes

  • Check the staged content, not the files on disk. A file can differ between the index and the working tree. Use git diff --cached to list changes, and git show :path (the colon means "the index") to read the staged version. Linting the working copy can approve code that is not what is being committed.
  • Use the right file list. git diff --cached --name-only --diff-filter=ACM -z gives added, copied and modified paths and survives spaces in names; deleted files cannot be linted.
  • Do not reformat in place and forget to re-stage. If the hook rewrites files, run git add on those exact paths afterward. A partial staging (git add -p) would be lost this way, so many teams only report problems and let the author fix them.
  • git stash --keep-index is a common trick for testing exactly the staged state, but it is dangerous in a hook: a crash leaves your work in a stash, and it interacts badly with commit -a. Prefer tools that read content from the index.
  • Index variable matters with -a or paths. Commands you run inside the hook (such as git diff --cached) honor the inherited GIT_INDEX_FILE, so they see the right state. If the hook calls other Git commands on a different repository, unset it or use git -C.
  • Start a new repository's hooks from the samples (.git/hooks/pre-commit.sample), which check for non-ASCII file names and whitespace errors.
  • Teams should store hooks in a tracked directory and set core.hooksPath; frameworks such as pre-commit, Husky and Lefthook automate this. Keep real enforcement in CI, since --no-verify always exists.
  • Exit codes matter more than messages. Always end with an explicit exit 0 so an unrelated last command does not block commits by accident.