1githooks(5) 2=========== 3 4NAME 5---- 6githooks - Hooks used by Git 7 8SYNOPSIS 9-------- 10$GIT_DIR/hooks/* (or \`git config core.hooksPath`/*) 11 12 13DESCRIPTION 14----------- 15 16Hooks are programs you can place in a hooks directory to trigger 17actions at certain points in git's execution. Hooks that don't have 18the executable bit set are ignored. 19 20By default the hooks directory is `$GIT_DIR/hooks`, but that can be 21changed via the `core.hooksPath` configuration variable (see 22linkgit:git-config[1]). 23 24Before Git invokes a hook, it changes its working directory to either 25$GIT_DIR in a bare repository or the root of the working tree in a non-bare 26repository. An exception are hooks triggered during a push ('pre-receive', 27'update', 'post-receive', 'post-update', 'push-to-checkout') which are always 28executed in $GIT_DIR. 29 30Hooks can get their arguments via the environment, command-line 31arguments, and stdin. See the documentation for each hook below for 32details. 33 34'git init' may copy hooks to the new repository, depending on its 35configuration. See the "TEMPLATE DIRECTORY" section in 36linkgit:git-init[1] for details. When the rest of this document refers 37to "default hooks" it's talking about the default template shipped 38with Git. 39 40The currently supported hooks are described below. 41 42HOOKS 43----- 44 45applypatch-msg 46~~~~~~~~~~~~~~ 47 48This hook is invoked by 'git am'. It takes a single 49parameter, the name of the file that holds the proposed commit 50log message. Exiting with a non-zero status causes 'git am' to abort 51before applying the patch. 52 53The hook is allowed to edit the message file in place, and can 54be used to normalize the message into some project standard 55format. It can also be used to refuse the commit after inspecting 56the message file. 57 58The default 'applypatch-msg' hook, when enabled, runs the 59'commit-msg' hook, if the latter is enabled. 60 61pre-applypatch 62~~~~~~~~~~~~~~ 63 64This hook is invoked by 'git am'. It takes no parameter, and is 65invoked after the patch is applied, but before a commit is made. 66 67If it exits with non-zero status, then the working tree will not be 68committed after applying the patch. 69 70It can be used to inspect the current working tree and refuse to 71make a commit if it does not pass certain test. 72 73The default 'pre-applypatch' hook, when enabled, runs the 74'pre-commit' hook, if the latter is enabled. 75 76post-applypatch 77~~~~~~~~~~~~~~~ 78 79This hook is invoked by 'git am'. It takes no parameter, 80and is invoked after the patch is applied and a commit is made. 81 82This hook is meant primarily for notification, and cannot affect 83the outcome of 'git am'. 84 85pre-commit 86~~~~~~~~~~ 87 88This hook is invoked by 'git commit', and can be bypassed 89with the `--no-verify` option. It takes no parameters, and is 90invoked before obtaining the proposed commit log message and 91making a commit. Exiting with a non-zero status from this script 92causes the 'git commit' command to abort before creating a commit. 93 94The default 'pre-commit' hook, when enabled, catches introduction 95of lines with trailing whitespaces and aborts the commit when 96such a line is found. 97 98All the 'git commit' hooks are invoked with the environment 99variable `GIT_EDITOR=:` if the command will not bring up an editor 100to modify the commit message. 101 102prepare-commit-msg 103~~~~~~~~~~~~~~~~~~ 104 105This hook is invoked by 'git commit' right after preparing the 106default log message, and before the editor is started. 107 108It takes one to three parameters. The first is the name of the file 109that contains the commit log message. The second is the source of the commit 110message, and can be: `message` (if a `-m` or `-F` option was 111given); `template` (if a `-t` option was given or the 112configuration option `commit.template` is set); `merge` (if the 113commit is a merge or a `.git/MERGE_MSG` file exists); `squash` 114(if a `.git/SQUASH_MSG` file exists); or `commit`, followed by 115a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given). 116 117If the exit status is non-zero, 'git commit' will abort. 118 119The purpose of the hook is to edit the message file in place, and 120it is not suppressed by the `--no-verify` option. A non-zero exit 121means a failure of the hook and aborts the commit. It should not 122be used as replacement for pre-commit hook. 123 124commit-msg 125~~~~~~~~~~ 126 127This hook is invoked by 'git commit', and can be bypassed 128with the `--no-verify` option. It takes a single parameter, the 129name of the file that holds the proposed commit log message. 130Exiting with a non-zero status causes the 'git commit' to 131abort. 132 133The hook is allowed to edit the message file in place, and can be used 134to normalize the message into some project standard format. It 135can also be used to refuse the commit after inspecting the message 136file. 137 138The default 'commit-msg' hook, when enabled, detects duplicate 139"Signed-off-by" lines, and aborts the commit if one is found. 140 141post-commit 142~~~~~~~~~~~ 143 144This hook is invoked by 'git commit'. It takes no parameters, and is 145invoked after a commit is made. 146 147This hook is meant primarily for notification, and cannot affect 148the outcome of 'git commit'. 149 150pre-rebase 151~~~~~~~~~~ 152 153This hook is called by 'git rebase' and can be used to prevent a 154branch from getting rebased. The hook may be called with one or 155two parameters. The first parameter is the upstream from which 156the series was forked. The second parameter is the branch being 157rebased, and is not set when rebasing the current branch. 158 159post-checkout 160~~~~~~~~~~~~~ 161 162This hook is invoked when a 'git checkout' is run after having updated the 163worktree. The hook is given three parameters: the ref of the previous HEAD, 164the ref of the new HEAD (which may or may not have changed), and a flag 165indicating whether the checkout was a branch checkout (changing branches, 166flag=1) or a file checkout (retrieving a file from the index, flag=0). 167This hook cannot affect the outcome of 'git checkout'. 168 169It is also run after 'git clone', unless the --no-checkout (-n) option is 170used. The first parameter given to the hook is the null-ref, the second the 171ref of the new HEAD and the flag is always 1. 172 173This hook can be used to perform repository validity checks, auto-display 174differences from the previous HEAD if different, or set working dir metadata 175properties. 176 177post-merge 178~~~~~~~~~~ 179 180This hook is invoked by 'git merge', which happens when a 'git pull' 181is done on a local repository. The hook takes a single parameter, a status 182flag specifying whether or not the merge being done was a squash merge. 183This hook cannot affect the outcome of 'git merge' and is not executed, 184if the merge failed due to conflicts. 185 186This hook can be used in conjunction with a corresponding pre-commit hook to 187save and restore any form of metadata associated with the working tree 188(e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl 189for an example of how to do this. 190 191pre-push 192~~~~~~~~ 193 194This hook is called by 'git push' and can be used to prevent a push from taking 195place. The hook is called with two parameters which provide the name and 196location of the destination remote, if a named remote is not being used both 197values will be the same. 198 199Information about what is to be pushed is provided on the hook's standard 200input with lines of the form: 201 202 <local ref> SP <local sha1> SP <remote ref> SP <remote sha1> LF 203 204For instance, if the command +git push origin master:foreign+ were run the 205hook would receive a line like the following: 206 207 refs/heads/master 67890 refs/heads/foreign 12345 208 209although the full, 40-character SHA-1s would be supplied. If the foreign ref 210does not yet exist the `<remote SHA-1>` will be 40 `0`. If a ref is to be 211deleted, the `<local ref>` will be supplied as `(delete)` and the `<local 212SHA-1>` will be 40 `0`. If the local commit was specified by something other 213than a name which could be expanded (such as `HEAD~`, or a SHA-1) it will be 214supplied as it was originally given. 215 216If this hook exits with a non-zero status, 'git push' will abort without 217pushing anything. Information about why the push is rejected may be sent 218to the user by writing to standard error. 219 220[[pre-receive]] 221pre-receive 222~~~~~~~~~~~ 223 224This hook is invoked by 'git-receive-pack' on the remote repository, 225which happens when a 'git push' is done on a local repository. 226Just before starting to update refs on the remote repository, the 227pre-receive hook is invoked. Its exit status determines the success 228or failure of the update. 229 230This hook executes once for the receive operation. It takes no 231arguments, but for each ref to be updated it receives on standard 232input a line of the format: 233 234 <old-value> SP <new-value> SP <ref-name> LF 235 236where `<old-value>` is the old object name stored in the ref, 237`<new-value>` is the new object name to be stored in the ref and 238`<ref-name>` is the full name of the ref. 239When creating a new ref, `<old-value>` is 40 `0`. 240 241If the hook exits with non-zero status, none of the refs will be 242updated. If the hook exits with zero, updating of individual refs can 243still be prevented by the <<update,'update'>> hook. 244 245Both standard output and standard error output are forwarded to 246'git send-pack' on the other end, so you can simply `echo` messages 247for the user. 248 249The number of push options given on the command line of 250`git push --push-option=...` can be read from the environment 251variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are 252found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... 253If it is negotiated to not use the push options phase, the 254environment variables will not be set. If the client selects 255to use push options, but doesn't transmit any, the count variable 256will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. 257 258See the section on "Quarantine Environment" in 259linkgit:git-receive-pack[1] for some caveats. 260 261[[update]] 262update 263~~~~~~ 264 265This hook is invoked by 'git-receive-pack' on the remote repository, 266which happens when a 'git push' is done on a local repository. 267Just before updating the ref on the remote repository, the update hook 268is invoked. Its exit status determines the success or failure of 269the ref update. 270 271The hook executes once for each ref to be updated, and takes 272three parameters: 273 274 - the name of the ref being updated, 275 - the old object name stored in the ref, 276 - and the new object name to be stored in the ref. 277 278A zero exit from the update hook allows the ref to be updated. 279Exiting with a non-zero status prevents 'git-receive-pack' 280from updating that ref. 281 282This hook can be used to prevent 'forced' update on certain refs by 283making sure that the object name is a commit object that is a 284descendant of the commit object named by the old object name. 285That is, to enforce a "fast-forward only" policy. 286 287It could also be used to log the old..new status. However, it 288does not know the entire set of branches, so it would end up 289firing one e-mail per ref when used naively, though. The 290<<post-receive,'post-receive'>> hook is more suited to that. 291 292In an environment that restricts the users' access only to git 293commands over the wire, this hook can be used to implement access 294control without relying on filesystem ownership and group 295membership. See linkgit:git-shell[1] for how you might use the login 296shell to restrict the user's access to only git commands. 297 298Both standard output and standard error output are forwarded to 299'git send-pack' on the other end, so you can simply `echo` messages 300for the user. 301 302The default 'update' hook, when enabled--and with 303`hooks.allowunannotated` config option unset or set to false--prevents 304unannotated tags to be pushed. 305 306[[post-receive]] 307post-receive 308~~~~~~~~~~~~ 309 310This hook is invoked by 'git-receive-pack' on the remote repository, 311which happens when a 'git push' is done on a local repository. 312It executes on the remote repository once after all the refs have 313been updated. 314 315This hook executes once for the receive operation. It takes no 316arguments, but gets the same information as the 317<<pre-receive,'pre-receive'>> 318hook does on its standard input. 319 320This hook does not affect the outcome of 'git-receive-pack', as it 321is called after the real work is done. 322 323This supersedes the <<post-update,'post-update'>> hook in that it gets 324both old and new values of all the refs in addition to their 325names. 326 327Both standard output and standard error output are forwarded to 328'git send-pack' on the other end, so you can simply `echo` messages 329for the user. 330 331The default 'post-receive' hook is empty, but there is 332a sample script `post-receive-email` provided in the `contrib/hooks` 333directory in Git distribution, which implements sending commit 334emails. 335 336The number of push options given on the command line of 337`git push --push-option=...` can be read from the environment 338variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are 339found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... 340If it is negotiated to not use the push options phase, the 341environment variables will not be set. If the client selects 342to use push options, but doesn't transmit any, the count variable 343will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. 344 345[[post-update]] 346post-update 347~~~~~~~~~~~ 348 349This hook is invoked by 'git-receive-pack' on the remote repository, 350which happens when a 'git push' is done on a local repository. 351It executes on the remote repository once after all the refs have 352been updated. 353 354It takes a variable number of parameters, each of which is the 355name of ref that was actually updated. 356 357This hook is meant primarily for notification, and cannot affect 358the outcome of 'git-receive-pack'. 359 360The 'post-update' hook can tell what are the heads that were pushed, 361but it does not know what their original and updated values are, 362so it is a poor place to do log old..new. The 363<<post-receive,'post-receive'>> hook does get both original and 364updated values of the refs. You might consider it instead if you need 365them. 366 367When enabled, the default 'post-update' hook runs 368'git update-server-info' to keep the information used by dumb 369transports (e.g., HTTP) up-to-date. If you are publishing 370a Git repository that is accessible via HTTP, you should 371probably enable this hook. 372 373Both standard output and standard error output are forwarded to 374'git send-pack' on the other end, so you can simply `echo` messages 375for the user. 376 377push-to-checkout 378~~~~~~~~~~~~~~~~ 379 380This hook is invoked by 'git-receive-pack' on the remote repository, 381which happens when a 'git push' is done on a local repository, when 382the push tries to update the branch that is currently checked out 383and the `receive.denyCurrentBranch` configuration variable is set to 384`updateInstead`. Such a push by default is refused if the working 385tree and the index of the remote repository has any difference from 386the currently checked out commit; when both the working tree and the 387index match the current commit, they are updated to match the newly 388pushed tip of the branch. This hook is to be used to override the 389default behaviour. 390 391The hook receives the commit with which the tip of the current 392branch is going to be updated. It can exit with a non-zero status 393to refuse the push (when it does so, it must not modify the index or 394the working tree). Or it can make any necessary changes to the 395working tree and to the index to bring them to the desired state 396when the tip of the current branch is updated to the new commit, and 397exit with a zero status. 398 399For example, the hook can simply run `git read-tree -u -m HEAD "$1"` 400in order to emulate 'git fetch' that is run in the reverse direction 401with `git push`, as the two-tree form of `read-tree -u -m` is 402essentially the same as `git checkout` that switches branches while 403keeping the local changes in the working tree that do not interfere 404with the difference between the branches. 405 406 407pre-auto-gc 408~~~~~~~~~~~ 409 410This hook is invoked by 'git gc --auto'. It takes no parameter, and 411exiting with non-zero status from this script causes the 'git gc --auto' 412to abort. 413 414post-rewrite 415~~~~~~~~~~~~ 416 417This hook is invoked by commands that rewrite commits (`git commit 418--amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call 419it!). Its first argument denotes the command it was invoked by: 420currently one of `amend` or `rebase`. Further command-dependent 421arguments may be passed in the future. 422 423The hook receives a list of the rewritten commits on stdin, in the 424format 425 426 <old-sha1> SP <new-sha1> [ SP <extra-info> ] LF 427 428The 'extra-info' is again command-dependent. If it is empty, the 429preceding SP is also omitted. Currently, no commands pass any 430'extra-info'. 431 432The hook always runs after the automatic note copying (see 433"notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and 434thus has access to these notes. 435 436The following command-specific comments apply: 437 438rebase:: 439 For the 'squash' and 'fixup' operation, all commits that were 440 squashed are listed as being rewritten to the squashed commit. 441 This means that there will be several lines sharing the same 442 'new-sha1'. 443+ 444The commits are guaranteed to be listed in the order that they were 445processed by rebase. 446 447sendemail-validate 448~~~~~~~~~~~~~~~~~~ 449 450This hook is invoked by 'git send-email'. It takes a single parameter, 451the name of the file that holds the e-mail to be sent. Exiting with a 452non-zero status causes 'git send-email' to abort before sending any 453e-mails. 454 455 456GIT 457--- 458Part of the linkgit:git[1] suite