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