NAME

githooks - Hooks used by Git

SYNOPSIS

$GIT_DIR/hooks/ (or git config core.hooksPath/)

DESCRIPTION

Hooks are programs you can place in a hooks directory to triggeractions at certain points in git’s execution. Hooks that don’t havethe executable bit set are ignored.

By default the hooks directory is $GIT_DIR/hooks, but that can bechanged via the core.hooksPath configuration variable (seegit-config[1]).

Before Git invokes a hook, it changes its working directory to either$GITDIR in a bare repository or the root of the working tree in a non-barerepository. An exception are hooks triggered during a push (_pre-receive,update, post-receive, post-update, push-to-checkout) which are alwaysexecuted in $GIT_DIR.

Hooks can get their arguments via the environment, command-linearguments, and stdin. See the documentation for each hook below fordetails.

git init may copy hooks to the new repository, depending on itsconfiguration. See the "TEMPLATE DIRECTORY" section ingit-init[1] for details. When the rest of this document refersto "default hooks" it’s talking about the default template shippedwith Git.

The currently supported hooks are described below.

HOOKS

applypatch-msg

This hook is invoked by git-am[1]. It takes a singleparameter, the name of the file that holds the proposed commitlog message. Exiting with a non-zero status causes git am to abortbefore applying the patch.

The hook is allowed to edit the message file in place, and canbe used to normalize the message into some project standardformat. It can also be used to refuse the commit after inspectingthe message file.

The default applypatch-msg hook, when enabled, runs thecommit-msg hook, if the latter is enabled.

pre-applypatch

This hook is invoked by git-am[1]. It takes no parameter, and isinvoked after the patch is applied, but before a commit is made.

If it exits with non-zero status, then the working tree will not becommitted after applying the patch.

It can be used to inspect the current working tree and refuse tomake a commit if it does not pass certain test.

The default pre-applypatch hook, when enabled, runs thepre-commit hook, if the latter is enabled.

post-applypatch

This hook is invoked by git-am[1]. It takes no parameter,and is invoked after the patch is applied and a commit is made.

This hook is meant primarily for notification, and cannot affectthe outcome of git am.

pre-commit

This hook is invoked by git-commit[1], and can be bypassedwith the —no-verify option. It takes no parameters, and isinvoked before obtaining the proposed commit log message andmaking a commit. Exiting with a non-zero status from this scriptcauses the git commit command to abort before creating a commit.

The default pre-commit hook, when enabled, catches introductionof lines with trailing whitespaces and aborts the commit whensuch a line is found.

All the git commit hooks are invoked with the environmentvariable GIT_EDITOR=: if the command will not bring up an editorto modify the commit message.

The default pre-commit hook, when enabled—​and with thehooks.allownonascii config option unset or set to false—​preventsthe use of non-ASCII filenames.

prepare-commit-msg

This hook is invoked by git-commit[1] right after preparing thedefault log message, and before the editor is started.

It takes one to three parameters. The first is the name of the filethat contains the commit log message. The second is the source of the commitmessage, and can be: message (if a -m or -F option wasgiven); template (if a -t option was given or theconfiguration option commit.template is set); merge (if thecommit is a merge or a .git/MERGE_MSG file exists); squash(if a .git/SQUASH_MSG file exists); or commit, followed bya commit SHA-1 (if a -c, -C or —amend option was given).

If the exit status is non-zero, git commit will abort.

The purpose of the hook is to edit the message file in place, andit is not suppressed by the —no-verify option. A non-zero exitmeans a failure of the hook and aborts the commit. It should notbe used as replacement for pre-commit hook.

The sample prepare-commit-msg hook that comes with Git removes thehelp message found in the commented portion of the commit template.

commit-msg

This hook is invoked by git-commit[1] and git-merge[1], and can bebypassed with the —no-verify option. It takes a single parameter,the name of the file that holds the proposed commit log message.Exiting with a non-zero status causes the command to abort.

The hook is allowed to edit the message file in place, and can be usedto normalize the message into some project standard format. Itcan also be used to refuse the commit after inspecting the messagefile.

The default commit-msg hook, when enabled, detects duplicate"Signed-off-by" lines, and aborts the commit if one is found.

post-commit

This hook is invoked by git-commit[1]. It takes no parameters, and isinvoked after a commit is made.

This hook is meant primarily for notification, and cannot affectthe outcome of git commit.

pre-rebase

This hook is called by git-rebase[1] and can be used to prevent abranch from getting rebased. The hook may be called with one ortwo parameters. The first parameter is the upstream from whichthe series was forked. The second parameter is the branch beingrebased, and is not set when rebasing the current branch.

post-checkout

This hook is invoked when a git-checkout[1] orgit-switch[1] is run after having updated theworktree. The hook is given three parameters: the ref of the previous HEAD,the ref of the new HEAD (which may or may not have changed), and a flagindicating whether the checkout was a branch checkout (changing branches,flag=1) or a file checkout (retrieving a file from the index, flag=0).This hook cannot affect the outcome of git switch or git checkout.

It is also run after git-clone[1], unless the —no-checkout (-n) option isused. The first parameter given to the hook is the null-ref, the second theref of the new HEAD and the flag is always 1. Likewise for git worktree addunless —no-checkout is used.

This hook can be used to perform repository validity checks, auto-displaydifferences from the previous HEAD if different, or set working dir metadataproperties.

post-merge

This hook is invoked by git-merge[1], which happens when a git pullis done on a local repository. The hook takes a single parameter, a statusflag specifying whether or not the merge being done was a squash merge.This hook cannot affect the outcome of git merge and is not executed,if the merge failed due to conflicts.

This hook can be used in conjunction with a corresponding pre-commit hook tosave and restore any form of metadata associated with the working tree(e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perlfor an example of how to do this.

pre-push

This hook is called by git-push[1] and can be used to preventa push from taking place. The hook is called with two parameterswhich provide the name and location of the destination remote, if anamed remote is not being used both values will be the same.

Information about what is to be pushed is provided on the hook’s standardinput with lines of the form:

<local ref> SP <local sha1> SP <remote ref> SP <remote sha1> LF

For instance, if the command git push origin master:foreign were run thehook would receive a line like the following:

refs/heads/master 67890 refs/heads/foreign 12345

although the full, 40-character SHA-1s would be supplied. If the foreign refdoes not yet exist the <remote SHA-1> will be 40 0. If a ref is to bedeleted, the <local ref> will be supplied as (delete) and the <localSHA-1> will be 40 0. If the local commit was specified by something otherthan a name which could be expanded (such as HEAD~, or a SHA-1) it will besupplied as it was originally given.

If this hook exits with a non-zero status, git push will abort withoutpushing anything. Information about why the push is rejected may be sentto the user by writing to standard error.

pre-receive

This hook is invoked by git-receive-pack[1] when it reacts togit push and updates reference(s) in its repository.Just before starting to update refs on the remote repository, thepre-receive hook is invoked. Its exit status determines the successor failure of the update.

This hook executes once for the receive operation. It takes noarguments, but for each ref to be updated it receives on standardinput a line of the format:

<old-value> SP <new-value> SP <ref-name> LF

where <old-value> is the old object name stored in the ref,<new-value> is the new object name to be stored in the ref and<ref-name> is the full name of the ref.When creating a new ref, <old-value> is 40 0.

If the hook exits with non-zero status, none of the refs will beupdated. If the hook exits with zero, updating of individual refs canstill be prevented by the update hook.

Both standard output and standard error output are forwarded togit send-pack on the other end, so you can simply echo messagesfor the user.

The number of push options given on the command line ofgit push —push-option=… can be read from the environmentvariable GIT_PUSH_OPTION_COUNT, and the options themselves arefound in GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,…​If it is negotiated to not use the push options phase, theenvironment variables will not be set. If the client selectsto use push options, but doesn’t transmit any, the count variablewill be set to zero, GIT_PUSH_OPTION_COUNT=0.

See the section on "Quarantine Environment" ingit-receive-pack[1] for some caveats.

update

This hook is invoked by git-receive-pack[1] when it reacts togit push and updates reference(s) in its repository.Just before updating the ref on the remote repository, the update hookis invoked. Its exit status determines the success or failure ofthe ref update.

The hook executes once for each ref to be updated, and takesthree parameters:

• the name of the ref being updated,

• the old object name stored in the ref,

• and the new object name to be stored in the ref.

A zero exit from the update hook allows the ref to be updated.Exiting with a non-zero status prevents git receive-packfrom updating that ref.

This hook can be used to prevent forced update on certain refs bymaking sure that the object name is a commit object that is adescendant of the commit object named by the old object name.That is, to enforce a "fast-forward only" policy.

It could also be used to log the old..new status. However, itdoes not know the entire set of branches, so it would end upfiring one e-mail per ref when used naively, though. Thepost-receive hook is more suited to that.

In an environment that restricts the users' access only to gitcommands over the wire, this hook can be used to implement accesscontrol without relying on filesystem ownership and groupmembership. See git-shell[1] for how you might use the loginshell to restrict the user’s access to only git commands.

Both standard output and standard error output are forwarded togit send-pack on the other end, so you can simply echo messagesfor the user.

The default update hook, when enabled—​and withhooks.allowunannotated config option unset or set to false—​preventsunannotated tags to be pushed.

post-receive

This hook is invoked by git-receive-pack[1] when it reacts togit push and updates reference(s) in its repository.It executes on the remote repository once after all the refs havebeen updated.

This hook executes once for the receive operation. It takes noarguments, but gets the same information as thepre-receivehook does on its standard input.

This hook does not affect the outcome of git receive-pack, as itis called after the real work is done.

This supersedes the post-update hook in that it getsboth old and new values of all the refs in addition to theirnames.

Both standard output and standard error output are forwarded togit send-pack on the other end, so you can simply echo messagesfor the user.

The default post-receive hook is empty, but there isa sample script post-receive-email provided in the contrib/hooksdirectory in Git distribution, which implements sending commitemails.

The number of push options given on the command line ofgit push —push-option=… can be read from the environmentvariable GIT_PUSH_OPTION_COUNT, and the options themselves arefound in GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,…​If it is negotiated to not use the push options phase, theenvironment variables will not be set. If the client selectsto use push options, but doesn’t transmit any, the count variablewill be set to zero, GIT_PUSH_OPTION_COUNT=0.

post-update

This hook is invoked by git-receive-pack[1] when it reacts togit push and updates reference(s) in its repository.It executes on the remote repository once after all the refs havebeen updated.

It takes a variable number of parameters, each of which is thename of ref that was actually updated.

This hook is meant primarily for notification, and cannot affectthe outcome of git receive-pack.

The post-update hook can tell what are the heads that were pushed,but it does not know what their original and updated values are,so it is a poor place to do log old..new. Thepost-receive hook does get both original andupdated values of the refs. You might consider it instead if you needthem.

When enabled, the default post-update hook runsgit update-server-info to keep the information used by dumbtransports (e.g., HTTP) up to date. If you are publishinga Git repository that is accessible via HTTP, you shouldprobably enable this hook.

Both standard output and standard error output are forwarded togit send-pack on the other end, so you can simply echo messagesfor the user.

push-to-checkout

This hook is invoked by git-receive-pack[1] when it reacts togit push and updates reference(s) in its repository, and whenthe push tries to update the branch that is currently checked outand the receive.denyCurrentBranch configuration variable is set toupdateInstead. Such a push by default is refused if the workingtree and the index of the remote repository has any difference fromthe currently checked out commit; when both the working tree and theindex match the current commit, they are updated to match the newlypushed tip of the branch. This hook is to be used to override thedefault behaviour.

The hook receives the commit with which the tip of the currentbranch is going to be updated. It can exit with a non-zero statusto refuse the push (when it does so, it must not modify the index orthe working tree). Or it can make any necessary changes to theworking tree and to the index to bring them to the desired statewhen the tip of the current branch is updated to the new commit, andexit with a zero status.

For example, the hook can simply run git read-tree -u -m HEAD "$1"in order to emulate git fetch that is run in the reverse directionwith git push, as the two-tree form of git read-tree -u -m isessentially the same as git switch or git checkoutthat switches branches whilekeeping the local changes in the working tree that do not interferewith the difference between the branches.

pre-auto-gc

This hook is invoked by git gc —auto (see git-gc[1]). Ittakes no parameter, and exiting with non-zero status from this scriptcauses the git gc —auto to abort.

post-rewrite

This hook is invoked by commands that rewrite commits(git-commit[1] when called with —amend andgit-rebase[1]; currently git filter-branch does not callit!). Its first argument denotes the command it was invoked by:currently one of amend or rebase. Further command-dependentarguments may be passed in the future.

The hook receives a list of the rewritten commits on stdin, in theformat

<old-sha1> SP <new-sha1> [ SP <extra-info> ] LF

The extra-info is again command-dependent. If it is empty, thepreceding SP is also omitted. Currently, no commands pass anyextra-info.

The hook always runs after the automatic note copying (see"notes.rewrite.<command>" in git-config[1]) has happened, andthus has access to these notes.

The following command-specific comments apply:

• rebase
• For the squash and fixup operation, all commits that weresquashed are listed as being rewritten to the squashed commit.This means that there will be several lines sharing the samenew-sha1.

The commits are guaranteed to be listed in the order that they wereprocessed by rebase.

sendemail-validate

This hook is invoked by git-send-email[1]. It takes a single parameter,the name of the file that holds the e-mail to be sent. Exiting with anon-zero status causes git send-email to abort before sending anye-mails.

fsmonitor-watchman

This hook is invoked when the configuration option core.fsmonitor isset to .git/hooks/fsmonitor-watchman. It takes two arguments, a version(currently 1) and the time in elapsed nanoseconds since midnight,January 1, 1970.

The hook should output to stdout the list of all files in the workingdirectory that may have changed since the requested time. The logicshould be inclusive so that it does not miss any potential changes.The paths should be relative to the root of the working directoryand be separated by a single NUL.

It is OK to include files which have not actually changed. All changesincluding newly-created and deleted files should be included. Whenfiles are renamed, both the old and the new name should be included.

Git will limit what files it checks for changes as well as whichdirectories are checked for untracked files based on the path namesgiven.

An optimized way to tell git "all files have changed" is to returnthe filename /.

The exit status determines whether git will use the data from thehook to limit its search. On error, it will fall back to verifyingall files and folders.

p4-pre-submit

This hook is invoked by git-p4 submit. It takes no parameters and nothingfrom standard input. Exiting with non-zero status from this script preventgit-p4 submit from launching. Run git-p4 submit —help for details.

post-index-change

This hook is invoked when the index is written in read-cache.cdo_write_locked_index.

The first parameter passed to the hook is the indicator for theworking directory being updated. "1" meaning working directorywas updated or "0" when the working directory was not updated.

The second parameter passed to the hook is the indicator for whetheror not the index was updated and the skip-worktree bit could havechanged. "1" meaning skip-worktree bits could have been updatedand "0" meaning they were not.

Only one parameter should be set to "1" when the hook runs. The hookrunning passing "1", "1" should not be possible.

GIT

Part of the git[1] suite