Git Reference ยท Hooks
Git hooks overview
Reference overview of Git hooks: where they live, when each runs, the arguments and stdin they get, what exit codes mean, environment variables and how to bypass them.
A hook is an executable file that Git runs at a defined moment: before a commit is made, after a merge, when a push arrives at a server. Git looks the file up by name, passes information through arguments, standard input and environment variables, and in many cases uses the exit status to decide whether to continue. Hooks are the way to attach checks and automation to Git itself, without wrapping every command.
This page describes what all hooks have in common. Each hook has its own page with the details of its arguments: pre-commit, commit-msg, pre-push and the others in this section.
ls .git/hooks # sample files, inactive until renamed git config core.hooksPath .githooks git hook run pre-commit # run a hook by hand git commit --no-verify # skip pre-commit and commit-msg
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
A hook is looked up by exact name in the hooks directory: .git/hooks/<name>, or the directory set by core.hooksPath. The file must be executable. Any language works if the first line names the interpreter, such as #!/bin/sh.
Client-side hooks, grouped by the command that runs them:
| Hook | Runs | Blocks? | Page |
|---|---|---|---|
pre-commit |
before the message is requested | yes | pre-commit |
prepare-commit-msg |
after the default message is built | yes | prepare-commit-msg |
commit-msg |
after the message is written | yes | commit-msg |
post-commit |
after the commit exists | no | post-commit |
pre-merge-commit |
before a successful merge commit | yes | |
pre-rebase |
before a rebase starts | yes | pre-rebase |
post-checkout, post-merge, post-rewrite |
after switching, merging, amending or rebasing | no | |
pre-push |
before objects are transferred | yes | pre-push |
pre-auto-gc |
before automatic gc | yes | |
applypatch-msg, pre-applypatch, post-applypatch |
during git am |
first two yes | |
reference-transaction |
when refs change | yes (in prepared) |
reference-transaction |
Server-side hooks: pre-receive, update (once per ref), post-receive, post-update and push-to-checkout.
Arguments, input and environment
- Arguments are hook specific (for example
commit-msggets the path to the message file). - Hooks that must see lists of refs (
pre-push,pre-receive,post-receive,post-rewrite) get them as lines on standard input. - Git sets environment variables for the hook. During a commit,
GIT_INDEX_FILEnames the index in use (the first example prints.git/index), andGIT_AUTHOR_*variables may be present. Client hooks start in the root of the working tree; server-side hooks start in the repository directory, whereGIT_DIRis.in a bare repository. Do not assumeGIT_DIRis set in client hooks.
Exit status: 0 continues. For a blocking hook any other value aborts the operation, and Git itself then exits with a failure. For the others the status cannot undo anything: in the second example post-commit exits 1 and git commit still exits 0 with the commit in place.
Usage notes
- Hook output goes to stderr for most client-side hooks, even when the script uses plain
echo, so scripts that capture stdout see nothing. --no-verifyskips only some hooks:pre-commit,commit-msgandpre-merge-commiton commit and merge, andpre-pushon push (git push --no-verify). It never skipspost-*hooks or server-side hooks.- Hooks are local.
.git/hooksis not copied bygit clone. Put shared hooks in a tracked folder and pointcore.hooksPathat it, or use configuration hooks. - A missing or non-executable file is silently skipped. On Windows the executable bit is not used; Git for Windows runs hooks through its own shell, so keep the
#!/bin/shline. Git prints a hint when a hook exists but is not executable. - Use
git hook run <name>to test, with extra arguments after--. It uses the same lookup rules and environment as Git itself. - Keep blocking hooks fast and make the error message explain how to fix the problem. Slow hooks train people to bypass them.
- Hooks are not security. Anyone can skip a client-side hook. Enforce rules on the server and in CI.
- A repository's hooks run code on your machine. Do not run Git commands in untrusted repositories with hooks you have not read;
safe.directoryand ownership checks are part of this protection.