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.
#!/bin/sh # .git/hooks/pre-commit (executable) git diff --cached --check || exit 1
Try it
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.
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
.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 --cachedto list changes, andgit 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 -zgives 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 addon 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-indexis 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 withcommit -a. Prefer tools that read content from the index.- Index variable matters with
-aor paths. Commands you run inside the hook (such asgit diff --cached) honor the inheritedGIT_INDEX_FILE, so they see the right state. If the hook calls other Git commands on a different repository, unset it or usegit -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-verifyalways exists. - Exit codes matter more than messages. Always end with an explicit
exit 0so an unrelated last command does not block commits by accident.