1Hooks used by git 2================= 3 4Hooks are little scripts you can place in `$GIT_DIR/hooks` 5directory to trigger action at certain points. When 6`git-init` is run, a handful example hooks are copied in the 7`hooks` directory of the new repository, but by default they are 8all disabled. To enable a hook, make it executable with `chmod +x`. 9 10This document describes the currently defined hooks. 11 12applypatch-msg 13-------------- 14 15This hook is invoked by `git-am` script. It takes a single 16parameter, the name of the file that holds the proposed commit 17log message. Exiting with non-zero status causes 18`git-am` to abort before applying the patch. 19 20The hook is allowed to edit the message file in place, and can 21be used to normalize the message into some project standard 22format (if the project has one). It can also be used to refuse 23the commit after inspecting the message file. 24 25The default 'applypatch-msg' hook, when enabled, runs the 26'commit-msg' hook, if the latter is enabled. 27 28pre-applypatch 29-------------- 30 31This hook is invoked by `git-am`. It takes no parameter, 32and is invoked after the patch is applied, but before a commit 33is made. Exiting with non-zero status causes the working tree 34after application of the patch not committed. 35 36It can be used to inspect the current working tree and refuse to 37make a commit if it does not pass certain test. 38 39The default 'pre-applypatch' hook, when enabled, runs the 40'pre-commit' hook, if the latter is enabled. 41 42post-applypatch 43--------------- 44 45This hook is invoked by `git-am`. It takes no parameter, 46and is invoked after the patch is applied and a commit is made. 47 48This hook is meant primarily for notification, and cannot affect 49the outcome of `git-am`. 50 51pre-commit 52---------- 53 54This hook is invoked by `git-commit`, and can be bypassed 55with `\--no-verify` option. It takes no parameter, and is 56invoked before obtaining the proposed commit log message and 57making a commit. Exiting with non-zero status from this script 58causes the `git-commit` to abort. 59 60The default 'pre-commit' hook, when enabled, catches introduction 61of lines with trailing whitespaces and aborts the commit when 62such a line is found. 63 64All the `git-commit` hooks are invoked with the environment 65variable `GIT_EDITOR=:` if the command will not bring up an editor 66to modify the commit message. 67 68commit-msg 69---------- 70 71This hook is invoked by `git-commit`, and can be bypassed 72with `\--no-verify` option. It takes a single parameter, the 73name of the file that holds the proposed commit log message. 74Exiting with non-zero status causes the `git-commit` to 75abort. 76 77The hook is allowed to edit the message file in place, and can 78be used to normalize the message into some project standard 79format (if the project has one). It can also be used to refuse 80the commit after inspecting the message file. 81 82The default 'commit-msg' hook, when enabled, detects duplicate 83"Signed-off-by" lines, and aborts the commit if one is found. 84 85post-commit 86----------- 87 88This hook is invoked by `git-commit`. It takes no 89parameter, and is invoked after a commit is made. 90 91This hook is meant primarily for notification, and cannot affect 92the outcome of `git-commit`. 93 94post-checkout 95----------- 96 97This hook is invoked when a `git-checkout` is run after having updated the 98worktree. The hook is given three parameters: the ref of the previous HEAD, 99the ref of the new HEAD (which may or may not have changed), and a flag 100indicating whether the checkout was a branch checkout (changing branches, 101flag=1) or a file checkout (retrieving a file from the index, flag=0). 102This hook cannot affect the outcome of `git-checkout`. 103 104This hook can be used to perform repository validity checks, auto-display 105differences from the previous HEAD if different, or set working dir metadata 106properties. 107 108post-merge 109----------- 110 111This hook is invoked by `git-merge`, which happens when a `git pull` 112is done on a local repository. The hook takes a single parameter, a status 113flag specifying whether or not the merge being done was a squash merge. 114This hook cannot affect the outcome of `git-merge`. 115 116This hook can be used in conjunction with a corresponding pre-commit hook to 117save and restore any form of metadata associated with the working tree 118(eg: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl 119for an example of how to do this. 120 121[[pre-receive]] 122pre-receive 123----------- 124 125This hook is invoked by `git-receive-pack` on the remote repository, 126which happens when a `git push` is done on a local repository. 127Just before starting to update refs on the remote repository, the 128pre-receive hook is invoked. Its exit status determines the success 129or failure of the update. 130 131This hook executes once for the receive operation. It takes no 132arguments, but for each ref to be updated it receives on standard 133input a line of the format: 134 135 <old-value> SP <new-value> SP <ref-name> LF 136 137where `<old-value>` is the old object name stored in the ref, 138`<new-value>` is the new object name to be stored in the ref and 139`<ref-name>` is the full name of the ref. 140When creating a new ref, `<old-value>` is 40 `0`. 141 142If the hook exits with non-zero status, none of the refs will be 143updated. If the hook exits with zero, updating of individual refs can 144still be prevented by the <<update,'update'>> hook. 145 146Both standard output and standard error output are forwarded to 147`git-send-pack` on the other end, so you can simply `echo` messages 148for the user. 149 150[[update]] 151update 152------ 153 154This hook is invoked by `git-receive-pack` on the remote repository, 155which happens when a `git push` is done on a local repository. 156Just before updating the ref on the remote repository, the update hook 157is invoked. Its exit status determines the success or failure of 158the ref update. 159 160The hook executes once for each ref to be updated, and takes 161three parameters: 162 163 - the name of the ref being updated, 164 - the old object name stored in the ref, 165 - and the new objectname to be stored in the ref. 166 167A zero exit from the update hook allows the ref to be updated. 168Exiting with a non-zero status prevents `git-receive-pack` 169from updating that ref. 170 171This hook can be used to prevent 'forced' update on certain refs by 172making sure that the object name is a commit object that is a 173descendant of the commit object named by the old object name. 174That is, to enforce a "fast forward only" policy. 175 176It could also be used to log the old..new status. However, it 177does not know the entire set of branches, so it would end up 178firing one e-mail per ref when used naively, though. The 179<<post-receive,'post-receive'>> hook is more suited to that. 180 181Another use suggested on the mailing list is to use this hook to 182implement access control which is finer grained than the one 183based on filesystem group. 184 185Both standard output and standard error output are forwarded to 186`git-send-pack` on the other end, so you can simply `echo` messages 187for the user. 188 189The default 'update' hook, when enabled--and with 190`hooks.allowunannotated` config option turned on--prevents 191unannotated tags to be pushed. 192 193[[post-receive]] 194post-receive 195------------ 196 197This hook is invoked by `git-receive-pack` on the remote repository, 198which happens when a `git push` is done on a local repository. 199It executes on the remote repository once after all the refs have 200been updated. 201 202This hook executes once for the receive operation. It takes no 203arguments, but gets the same information as the 204<<pre-receive,'pre-receive'>> 205hook does on its standard input. 206 207This hook does not affect the outcome of `git-receive-pack`, as it 208is called after the real work is done. 209 210This supersedes the <<post-update,'post-update'>> hook in that it gets 211both old and new values of all the refs in addition to their 212names. 213 214Both standard output and standard error output are forwarded to 215`git-send-pack` on the other end, so you can simply `echo` messages 216for the user. 217 218The default 'post-receive' hook is empty, but there is 219a sample script `post-receive-email` provided in the `contrib/hooks` 220directory in git distribution, which implements sending commit 221emails. 222 223[[post-update]] 224post-update 225----------- 226 227This hook is invoked by `git-receive-pack` on the remote repository, 228which happens when a `git push` is done on a local repository. 229It executes on the remote repository once after all the refs have 230been updated. 231 232It takes a variable number of parameters, each of which is the 233name of ref that was actually updated. 234 235This hook is meant primarily for notification, and cannot affect 236the outcome of `git-receive-pack`. 237 238The 'post-update' hook can tell what are the heads that were pushed, 239but it does not know what their original and updated values are, 240so it is a poor place to do log old..new. The 241<<post-receive,'post-receive'>> hook does get both original and 242updated values of the refs. You might consider it instead if you need 243them. 244 245When enabled, the default 'post-update' hook runs 246`git-update-server-info` to keep the information used by dumb 247transports (e.g., HTTP) up-to-date. If you are publishing 248a git repository that is accessible via HTTP, you should 249probably enable this hook. 250 251Both standard output and standard error output are forwarded to 252`git-send-pack` on the other end, so you can simply `echo` messages 253for the user.