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