Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash Several hooks for one event

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 Scopes, failures and a hook directory

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 tests hook fails with status 3 and git hook run returns 3. For a hook that can block an action, such as pre-commit, a failure blocks it.
  • Completeness. An entry that has an event but no command is a fatal error, so Git does not guess what you meant. Remove the stray event or 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 run and git hook list need a new enough Git as well (git hook run since 2.36, the hook.* 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-verify skips pre-commit and commit-msg for configured hooks as it does for files. Hooks cannot be made mandatory on the client.
  • Pointing core.hooksPath at a directory with no hook files disables the file hooks for one command: git -c core.hooksPath=/dev/null commit.