| 1 | githooks(5) |
| 2 | =========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | githooks - Hooks used by Git |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | $GIT_DIR/hooks/* (or \`git config core.hooksPath`/*) |
| 11 | |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | |
| 16 | Hooks are programs you can place in a hooks directory to trigger |
| 17 | actions at certain points in git's execution. Hooks that don't have |
| 18 | the executable bit set are ignored. |
| 19 | |
| 20 | By default the hooks directory is `$GIT_DIR/hooks`, but that can be |
| 21 | changed via the `core.hooksPath` configuration variable (see |
| 22 | linkgit:git-config[1]). |
| 23 | |
| 24 | Before 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 |
| 26 | repository. An exception are hooks triggered during a push ('pre-receive', |
| 27 | 'update', 'post-receive', 'post-update', 'push-to-checkout') which are always |
| 28 | executed in $GIT_DIR. |
| 29 | |
| 30 | Environment variables, such as `GIT_DIR`, `GIT_WORK_TREE`, etc., are exported |
| 31 | so that Git commands run by the hook can correctly locate the repository. If |
| 32 | your hook needs to invoke Git commands in a foreign repository or in a |
| 33 | different working tree of the same repository, then it should clear these |
| 34 | environment variables so they do not interfere with Git operations at the |
| 35 | foreign location. For example: |
| 36 | |
| 37 | ------------ |
| 38 | local_desc=$(git describe) |
| 39 | foreign_desc=$(unset $(git rev-parse --local-env-vars); git -C ../foreign-repo describe) |
| 40 | ------------ |
| 41 | |
| 42 | Hooks can get their arguments via the environment, command-line |
| 43 | arguments, and stdin. See the documentation for each hook below for |
| 44 | details. |
| 45 | |
| 46 | `git init` may copy hooks to the new repository, depending on its |
| 47 | configuration. See the "TEMPLATE DIRECTORY" section in |
| 48 | linkgit:git-init[1] for details. When the rest of this document refers |
| 49 | to "default hooks" it's talking about the default template shipped |
| 50 | with Git. |
| 51 | |
| 52 | The currently supported hooks are described below. |
| 53 | |
| 54 | HOOKS |
| 55 | ----- |
| 56 | |
| 57 | applypatch-msg |
| 58 | ~~~~~~~~~~~~~~ |
| 59 | |
| 60 | This hook is invoked by linkgit:git-am[1]. It takes a single |
| 61 | parameter, the name of the file that holds the proposed commit |
| 62 | log message. Exiting with a non-zero status causes `git am` to abort |
| 63 | before applying the patch. |
| 64 | |
| 65 | The hook is allowed to edit the message file in place, and can |
| 66 | be used to normalize the message into some project standard |
| 67 | format. It can also be used to refuse the commit after inspecting |
| 68 | the message file. |
| 69 | |
| 70 | The default 'applypatch-msg' hook, when enabled, runs the |
| 71 | 'commit-msg' hook, if the latter is enabled. |
| 72 | |
| 73 | pre-applypatch |
| 74 | ~~~~~~~~~~~~~~ |
| 75 | |
| 76 | This hook is invoked by linkgit:git-am[1]. It takes no parameter, and is |
| 77 | invoked after the patch is applied, but before a commit is made. |
| 78 | |
| 79 | If it exits with non-zero status, then the working tree will not be |
| 80 | committed after applying the patch. |
| 81 | |
| 82 | It can be used to inspect the current working tree and refuse to |
| 83 | make a commit if it does not pass certain tests. |
| 84 | |
| 85 | The default 'pre-applypatch' hook, when enabled, runs the |
| 86 | 'pre-commit' hook, if the latter is enabled. |
| 87 | |
| 88 | post-applypatch |
| 89 | ~~~~~~~~~~~~~~~ |
| 90 | |
| 91 | This hook is invoked by linkgit:git-am[1]. It takes no parameter, |
| 92 | and is invoked after the patch is applied and a commit is made. |
| 93 | |
| 94 | This hook is meant primarily for notification, and cannot affect |
| 95 | the outcome of `git am`. |
| 96 | |
| 97 | pre-commit |
| 98 | ~~~~~~~~~~ |
| 99 | |
| 100 | This hook is invoked by linkgit:git-commit[1], and can be bypassed |
| 101 | with the `--no-verify` option. It takes no parameters, and is |
| 102 | invoked before obtaining the proposed commit log message and |
| 103 | making a commit. Exiting with a non-zero status from this script |
| 104 | causes the `git commit` command to abort before creating a commit. |
| 105 | |
| 106 | All the `git commit` hooks are invoked with the environment |
| 107 | variable `GIT_EDITOR=:` if the command will not bring up an editor |
| 108 | to modify the commit message. |
| 109 | |
| 110 | The default 'pre-commit' hook, when enabled, prevents the introduction |
| 111 | of non-ASCII filenames and lines with trailing whitespace. The non-ASCII |
| 112 | check can be turned off by setting the `hooks.allownonascii` config |
| 113 | option to `true`. |
| 114 | |
| 115 | pre-merge-commit |
| 116 | ~~~~~~~~~~~~~~~~ |
| 117 | |
| 118 | This hook is invoked by linkgit:git-merge[1], and can be bypassed |
| 119 | with the `--no-verify` option. It takes no parameters, and is |
| 120 | invoked after the merge has been carried out successfully and before |
| 121 | obtaining the proposed commit log message to |
| 122 | make a commit. Exiting with a non-zero status from this script |
| 123 | causes the `git merge` command to abort before creating a commit. |
| 124 | |
| 125 | The default 'pre-merge-commit' hook, when enabled, runs the |
| 126 | 'pre-commit' hook, if the latter is enabled. |
| 127 | |
| 128 | This hook is invoked with the environment variable |
| 129 | `GIT_EDITOR=:` if the command will not bring up an editor |
| 130 | to modify the commit message. |
| 131 | |
| 132 | If the merge cannot be carried out automatically, the conflicts |
| 133 | need to be resolved and the result committed separately (see |
| 134 | linkgit:git-merge[1]). At that point, this hook will not be executed, |
| 135 | but the 'pre-commit' hook will, if it is enabled. |
| 136 | |
| 137 | prepare-commit-msg |
| 138 | ~~~~~~~~~~~~~~~~~~ |
| 139 | |
| 140 | This hook is invoked by linkgit:git-commit[1] right after preparing the |
| 141 | default log message, and before the editor is started. |
| 142 | |
| 143 | It takes one to three parameters. The first is the name of the file |
| 144 | that contains the commit log message. The second is the source of the commit |
| 145 | message, and can be: `message` (if a `-m` or `-F` option was |
| 146 | given); `template` (if a `-t` option was given or the |
| 147 | configuration option `commit.template` is set); `merge` (if the |
| 148 | commit is a merge or a `.git/MERGE_MSG` file exists); `squash` |
| 149 | (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by |
| 150 | a commit object name (if a `-c`, `-C` or `--amend` option was given). |
| 151 | |
| 152 | If the exit status is non-zero, `git commit` will abort. |
| 153 | |
| 154 | The purpose of the hook is to edit the message file in place, and |
| 155 | it is not suppressed by the `--no-verify` option. A non-zero exit |
| 156 | means a failure of the hook and aborts the commit. It should not |
| 157 | be used as a replacement for the pre-commit hook. |
| 158 | |
| 159 | The sample `prepare-commit-msg` hook that comes with Git removes the |
| 160 | help message found in the commented portion of the commit template. |
| 161 | |
| 162 | commit-msg |
| 163 | ~~~~~~~~~~ |
| 164 | |
| 165 | This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and can be |
| 166 | bypassed with the `--no-verify` option. It takes a single parameter, |
| 167 | the name of the file that holds the proposed commit log message. |
| 168 | Exiting with a non-zero status causes the command to abort. |
| 169 | |
| 170 | The hook is allowed to edit the message file in place, and can be used |
| 171 | to normalize the message into some project standard format. It |
| 172 | can also be used to refuse the commit after inspecting the message |
| 173 | file. |
| 174 | |
| 175 | The default 'commit-msg' hook, when enabled, detects duplicate |
| 176 | `Signed-off-by` trailers, and aborts the commit if one is found. |
| 177 | |
| 178 | post-commit |
| 179 | ~~~~~~~~~~~ |
| 180 | |
| 181 | This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is |
| 182 | invoked after a commit is made. |
| 183 | |
| 184 | This hook is meant primarily for notification, and cannot affect |
| 185 | the outcome of `git commit`. |
| 186 | |
| 187 | pre-rebase |
| 188 | ~~~~~~~~~~ |
| 189 | |
| 190 | This hook is called by linkgit:git-rebase[1] and can be used to prevent a |
| 191 | branch from getting rebased. The hook may be called with one or |
| 192 | two parameters. The first parameter is the upstream from which |
| 193 | the series was forked. The second parameter is the branch being |
| 194 | rebased, and is not set when rebasing the current branch. |
| 195 | |
| 196 | post-checkout |
| 197 | ~~~~~~~~~~~~~ |
| 198 | |
| 199 | This hook is invoked when a linkgit:git-checkout[1] or |
| 200 | linkgit:git-switch[1] is run after having updated the |
| 201 | worktree. The hook is given three parameters: the ref of the previous HEAD, |
| 202 | the ref of the new HEAD (which may or may not have changed), and a flag |
| 203 | indicating whether the checkout was a branch checkout (changing branches, |
| 204 | flag=1) or a file checkout (retrieving a file from the index, flag=0). |
| 205 | This hook cannot affect the outcome of `git switch` or `git checkout`, |
| 206 | other than that the hook's exit status becomes the exit status of |
| 207 | these two commands. |
| 208 | |
| 209 | It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is |
| 210 | used. The first parameter given to the hook is the null-ref, the second the |
| 211 | ref of the new HEAD and the flag is always 1. Likewise for `git worktree add` |
| 212 | unless `--no-checkout` is used. |
| 213 | |
| 214 | This hook can be used to perform repository validity checks, auto-display |
| 215 | differences from the previous HEAD if different, or set working dir metadata |
| 216 | properties. |
| 217 | |
| 218 | post-merge |
| 219 | ~~~~~~~~~~ |
| 220 | |
| 221 | This hook is invoked by linkgit:git-merge[1], which happens when a `git pull` |
| 222 | is done on a local repository. The hook takes a single parameter, a status |
| 223 | flag specifying whether or not the merge being done was a squash merge. |
| 224 | This hook cannot affect the outcome of `git merge` and is not executed, |
| 225 | if the merge failed due to conflicts. |
| 226 | |
| 227 | This hook can be used in conjunction with a corresponding pre-commit hook to |
| 228 | save and restore any form of metadata associated with the working tree |
| 229 | (e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl |
| 230 | for an example of how to do this. |
| 231 | |
| 232 | pre-push |
| 233 | ~~~~~~~~ |
| 234 | |
| 235 | This hook is called by linkgit:git-push[1] and can be used to prevent |
| 236 | a push from taking place. The hook is called with two parameters |
| 237 | which provide the name and location of the destination remote, if a |
| 238 | named remote is not being used both values will be the same. |
| 239 | |
| 240 | Information about what is to be pushed is provided on the hook's standard |
| 241 | input with lines of the form: |
| 242 | |
| 243 | <local-ref> SP <local-object-name> SP <remote-ref> SP <remote-object-name> LF |
| 244 | |
| 245 | For instance, if the command +git push origin master:foreign+ were run the |
| 246 | hook would receive a line like the following: |
| 247 | |
| 248 | refs/heads/master 67890 refs/heads/foreign 12345 |
| 249 | |
| 250 | although the full object name would be supplied. If the foreign ref does not |
| 251 | yet exist the `<remote-object-name>` will be the all-zeroes object name. If a |
| 252 | ref is to be deleted, the `<local-ref>` will be supplied as `(delete)` and the |
| 253 | `<local-object-name>` will be the all-zeroes object name. If the local commit |
| 254 | was specified by something other than a name which could be expanded (such as |
| 255 | `HEAD~`, or an object name) it will be supplied as it was originally given. |
| 256 | |
| 257 | If this hook exits with a non-zero status, `git push` will abort without |
| 258 | pushing anything. Information about why the push is rejected may be sent |
| 259 | to the user by writing to standard error. |
| 260 | |
| 261 | [[pre-receive]] |
| 262 | pre-receive |
| 263 | ~~~~~~~~~~~ |
| 264 | |
| 265 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 266 | `git push` and updates reference(s) in its repository. |
| 267 | Just before starting to update refs on the remote repository, the |
| 268 | pre-receive hook is invoked. Its exit status determines the success |
| 269 | or failure of the update. |
| 270 | |
| 271 | This hook executes once for the receive operation. It takes no |
| 272 | arguments, but for each ref to be updated it receives on standard |
| 273 | input a line of the format: |
| 274 | |
| 275 | <old-oid> SP <new-oid> SP <ref-name> LF |
| 276 | |
| 277 | where `<old-oid>` is the old object name stored in the ref, |
| 278 | `<new-oid>` is the new object name to be stored in the ref and |
| 279 | `<ref-name>` is the full name of the ref. |
| 280 | When creating a new ref, `<old-oid>` is the all-zeroes object name. |
| 281 | |
| 282 | If the hook exits with non-zero status, none of the refs will be |
| 283 | updated. If the hook exits with zero, updating of individual refs can |
| 284 | still be prevented by the <<update,'update'>> hook. |
| 285 | |
| 286 | Both standard output and standard error output are forwarded to |
| 287 | `git send-pack` on the other end, so you can simply `echo` messages |
| 288 | for the user. |
| 289 | |
| 290 | The number of push options given on the command line of |
| 291 | `git push --push-option=...` can be read from the environment |
| 292 | variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are |
| 293 | found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... |
| 294 | If it is negotiated to not use the push options phase, the |
| 295 | environment variables will not be set. If the client selects |
| 296 | to use push options, but doesn't transmit any, the count variable |
| 297 | will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. |
| 298 | |
| 299 | See the section on "Quarantine Environment" in |
| 300 | linkgit:git-receive-pack[1] for some caveats. |
| 301 | |
| 302 | [[update]] |
| 303 | update |
| 304 | ~~~~~~ |
| 305 | |
| 306 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 307 | `git push` and updates reference(s) in its repository. |
| 308 | Just before updating the ref on the remote repository, the update hook |
| 309 | is invoked. Its exit status determines the success or failure of |
| 310 | the ref update. |
| 311 | |
| 312 | The hook executes once for each ref to be updated, and takes |
| 313 | three parameters: |
| 314 | |
| 315 | - the name of the ref being updated, |
| 316 | - the old object name stored in the ref, |
| 317 | - and the new object name to be stored in the ref. |
| 318 | |
| 319 | A zero exit from the update hook allows the ref to be updated. |
| 320 | Exiting with a non-zero status prevents `git receive-pack` |
| 321 | from updating that ref. |
| 322 | |
| 323 | This hook can be used to prevent 'forced' update on certain refs by |
| 324 | making sure that the object name is a commit object that is a |
| 325 | descendant of the commit object named by the old object name. |
| 326 | That is, to enforce a "fast-forward only" policy. |
| 327 | |
| 328 | It could also be used to log the old..new status. However, it |
| 329 | does not know the entire set of branches, so it would end up |
| 330 | firing one e-mail per ref when used naively, though. The |
| 331 | <<post-receive,'post-receive'>> hook is more suited to that. |
| 332 | |
| 333 | In an environment that restricts the users' access only to git |
| 334 | commands over the wire, this hook can be used to implement access |
| 335 | control without relying on filesystem ownership and group |
| 336 | membership. See linkgit:git-shell[1] for how you might use the login |
| 337 | shell to restrict the user's access to only git commands. |
| 338 | |
| 339 | Both standard output and standard error output are forwarded to |
| 340 | `git send-pack` on the other end, so you can simply `echo` messages |
| 341 | for the user. |
| 342 | |
| 343 | The default 'update' hook, when enabled--and with |
| 344 | `hooks.allowunannotated` config option unset or set to false--prevents |
| 345 | unannotated tags from being pushed. |
| 346 | |
| 347 | [[proc-receive]] |
| 348 | proc-receive |
| 349 | ~~~~~~~~~~~~ |
| 350 | |
| 351 | This hook is invoked by linkgit:git-receive-pack[1]. If the server has |
| 352 | set the multi-valued config variable `receive.procReceiveRefs`, and the |
| 353 | commands sent to 'receive-pack' have matching reference names, these |
| 354 | commands will be executed by this hook, instead of by the internal |
| 355 | `execute_commands()` function. This hook is responsible for updating |
| 356 | the relevant references and reporting the results back to 'receive-pack'. |
| 357 | |
| 358 | This hook executes once for the receive operation. It takes no |
| 359 | arguments, but uses a pkt-line format protocol to communicate with |
| 360 | 'receive-pack' to read commands, push-options and send results. In the |
| 361 | following example for the protocol, the letter 'S' stands for |
| 362 | 'receive-pack' and the letter 'H' stands for this hook. |
| 363 | |
| 364 | # Version and features negotiation. |
| 365 | S: PKT-LINE(version=1\0push-options atomic...) |
| 366 | S: flush-pkt |
| 367 | H: PKT-LINE(version=1\0push-options...) |
| 368 | H: flush-pkt |
| 369 | |
| 370 | # Send commands from server to the hook. |
| 371 | S: PKT-LINE(<old-oid> <new-oid> <ref>) |
| 372 | S: ... ... |
| 373 | S: flush-pkt |
| 374 | # Send push-options only if the 'push-options' feature is enabled. |
| 375 | S: PKT-LINE(push-option) |
| 376 | S: ... ... |
| 377 | S: flush-pkt |
| 378 | |
| 379 | # Receive results from the hook. |
| 380 | # OK, run this command successfully. |
| 381 | H: PKT-LINE(ok <ref>) |
| 382 | # NO, I reject it. |
| 383 | H: PKT-LINE(ng <ref> <reason>) |
| 384 | # Fall through, let 'receive-pack' execute it. |
| 385 | H: PKT-LINE(ok <ref>) |
| 386 | H: PKT-LINE(option fall-through) |
| 387 | # OK, but has an alternate reference. The alternate reference name |
| 388 | # and other status can be given in option directives. |
| 389 | H: PKT-LINE(ok <ref>) |
| 390 | H: PKT-LINE(option refname <refname>) |
| 391 | H: PKT-LINE(option old-oid <old-oid>) |
| 392 | H: PKT-LINE(option new-oid <new-oid>) |
| 393 | H: PKT-LINE(option forced-update) |
| 394 | H: ... ... |
| 395 | H: flush-pkt |
| 396 | |
| 397 | Each command for the 'proc-receive' hook may point to a pseudo-reference |
| 398 | and always has a zero-old as its old-oid, while the 'proc-receive' hook |
| 399 | may update an alternate reference and the alternate reference may exist |
| 400 | already with a non-zero old-oid. For this case, this hook will use |
| 401 | "option" directives to report extended attributes for the reference given |
| 402 | by the leading "ok" directive. |
| 403 | |
| 404 | The report of the commands of this hook should have the same order as |
| 405 | the input. The exit status of the 'proc-receive' hook only determines |
| 406 | the success or failure of the group of commands sent to it, unless |
| 407 | atomic push is in use. |
| 408 | |
| 409 | [[post-receive]] |
| 410 | post-receive |
| 411 | ~~~~~~~~~~~~ |
| 412 | |
| 413 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 414 | `git push` and updates reference(s) in its repository. |
| 415 | The hook executes on the remote repository once after all the proposed |
| 416 | ref updates are processed and if at least one ref is updated as the |
| 417 | result. |
| 418 | |
| 419 | The hook takes no arguments. It receives one line on standard input for |
| 420 | each ref that is successfully updated following the same format as the |
| 421 | <<pre-receive,'pre-receive'>> hook. |
| 422 | |
| 423 | This hook does not affect the outcome of `git receive-pack`, as it |
| 424 | is called after the real work is done. |
| 425 | |
| 426 | This supersedes the <<post-update,'post-update'>> hook in that it gets |
| 427 | both old and new values of all the refs in addition to their |
| 428 | names. |
| 429 | |
| 430 | Both standard output and standard error output are forwarded to |
| 431 | `git send-pack` on the other end, so you can simply `echo` messages |
| 432 | for the user. |
| 433 | |
| 434 | The default 'post-receive' hook is empty, but there is |
| 435 | a sample script `post-receive-email` provided in the `contrib/hooks` |
| 436 | directory in Git distribution, which implements sending commit |
| 437 | emails. |
| 438 | |
| 439 | The number of push options given on the command line of |
| 440 | `git push --push-option=...` can be read from the environment |
| 441 | variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are |
| 442 | found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,... |
| 443 | If it is negotiated to not use the push options phase, the |
| 444 | environment variables will not be set. If the client selects |
| 445 | to use push options, but doesn't transmit any, the count variable |
| 446 | will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. |
| 447 | |
| 448 | See the "post-receive" section in linkgit:git-receive-pack[1] for |
| 449 | additional details. |
| 450 | |
| 451 | [[post-update]] |
| 452 | post-update |
| 453 | ~~~~~~~~~~~ |
| 454 | |
| 455 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 456 | `git push` and updates reference(s) in its repository. |
| 457 | It executes on the remote repository once after all the refs have |
| 458 | been updated. |
| 459 | |
| 460 | It takes a variable number of parameters, each of which is the |
| 461 | name of ref that was actually updated. |
| 462 | |
| 463 | This hook is meant primarily for notification, and cannot affect |
| 464 | the outcome of `git receive-pack`. |
| 465 | |
| 466 | The 'post-update' hook can tell what are the heads that were pushed, |
| 467 | but it does not know what their original and updated values are, |
| 468 | so it is a poor place to do log old..new. The |
| 469 | <<post-receive,'post-receive'>> hook does get both original and |
| 470 | updated values of the refs. You might consider it instead if you need |
| 471 | them. |
| 472 | |
| 473 | When enabled, the default 'post-update' hook runs |
| 474 | `git update-server-info` to keep the information used by dumb |
| 475 | transports (e.g., HTTP) up to date. If you are publishing |
| 476 | a Git repository that is accessible via HTTP, you should |
| 477 | probably enable this hook. |
| 478 | |
| 479 | Both standard output and standard error output are forwarded to |
| 480 | `git send-pack` on the other end, so you can simply `echo` messages |
| 481 | for the user. |
| 482 | |
| 483 | reference-transaction |
| 484 | ~~~~~~~~~~~~~~~~~~~~~ |
| 485 | |
| 486 | This hook is invoked by any Git command that performs reference |
| 487 | updates. It executes whenever a reference transaction is preparing, |
| 488 | prepared, committed or aborted and may thus get called multiple times. |
| 489 | The hook also supports symbolic reference updates. |
| 490 | |
| 491 | The hook takes exactly one argument, which is the current state the |
| 492 | given reference transaction is in: |
| 493 | |
| 494 | - "preparing": All reference updates have been queued to the |
| 495 | transaction but references are not yet locked on disk. |
| 496 | |
| 497 | - "prepared": All reference updates have been queued to the |
| 498 | transaction and references were locked on disk. |
| 499 | |
| 500 | - "committed": The reference transaction was committed and all |
| 501 | references now have their respective new value. |
| 502 | |
| 503 | - "aborted": The reference transaction was aborted, no changes |
| 504 | were performed and the locks have been released. |
| 505 | |
| 506 | For each reference update that was added to the transaction, the hook |
| 507 | receives on standard input a line of the format: |
| 508 | |
| 509 | <old-value> SP <new-value> SP <ref-name> LF |
| 510 | |
| 511 | where `<old-value>` is the old object name passed into the reference |
| 512 | transaction, `<new-value>` is the new object name to be stored in the |
| 513 | ref and `<ref-name>` is the full name of the ref. When force updating |
| 514 | the reference regardless of its current value or when the reference is |
| 515 | to be created anew, `<old-value>` is the all-zeroes object name. To |
| 516 | distinguish these cases, you can inspect the current value of |
| 517 | `<ref-name>` via `git rev-parse`. During the "preparing" state, symbolic |
| 518 | references are not resolved: `<ref-name>` will reflect the symbolic reference |
| 519 | itself rather than the object it points to. |
| 520 | |
| 521 | For symbolic reference updates the `<old_value>` and `<new-value>` |
| 522 | fields could denote references instead of objects. A reference will be |
| 523 | denoted with a 'ref:' prefix, like `ref:<ref-target>`. |
| 524 | |
| 525 | The exit status of the hook is ignored for any state except for the |
| 526 | "preparing" and "prepared" states. In these states, a non-zero exit |
| 527 | status will cause the transaction to be aborted. The hook will not be |
| 528 | called with "aborted" state in that case. |
| 529 | |
| 530 | push-to-checkout |
| 531 | ~~~~~~~~~~~~~~~~ |
| 532 | |
| 533 | This hook is invoked by linkgit:git-receive-pack[1] when it reacts to |
| 534 | `git push` and updates reference(s) in its repository, and when |
| 535 | the push tries to update the branch that is currently checked out |
| 536 | and the `receive.denyCurrentBranch` configuration variable is set to |
| 537 | `updateInstead`. Such a push by default is refused if the working |
| 538 | tree and the index of the remote repository has any difference from |
| 539 | the currently checked out commit; when both the working tree and the |
| 540 | index match the current commit, they are updated to match the newly |
| 541 | pushed tip of the branch. This hook is to be used to override the |
| 542 | default behaviour. |
| 543 | |
| 544 | The hook receives the commit with which the tip of the current |
| 545 | branch is going to be updated. It can exit with a non-zero status |
| 546 | to refuse the push (when it does so, it must not modify the index or |
| 547 | the working tree). Or it can make any necessary changes to the |
| 548 | working tree and to the index to bring them to the desired state |
| 549 | when the tip of the current branch is updated to the new commit, and |
| 550 | exit with a zero status. |
| 551 | |
| 552 | For example, the hook can simply run `git read-tree -u -m HEAD "$1"` |
| 553 | in order to emulate `git fetch` that is run in the reverse direction |
| 554 | with `git push`, as the two-tree form of `git read-tree -u -m` is |
| 555 | essentially the same as `git switch` or `git checkout` |
| 556 | that switches branches while |
| 557 | keeping the local changes in the working tree that do not interfere |
| 558 | with the difference between the branches. |
| 559 | |
| 560 | |
| 561 | pre-auto-gc |
| 562 | ~~~~~~~~~~~ |
| 563 | |
| 564 | This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It |
| 565 | takes no parameter, and exiting with non-zero status from this script |
| 566 | causes the `git gc --auto` to abort. |
| 567 | |
| 568 | post-rewrite |
| 569 | ~~~~~~~~~~~~ |
| 570 | |
| 571 | This hook is invoked by commands that rewrite commits |
| 572 | (linkgit:git-commit[1] when called with `--amend` and |
| 573 | linkgit:git-rebase[1]; however, full-history (re)writing tools like |
| 574 | linkgit:git-fast-import[1] or |
| 575 | https://github.com/newren/git-filter-repo[git-filter-repo] typically |
| 576 | do not call it!). Its first argument denotes the command it was |
| 577 | invoked by: currently one of `amend` or `rebase`. Further |
| 578 | command-dependent arguments may be passed in the future. |
| 579 | |
| 580 | The hook receives a list of the rewritten commits on stdin, in the |
| 581 | format |
| 582 | |
| 583 | <old-object-name> SP <new-object-name> [ SP <extra-info> ] LF |
| 584 | |
| 585 | The 'extra-info' is again command-dependent. If it is empty, the |
| 586 | preceding SP is also omitted. Currently, no commands pass any |
| 587 | 'extra-info'. |
| 588 | |
| 589 | The hook always runs after the automatic note copying (see |
| 590 | "notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and |
| 591 | thus has access to these notes. |
| 592 | |
| 593 | The following command-specific comments apply: |
| 594 | |
| 595 | rebase:: |
| 596 | For the 'squash' and 'fixup' operation, all commits that were |
| 597 | squashed are listed as being rewritten to the squashed commit. |
| 598 | This means that there will be several lines sharing the same |
| 599 | 'new-object-name'. |
| 600 | + |
| 601 | The commits are guaranteed to be listed in the order that they were |
| 602 | processed by rebase. |
| 603 | |
| 604 | sendemail-validate |
| 605 | ~~~~~~~~~~~~~~~~~~ |
| 606 | |
| 607 | This hook is invoked by linkgit:git-send-email[1]. |
| 608 | |
| 609 | It takes these command line arguments. They are, |
| 610 | 1. the name of the file which holds the contents of the email to be sent. |
| 611 | 2. The name of the file which holds the SMTP headers of the email. |
| 612 | |
| 613 | The SMTP headers are passed in the exact same way as they are passed to the |
| 614 | user's Mail Transport Agent (MTA). In effect, the email given to the user's |
| 615 | MTA, is the contents of $2 followed by the contents of $1. |
| 616 | |
| 617 | An example of a few common headers is shown below. Take notice of the |
| 618 | capitalization and multi-line tab structure. |
| 619 | |
| 620 | From: Example <from@example.com> |
| 621 | To: to@example.com |
| 622 | Cc: cc@example.com, |
| 623 | A <author@example.com>, |
| 624 | One <one@example.com>, |
| 625 | two@example.com |
| 626 | Subject: PATCH-STRING |
| 627 | |
| 628 | Exiting with a non-zero status causes `git send-email` to abort |
| 629 | before sending any e-mails. |
| 630 | |
| 631 | The following environment variables are set when executing the hook. |
| 632 | |
| 633 | `GIT_SENDEMAIL_FILE_COUNTER`:: |
| 634 | A 1-based counter incremented by one for every file holding an e-mail |
| 635 | to be sent (excluding any FIFOs). This counter does not follow the |
| 636 | patch series counter scheme. It will always start at 1 and will end at |
| 637 | GIT_SENDEMAIL_FILE_TOTAL. |
| 638 | |
| 639 | `GIT_SENDEMAIL_FILE_TOTAL`:: |
| 640 | The total number of files that will be sent (excluding any FIFOs). This |
| 641 | counter does not follow the patch series counter scheme. It will always |
| 642 | be equal to the number of files being sent, whether there is a cover |
| 643 | letter or not. |
| 644 | |
| 645 | These variables may for instance be used to validate patch series. |
| 646 | |
| 647 | The sample `sendemail-validate` hook that comes with Git checks that all sent |
| 648 | patches (excluding the cover letter) can be applied on top of the upstream |
| 649 | repository default branch without conflicts. Some placeholders are left for |
| 650 | additional validation steps to be performed after all patches of a given series |
| 651 | have been applied. |
| 652 | |
| 653 | fsmonitor-watchman |
| 654 | ~~~~~~~~~~~~~~~~~~ |
| 655 | |
| 656 | This hook is invoked when the configuration option `core.fsmonitor` is |
| 657 | set to `.git/hooks/fsmonitor-watchman` or `.git/hooks/fsmonitor-watchmanv2` |
| 658 | depending on the version of the hook to use. |
| 659 | |
| 660 | Version 1 takes two arguments, a version (1) and the time in elapsed |
| 661 | nanoseconds since midnight, January 1, 1970. |
| 662 | |
| 663 | Version 2 takes two arguments, a version (2) and a token that is used |
| 664 | for identifying changes since the token. For watchman this would be |
| 665 | a clock id. This version must output to stdout the new token followed |
| 666 | by a NUL before the list of files. |
| 667 | |
| 668 | The hook should output to stdout the list of all files in the working |
| 669 | directory that may have changed since the requested time. The logic |
| 670 | should be inclusive so that it does not miss any potential changes. |
| 671 | The paths should be relative to the root of the working directory |
| 672 | and be separated by a single NUL. |
| 673 | |
| 674 | It is OK to include files which have not actually changed. All changes |
| 675 | including newly-created and deleted files should be included. When |
| 676 | files are renamed, both the old and the new name should be included. |
| 677 | |
| 678 | Git will limit what files it checks for changes as well as which |
| 679 | directories are checked for untracked files based on the path names |
| 680 | given. |
| 681 | |
| 682 | An optimized way to tell git "all files have changed" is to return |
| 683 | the filename `/`. |
| 684 | |
| 685 | The exit status determines whether git will use the data from the |
| 686 | hook to limit its search. On error, it will fall back to verifying |
| 687 | all files and folders. |
| 688 | |
| 689 | p4-changelist |
| 690 | ~~~~~~~~~~~~~ |
| 691 | |
| 692 | This hook is invoked by `git-p4 submit`. |
| 693 | |
| 694 | The `p4-changelist` hook is executed after the changelist |
| 695 | message has been edited by the user. It can be bypassed with the |
| 696 | `--no-verify` option. It takes a single parameter, the name |
| 697 | of the file that holds the proposed changelist text. Exiting |
| 698 | with a non-zero status causes the command to abort. |
| 699 | |
| 700 | The hook is allowed to edit the changelist file and can be used |
| 701 | to normalize the text into some project standard format. It can |
| 702 | also be used to refuse the Submit after inspect the message file. |
| 703 | |
| 704 | Run `git-p4 submit --help` for details. |
| 705 | |
| 706 | p4-prepare-changelist |
| 707 | ~~~~~~~~~~~~~~~~~~~~~ |
| 708 | |
| 709 | This hook is invoked by `git-p4 submit`. |
| 710 | |
| 711 | The `p4-prepare-changelist` hook is executed right after preparing |
| 712 | the default changelist message and before the editor is started. |
| 713 | It takes one parameter, the name of the file that contains the |
| 714 | changelist text. Exiting with a non-zero status from the script |
| 715 | will abort the process. |
| 716 | |
| 717 | The purpose of the hook is to edit the message file in place, |
| 718 | and it is not suppressed by the `--no-verify` option. This hook |
| 719 | is called even if `--prepare-p4-only` is set. |
| 720 | |
| 721 | Run `git-p4 submit --help` for details. |
| 722 | |
| 723 | p4-post-changelist |
| 724 | ~~~~~~~~~~~~~~~~~~ |
| 725 | |
| 726 | This hook is invoked by `git-p4 submit`. |
| 727 | |
| 728 | The `p4-post-changelist` hook is invoked after the submit has |
| 729 | successfully occurred in P4. It takes no parameters and is meant |
| 730 | primarily for notification and cannot affect the outcome of the |
| 731 | git p4 submit action. |
| 732 | |
| 733 | Run `git-p4 submit --help` for details. |
| 734 | |
| 735 | p4-pre-submit |
| 736 | ~~~~~~~~~~~~~ |
| 737 | |
| 738 | This hook is invoked by `git-p4 submit`. It takes no parameters and nothing |
| 739 | from standard input. Exiting with non-zero status from this script prevent |
| 740 | `git-p4 submit` from launching. It can be bypassed with the `--no-verify` |
| 741 | command line option. Run `git-p4 submit --help` for details. |
| 742 | |
| 743 | |
| 744 | |
| 745 | post-index-change |
| 746 | ~~~~~~~~~~~~~~~~~ |
| 747 | |
| 748 | This hook is invoked when the index is written in read-cache.c |
| 749 | do_write_locked_index. |
| 750 | |
| 751 | The first parameter passed to the hook is the indicator for the |
| 752 | working directory being updated. "1" meaning working directory |
| 753 | was updated or "0" when the working directory was not updated. |
| 754 | |
| 755 | The second parameter passed to the hook is the indicator for whether |
| 756 | or not the index was updated and the skip-worktree bit could have |
| 757 | changed. "1" meaning skip-worktree bits could have been updated |
| 758 | and "0" meaning they were not. |
| 759 | |
| 760 | Only one parameter should be set to "1" when the hook runs. The hook |
| 761 | running passing "1", "1" should not be possible. |
| 762 | |
| 763 | SEE ALSO |
| 764 | -------- |
| 765 | linkgit:git-hook[1] |
| 766 | |
| 767 | GIT |
| 768 | --- |
| 769 | Part of the linkgit:git[1] suite |