Git Reference ยท Hooks
Hook configuration (hook.* and core.hooksPath)
Reference for configuring Git hooks without files: hook.<name>.event, command and enabled, ordering with hook files, git hook list and run, and core.hooksPath.
Traditionally a hook is one executable file named after its event, such as .git/hooks/pre-commit. That allows exactly one program per event and keeps hooks out of version control. Git gives you two ways around this: core.hooksPath points Git at a different directory of hook files, and, in recent versions, hooks defined in configuration let you register as many commands as you like for an event, from any configuration scope.
A configured hook has a name you choose, an event (the hook it listens to), and a command. Because the settings can live in the system, global or local configuration, an organization can install shared checks everywhere while each repository adds its own.
git config hook.<name>.event <hook-event> # may be set several times git config hook.<name>.command <shell command> git config hook.<name>.enabled false # switch it off without deleting it git hook list [--show-scope] <hook-event> git hook run [--ignore-missing] [--to-stdin=<path>] <hook-event> [-- <args>...]
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
| Setting | Description |
|---|---|
hook.<name>.event |
The hook event this entry listens to (pre-commit, commit-msg, pre-push, and so on). It is a multi-valued key: repeat it with git config --add to listen to several events. |
hook.<name>.command |
The command to run, executed by the shell. Git appends the hook's arguments to it: in the first example the lint hook, running as commit-msg, was called with .git/COMMIT_EDITMSG at the end, so use a script that reads $1 for hooks that take arguments. |
hook.<name>.enabled |
false turns the entry off without deleting it. Set it in a narrower scope (local) to switch off a hook defined in a wider one (global or system). Default true. |
core.hooksPath |
Directory that holds hook files instead of $GIT_DIR/hooks. Absolute or relative to where Git runs the hook (the top of the working tree for most hooks). |
git hook list <event> prints the hooks Git would run, in order, one name per line. --show-scope adds the configuration scope. A hook that comes from a file is listed too, and a disabled one is shown with a disabled marker. git hook run <event> runs them exactly as Git would, returning a non-zero exit status if a hook failed; --ignore-missing makes it succeed quietly when nothing is registered, and everything after -- is passed to the hooks as arguments. --to-stdin=<path> feeds a file to the hooks' standard input.
Usage notes
- Order. Configured hooks run first, in the order the settings are read (system, then global, then local, and within a file top to bottom). The hook file from the hooks directory runs last.
- Failure. In the second example the
testshook fails with status 3 andgit hook runreturns 3. For a hook that can block an action, such aspre-commit, a failure blocks it. - Completeness. An entry that has an
eventbut nocommandis a fatal error, so Git does not guess what you meant. Remove the strayeventor add the command. - Output. A hook's stdout is sent to stderr, as with file hooks, so the terminal shows it but pipes in scripts do not carry it.
- Compatibility. Older Git versions ignore
hook.*settings and fall back to the file only. If a team has mixed versions, keep an equivalent file hook or a clear minimum version.git hook runandgit hook listneed a new enough Git as well (git hook runsince 2.36, thehook.*settings in the Git 2.56 used for the examples). - Sharing. Config values are not committed, so a global or system configuration is the way to distribute organization-wide hooks. For a repository-specific set, commit a hooks directory and tell developers to run
git config core.hooksPath <dir>once, or use a setup script. - Security. A hook is arbitrary code. Anyone who can write your configuration can make Git run something on every commit. Only the local and global files are yours; take care with includes (
include.path) from untrusted places. - Bypass.
--no-verifyskipspre-commitandcommit-msgfor configured hooks as it does for files. Hooks cannot be made mandatory on the client. - Pointing
core.hooksPathat a directory with no hook files disables the file hooks for one command:git -c core.hooksPath=/dev/null commit.