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 linkgit:git-am[1]. 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 linkgit:git-am[1]. 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 linkgit:git-am[1]. 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 linkgit:git-commit[1], 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 102The default 'pre-commit' hook, when enabled--and with the 103`hooks.allownonascii` config option unset or set to false--prevents 104the use of non-ASCII filenames. 105 106prepare-commit-msg 107~~~~~~~~~~~~~~~~~~ 108 109This hook is invoked by linkgit:git-commit[1] right after preparing the 110default log message, and before the editor is started. 111 112It takes one to three parameters. The first is the name of the file 113that contains the commit log message. The second is the source of the commit 114message, and can be: `message` (if a `-m` or `-F` option was 115given); `template` (if a `-t` option was given or the 116configuration option `commit.template` is set); `merge` (if the 117commit is a merge or a `.git/MERGE_MSG` file exists); `squash` 118(if a `.git/SQUASH_MSG` file exists); or `commit`, followed by 119a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given). 120 121If the exit status is non-zero, `git commit` will abort. 122 123The purpose of the hook is to edit the message file in place, and 124it is not suppressed by the `--no-verify` option. A non-zero exit 125means a failure of the hook and aborts the commit. It should not 126be used as replacement for pre-commit hook. 127 128The sample `prepare-commit-msg` hook that comes with Git removes the 129help message found in the commented portion of the commit template. 130 131commit-msg 132~~~~~~~~~~ 133 134This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and can be 135bypassed with the `--no-verify` option. It takes a single parameter, 136the name of the file that holds the proposed commit log message. 137Exiting with a non-zero status causes the command to abort. 138 139The hook is allowed to edit the message file in place, and can be used 140to normalize the message into some project standard format. It 141can also be used to refuse the commit after inspecting the message 142file. 143 144The default 'commit-msg' hook, when enabled, detects duplicate 145"Signed-off-by" lines, and aborts the commit if one is found. 146 147post-commit 148~~~~~~~~~~~ 149 150This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is 151invoked after a commit is made. 152 153This hook is meant primarily for notification, and cannot affect 154the outcome of `git commit`. 155 156pre-rebase 157~~~~~~~~~~ 158 159This hook is called by linkgit:git-rebase[1] and can be used to prevent a 160branch from getting rebased. The hook may be called with one or 161two parameters. The first parameter is the upstream from which 162the series was forked. The second parameter is the branch being 163rebased, and is not set when rebasing the current branch. 164 165post-checkout 166~~~~~~~~~~~~~ 167 168This hook is invoked when a linkgit:git-checkout[1] or 169linkgit:git-switch[1] is run after having updated the 170worktree. The hook is given three parameters: the ref of the previous HEAD, 171the ref of the new HEAD (which may or may not have changed), and a flag 172indicating whether the checkout was a branch checkout (changing branches, 173flag=1) or a file checkout (retrieving a file from the index, flag=0). 174This hook cannot affect the outcome of `git switch` or `git checkout`. 175 176It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is 177used. The first parameter given to the hook is the null-ref, the second the 178ref of the new HEAD and the flag is always 1. Likewise for `git worktree add` 179unless `--no-checkout` is used. 180 181This hook can be used to perform repository validity checks, auto-display 182differences from the previous HEAD if different, or set working dir metadata 183properties. 184 185post-merge 186~~~~~~~~~~ 187 188This hook is invoked by linkgit:git-merge[1], which happens when a `git pull` 189is done on a local repository. The hook takes a single parameter, a status 190flag specifying whether or not the merge being done was a squash merge. 191This hook cannot affect the outcome of `git merge` and is not executed, 192if the merge failed due to conflicts. 193 194This hook can be used in conjunction with a corresponding pre-commit hook to 195save and restore any form of metadata associated with the working tree 196(e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl 197for an example of how to do this. 198 199pre-push 200~~~~~~~~ 201 202This hook is called by linkgit:git-push[1] and can be used to prevent 203a push from taking place. The hook is called with two parameters 204which provide the name and location of the destination remote, if a 205named remote is not being used both values will be the same. 206 207Information about what is to be pushed is provided on the hook's standard 208input with lines of the form: 209 210 <local ref> SP <local sha1> SP <remote ref> SP <remote sha1> LF 211 212For instance, if the command +git push origin master:foreign+ were run the 213hook would receive a line like the following: 214 215 refs/heads/master 67890 refs/heads/foreign 12345 216 217although the full, 40-character SHA-1s would be supplied. If the foreign ref 218does not yet exist the `<remote SHA-1>` will be 40 `0`. If a ref is to be 219deleted, the `<local ref>` will be supplied as `(delete)` and the `<local 220SHA-1>` will be 40 `0`. If the local commit was specified by something other 221than a name which could be expanded (such as `HEAD~`, or a SHA-1) it will be 222supplied as it was originally given. 223 224If this hook exits with a non-zero status, `git push` will abort without 225pushing anything. Information about why the push is rejected may be sent 226to the user by writing to standard error. 227 228[[pre-receive]] 229pre-receive 230~~~~~~~~~~~ 231 232This hook is invoked by linkgit:git-receive-pack[1] when it reacts to 233`git push` and updates reference(s) in its repository. 234Just before starting to update refs on the remote repository, the 235pre-receive hook is invoked. Its exit status determines the success 236or failure of the update. 237 238This hook executes once for the receive operation. It takes no 239arguments, but for each ref to be updated it receives on standard 240input a line of the format: 241 242 <old-value> SP <new-value> SP <ref-name> LF 243 244where `<old-value>` is the old object name stored in the ref, 245`<new-value>` is the new object name to be stored in the ref and 246`<ref-name>` is the full name of the ref. 247When creating a new ref, `<old-value>` is 40 `0`. 248 249If the hook exits with non-zero status, none of the refs will be 250updated. If the hook exits with zero, updating of individual refs can 251still be prevented by the <<update,'update'>> hook. 252 253Both standard output and standard error output are forwarded to 254`git send-pack` on the other end, so you can simply `echo` messages 255for the user. 256 257The number of push options given on the command line of 258`git push --push-option=...` can be read from the environment 259variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are 260found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... 261If it is negotiated to not use the push options phase, the 262environment variables will not be set. If the client selects 263to use push options, but doesn't transmit any, the count variable 264will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. 265 266See the section on "Quarantine Environment" in 267linkgit:git-receive-pack[1] for some caveats. 268 269[[update]] 270update 271~~~~~~ 272 273This hook is invoked by linkgit:git-receive-pack[1] when it reacts to 274`git push` and updates reference(s) in its repository. 275Just before updating the ref on the remote repository, the update hook 276is invoked. Its exit status determines the success or failure of 277the ref update. 278 279The hook executes once for each ref to be updated, and takes 280three parameters: 281 282 - the name of the ref being updated, 283 - the old object name stored in the ref, 284 - and the new object name to be stored in the ref. 285 286A zero exit from the update hook allows the ref to be updated. 287Exiting with a non-zero status prevents `git receive-pack` 288from updating that ref. 289 290This hook can be used to prevent 'forced' update on certain refs by 291making sure that the object name is a commit object that is a 292descendant of the commit object named by the old object name. 293That is, to enforce a "fast-forward only" policy. 294 295It could also be used to log the old..new status. However, it 296does not know the entire set of branches, so it would end up 297firing one e-mail per ref when used naively, though. The 298<<post-receive,'post-receive'>> hook is more suited to that. 299 300In an environment that restricts the users' access only to git 301commands over the wire, this hook can be used to implement access 302control without relying on filesystem ownership and group 303membership. See linkgit:git-shell[1] for how you might use the login 304shell to restrict the user's access to only git commands. 305 306Both standard output and standard error output are forwarded to 307`git send-pack` on the other end, so you can simply `echo` messages 308for the user. 309 310The default 'update' hook, when enabled--and with 311`hooks.allowunannotated` config option unset or set to false--prevents 312unannotated tags to be pushed. 313 314[[post-receive]] 315post-receive 316~~~~~~~~~~~~ 317 318This hook is invoked by linkgit:git-receive-pack[1] when it reacts to 319`git push` and updates reference(s) in its repository. 320It executes on the remote repository once after all the refs have 321been updated. 322 323This hook executes once for the receive operation. It takes no 324arguments, but gets the same information as the 325<<pre-receive,'pre-receive'>> 326hook does on its standard input. 327 328This hook does not affect the outcome of `git receive-pack`, as it 329is called after the real work is done. 330 331This supersedes the <<post-update,'post-update'>> hook in that it gets 332both old and new values of all the refs in addition to their 333names. 334 335Both standard output and standard error output are forwarded to 336`git send-pack` on the other end, so you can simply `echo` messages 337for the user. 338 339The default 'post-receive' hook is empty, but there is 340a sample script `post-receive-email` provided in the `contrib/hooks` 341directory in Git distribution, which implements sending commit 342emails. 343 344The number of push options given on the command line of 345`git push --push-option=...` can be read from the environment 346variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are 347found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... 348If it is negotiated to not use the push options phase, the 349environment variables will not be set. If the client selects 350to use push options, but doesn't transmit any, the count variable 351will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. 352 353[[post-update]] 354post-update 355~~~~~~~~~~~ 356 357This hook is invoked by linkgit:git-receive-pack[1] when it reacts to 358`git push` and updates reference(s) in its repository. 359It executes on the remote repository once after all the refs have 360been updated. 361 362It takes a variable number of parameters, each of which is the 363name of ref that was actually updated. 364 365This hook is meant primarily for notification, and cannot affect 366the outcome of `git receive-pack`. 367 368The 'post-update' hook can tell what are the heads that were pushed, 369but it does not know what their original and updated values are, 370so it is a poor place to do log old..new. The 371<<post-receive,'post-receive'>> hook does get both original and 372updated values of the refs. You might consider it instead if you need 373them. 374 375When enabled, the default 'post-update' hook runs 376`git update-server-info` to keep the information used by dumb 377transports (e.g., HTTP) up to date. If you are publishing 378a Git repository that is accessible via HTTP, you should 379probably enable this hook. 380 381Both standard output and standard error output are forwarded to 382`git send-pack` on the other end, so you can simply `echo` messages 383for the user. 384 385push-to-checkout 386~~~~~~~~~~~~~~~~ 387 388This hook is invoked by linkgit:git-receive-pack[1] when it reacts to 389`git push` and updates reference(s) in its repository, and when 390the push tries to update the branch that is currently checked out 391and the `receive.denyCurrentBranch` configuration variable is set to 392`updateInstead`. Such a push by default is refused if the working 393tree and the index of the remote repository has any difference from 394the currently checked out commit; when both the working tree and the 395index match the current commit, they are updated to match the newly 396pushed tip of the branch. This hook is to be used to override the 397default behaviour. 398 399The hook receives the commit with which the tip of the current 400branch is going to be updated. It can exit with a non-zero status 401to refuse the push (when it does so, it must not modify the index or 402the working tree). Or it can make any necessary changes to the 403working tree and to the index to bring them to the desired state 404when the tip of the current branch is updated to the new commit, and 405exit with a zero status. 406 407For example, the hook can simply run `git read-tree -u -m HEAD "$1"` 408in order to emulate `git fetch` that is run in the reverse direction 409with `git push`, as the two-tree form of `git read-tree -u -m` is 410essentially the same as `git switch` or `git checkout` 411that switches branches while 412keeping the local changes in the working tree that do not interfere 413with the difference between the branches. 414 415 416pre-auto-gc 417~~~~~~~~~~~ 418 419This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It 420takes no parameter, and exiting with non-zero status from this script 421causes the `git gc --auto` to abort. 422 423post-rewrite 424~~~~~~~~~~~~ 425 426This hook is invoked by commands that rewrite commits 427(linkgit:git-commit[1] when called with `--amend` and 428linkgit:git-rebase[1]; however, full-history (re)writing tools like 429linkgit:git-fast-import[1] or 430https://github.com/newren/git-filter-repo[git-filter-repo] typically 431do not call it!). Its first argument denotes the command it was 432invoked by: currently one of `amend` or `rebase`. Further 433command-dependent arguments may be passed in the future. 434 435The hook receives a list of the rewritten commits on stdin, in the 436format 437 438 <old-sha1> SP <new-sha1> [ SP <extra-info> ] LF 439 440The 'extra-info' is again command-dependent. If it is empty, the 441preceding SP is also omitted. Currently, no commands pass any 442'extra-info'. 443 444The hook always runs after the automatic note copying (see 445"notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and 446thus has access to these notes. 447 448The following command-specific comments apply: 449 450rebase:: 451 For the 'squash' and 'fixup' operation, all commits that were 452 squashed are listed as being rewritten to the squashed commit. 453 This means that there will be several lines sharing the same 454 'new-sha1'. 455+ 456The commits are guaranteed to be listed in the order that they were 457processed by rebase. 458 459sendemail-validate 460~~~~~~~~~~~~~~~~~~ 461 462This hook is invoked by linkgit:git-send-email[1]. It takes a single parameter, 463the name of the file that holds the e-mail to be sent. Exiting with a 464non-zero status causes `git send-email` to abort before sending any 465e-mails. 466 467fsmonitor-watchman 468~~~~~~~~~~~~~~~~~~ 469 470This hook is invoked when the configuration option `core.fsmonitor` is 471set to `.git/hooks/fsmonitor-watchman`. It takes two arguments, a version 472(currently 1) and the time in elapsed nanoseconds since midnight, 473January 1, 1970. 474 475The hook should output to stdout the list of all files in the working 476directory that may have changed since the requested time. The logic 477should be inclusive so that it does not miss any potential changes. 478The paths should be relative to the root of the working directory 479and be separated by a single NUL. 480 481It is OK to include files which have not actually changed. All changes 482including newly-created and deleted files should be included. When 483files are renamed, both the old and the new name should be included. 484 485Git will limit what files it checks for changes as well as which 486directories are checked for untracked files based on the path names 487given. 488 489An optimized way to tell git "all files have changed" is to return 490the filename `/`. 491 492The exit status determines whether git will use the data from the 493hook to limit its search. On error, it will fall back to verifying 494all files and folders. 495 496p4-pre-submit 497~~~~~~~~~~~~~ 498 499This hook is invoked by `git-p4 submit`. It takes no parameters and nothing 500from standard input. Exiting with non-zero status from this script prevent 501`git-p4 submit` from launching. Run `git-p4 submit --help` for details. 502 503post-index-change 504~~~~~~~~~~~~~~~~~ 505 506This hook is invoked when the index is written in read-cache.c 507do_write_locked_index. 508 509The first parameter passed to the hook is the indicator for the 510working directory being updated. "1" meaning working directory 511was updated or "0" when the working directory was not updated. 512 513The second parameter passed to the hook is the indicator for whether 514or not the index was updated and the skip-worktree bit could have 515changed. "1" meaning skip-worktree bits could have been updated 516and "0" meaning they were not. 517 518Only one parameter should be set to "1" when the hook runs. The hook 519running passing "1", "1" should not be possible. 520 521GIT 522--- 523Part of the linkgit:git[1] suite