githooks.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.2.5" />
   7 <style type="text/css">
   8 /* Debug borders */
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29 }
  30
  31 strong {
  32   font-weight: bold;
  33 }
  34
  35 tt {
  36   color: navy;
  37 }
  38
  39 h1, h2, h3, h4, h5, h6 {
  40   color: #527bbd;
  41   font-family: sans-serif;
  42   margin-top: 1.2em;
  43   margin-bottom: 0.5em;
  44   line-height: 1.3;
  45 }
  46
  47 h1, h2, h3 {
  48   border-bottom: 2px solid silver;
  49 }
  50 h2 {
  51   padding-top: 0.5em;
  52 }
  53 h3 {
  54   float: left;
  55 }
  56 h3 + * {
  57   clear: left;
  58 }
  59
  60 div.sectionbody {
  61   font-family: serif;
  62   margin-left: 0;
  63 }
  64
  65 hr {
  66   border: 1px solid silver;
  67 }
  68
  69 p {
  70   margin-top: 0.5em;
  71   margin-bottom: 0.5em;
  72 }
  73
  74 pre {
  75   padding: 0;
  76   margin: 0;
  77 }
  78
  79 span#author {
  80   color: #527bbd;
  81   font-family: sans-serif;
  82   font-weight: bold;
  83   font-size: 1.1em;
  84 }
  85 span#email {
  86 }
  87 span#revision {
  88   font-family: sans-serif;
  89 }
  90
  91 div#footer {
  92   font-family: sans-serif;
  93   font-size: small;
  94   border-top: 2px solid silver;
  95   padding-top: 0.5em;
  96   margin-top: 4.0em;
  97 }
  98 div#footer-text {
  99   float: left;
 100   padding-bottom: 0.5em;
 101 }
 102 div#footer-badges {
 103   float: right;
 104   padding-bottom: 0.5em;
 105 }
 106
 107 div#preamble,
 108 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 109 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 110 div.admonitionblock {
 111   margin-right: 10%;
 112   margin-top: 1.5em;
 113   margin-bottom: 1.5em;
 114 }
 115 div.admonitionblock {
 116   margin-top: 2.5em;
 117   margin-bottom: 2.5em;
 118 }
 119
 120 div.content { /* Block element content. */
 121   padding: 0;
 122 }
 123
 124 /* Block element titles. */
 125 div.title, caption.title {
 126   font-family: sans-serif;
 127   font-weight: bold;
 128   text-align: left;
 129   margin-top: 1.0em;
 130   margin-bottom: 0.5em;
 131 }
 132 div.title + * {
 133   margin-top: 0;
 134 }
 135
 136 td div.title:first-child {
 137   margin-top: 0.0em;
 138 }
 139 div.content div.title:first-child {
 140   margin-top: 0.0em;
 141 }
 142 div.content + div.title {
 143   margin-top: 0.0em;
 144 }
 145
 146 div.sidebarblock > div.content {
 147   background: #ffffee;
 148   border: 1px solid silver;
 149   padding: 0.5em;
 150 }
 151
 152 div.listingblock {
 153   margin-right: 0%;
 154 }
 155 div.listingblock > div.content {
 156   border: 1px solid silver;
 157   background: #f4f4f4;
 158   padding: 0.5em;
 159 }
 160
 161 div.quoteblock > div.content {
 162   padding-left: 2.0em;
 163 }
 164
 165 div.attribution {
 166   text-align: right;
 167 }
 168 div.verseblock + div.attribution {
 169   text-align: left;
 170 }
 171
 172 div.admonitionblock .icon {
 173   vertical-align: top;
 174   font-size: 1.1em;
 175   font-weight: bold;
 176   text-decoration: underline;
 177   color: #527bbd;
 178   padding-right: 0.5em;
 179 }
 180 div.admonitionblock td.content {
 181   padding-left: 0.5em;
 182   border-left: 2px solid silver;
 183 }
 184
 185 div.exampleblock > div.content {
 186   border-left: 2px solid silver;
 187   padding: 0.5em;
 188 }
 189
 190 div.verseblock div.content {
 191   white-space: pre;
 192 }
 193
 194 div.imageblock div.content { padding-left: 0; }
 195 div.imageblock img { border: 1px solid silver; }
 196 span.image img { border-style: none; }
 197
 198 dl {
 199   margin-top: 0.8em;
 200   margin-bottom: 0.8em;
 201 }
 202 dt {
 203   margin-top: 0.5em;
 204   margin-bottom: 0;
 205   font-style: italic;
 206 }
 207 dd > *:first-child {
 208   margin-top: 0;
 209 }
 210
 211 ul, ol {
 212     list-style-position: outside;
 213 }
 214 div.olist2 ol {
 215   list-style-type: lower-alpha;
 216 }
 217
 218 div.tableblock > table {
 219   border: 3px solid #527bbd;
 220 }
 221 thead {
 222   font-family: sans-serif;
 223   font-weight: bold;
 224 }
 225 tfoot {
 226   font-weight: bold;
 227 }
 228
 229 div.hlist {
 230   margin-top: 0.8em;
 231   margin-bottom: 0.8em;
 232 }
 233 div.hlist td {
 234   padding-bottom: 5px;
 235 }
 236 td.hlist1 {
 237   vertical-align: top;
 238   font-style: italic;
 239   padding-right: 0.8em;
 240 }
 241 td.hlist2 {
 242   vertical-align: top;
 243 }
 244
 245 @media print {
 246   div#footer-badges { display: none; }
 247 }
 248
 249 div#toctitle {
 250   color: #527bbd;
 251   font-family: sans-serif;
 252   font-size: 1.1em;
 253   font-weight: bold;
 254   margin-top: 1.0em;
 255   margin-bottom: 0.1em;
 256 }
 257
 258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 259   margin-top: 0;
 260   margin-bottom: 0;
 261 }
 262 div.toclevel2 {
 263   margin-left: 2em;
 264   font-size: 0.9em;
 265 }
 266 div.toclevel3 {
 267   margin-left: 4em;
 268   font-size: 0.9em;
 269 }
 270 div.toclevel4 {
 271   margin-left: 6em;
 272   font-size: 0.9em;
 273 }
 274 include1::./stylesheets/xhtml11-manpage.css[]
 275 /* Workarounds for IE6's broken and incomplete CSS2. */
 276
 277 div.sidebar-content {
 278   background: #ffffee;
 279   border: 1px solid silver;
 280   padding: 0.5em;
 281 }
 282 div.sidebar-title, div.image-title {
 283   font-family: sans-serif;
 284   font-weight: bold;
 285   margin-top: 0.0em;
 286   margin-bottom: 0.5em;
 287 }
 288
 289 div.listingblock div.content {
 290   border: 1px solid silver;
 291   background: #f4f4f4;
 292   padding: 0.5em;
 293 }
 294
 295 div.quoteblock-content {
 296   padding-left: 2.0em;
 297 }
 298
 299 div.exampleblock-content {
 300   border-left: 2px solid silver;
 301   padding-left: 0.5em;
 302 }
 303
 304 /* IE6 sets dynamically generated links as visited. */
 305 div#toc a:visited { color: blue; }
 306 </style>
 307 <title>githooks(5)</title>
 308 </head>
 309 <body>
 310 <div id="header">
 311 <h1>
 312 githooks(5) Manual Page
 313 </h1>
 314 <h2>NAME</h2>
 315 <div class="sectionbody">
 316 <p>githooks -
 317    Hooks used by git
 318 </p>
 319 </div>
 320 </div>
 321 <h2>SYNOPSIS</h2>
 322 <div class="sectionbody">
 323 <div class="para"><p>$GIT_DIR/hooks/*</p></div>
 324 </div>
 325 <h2 id="_description">DESCRIPTION</h2>
 326 <div class="sectionbody">
 327 <div class="para"><p>Hooks are little scripts you can place in <tt>$GIT_DIR/hooks</tt>
 328 directory to trigger action at certain points.  When
 329 <em>git-init</em> is run, a handful of example hooks are copied into the
 330 <tt>hooks</tt> directory of the new repository, but by default they are
 331 all disabled.  To enable a hook, rename it by removing its <tt>.sample</tt>
 332 suffix.</p></div>
 333 <div class="admonitionblock">
 334 <table><tr>
 335 <td class="icon">
 336 <div class="title">Note</div>
 337 </td>
 338 <td class="content">It is also a requirement for a given hook to be executable.
 339 However - in a freshly initialized repository - the <tt>.sample</tt> files are
 340 executable by default.</td>
 341 </tr></table>
 342 </div>
 343 <div class="para"><p>This document describes the currently defined hooks.</p></div>
 344 </div>
 345 <h2 id="_applypatch_msg">applypatch-msg</h2>
 346 <div class="sectionbody">
 347 <div class="para"><p>This hook is invoked by <em>git-am</em> script.  It takes a single
 348 parameter, the name of the file that holds the proposed commit
 349 log message.  Exiting with non-zero status causes
 350 <em>git-am</em> to abort before applying the patch.</p></div>
 351 <div class="para"><p>The hook is allowed to edit the message file in place, and can
 352 be used to normalize the message into some project standard
 353 format (if the project has one). It can also be used to refuse
 354 the commit after inspecting the message file.</p></div>
 355 <div class="para"><p>The default <em>applypatch-msg</em> hook, when enabled, runs the
 356 <em>commit-msg</em> hook, if the latter is enabled.</p></div>
 357 </div>
 358 <h2 id="_pre_applypatch">pre-applypatch</h2>
 359 <div class="sectionbody">
 360 <div class="para"><p>This hook is invoked by <em>git-am</em>.  It takes no parameter, and is
 361 invoked after the patch is applied, but before a commit is made.</p></div>
 362 <div class="para"><p>If it exits with non-zero status, then the working tree will not be
 363 committed after applying the patch.</p></div>
 364 <div class="para"><p>It can be used to inspect the current working tree and refuse to
 365 make a commit if it does not pass certain test.</p></div>
 366 <div class="para"><p>The default <em>pre-applypatch</em> hook, when enabled, runs the
 367 <em>pre-commit</em> hook, if the latter is enabled.</p></div>
 368 </div>
 369 <h2 id="_post_applypatch">post-applypatch</h2>
 370 <div class="sectionbody">
 371 <div class="para"><p>This hook is invoked by <em>git-am</em>.  It takes no parameter,
 372 and is invoked after the patch is applied and a commit is made.</p></div>
 373 <div class="para"><p>This hook is meant primarily for notification, and cannot affect
 374 the outcome of <em>git-am</em>.</p></div>
 375 </div>
 376 <h2 id="_pre_commit">pre-commit</h2>
 377 <div class="sectionbody">
 378 <div class="para"><p>This hook is invoked by <em>git-commit</em>, and can be bypassed
 379 with <tt>--no-verify</tt> option.  It takes no parameter, and is
 380 invoked before obtaining the proposed commit log message and
 381 making a commit.  Exiting with non-zero status from this script
 382 causes the <em>git-commit</em> to abort.</p></div>
 383 <div class="para"><p>The default <em>pre-commit</em> hook, when enabled, catches introduction
 384 of lines with trailing whitespaces and aborts the commit when
 385 such a line is found.</p></div>
 386 <div class="para"><p>All the <em>git-commit</em> hooks are invoked with the environment
 387 variable <tt>GIT_EDITOR=:</tt> if the command will not bring up an editor
 388 to modify the commit message.</p></div>
 389 </div>
 390 <h2 id="_prepare_commit_msg">prepare-commit-msg</h2>
 391 <div class="sectionbody">
 392 <div class="para"><p>This hook is invoked by <em>git-commit</em> right after preparing the
 393 default log message, and before the editor is started.</p></div>
 394 <div class="para"><p>It takes one to three parameters.  The first is the name of the file
 395 that contains the commit log message.  The second is the source of the commit
 396 message, and can be: <tt>message</tt> (if a <tt>-m</tt> or <tt>-F</tt> option was
 397 given); <tt>template</tt> (if a <tt>-t</tt> option was given or the
 398 configuration option <tt>commit.template</tt> is set); <tt>merge</tt> (if the
 399 commit is a merge or a <tt>.git/MERGE_MSG</tt> file exists); <tt>squash</tt>
 400 (if a <tt>.git/SQUASH_MSG</tt> file exists); or <tt>commit</tt>, followed by
 401 a commit SHA1 (if a <tt>-c</tt>, <tt>-C</tt> or <tt>--amend</tt> option was given).</p></div>
 402 <div class="para"><p>If the exit status is non-zero, <em>git-commit</em> will abort.</p></div>
 403 <div class="para"><p>The purpose of the hook is to edit the message file in place, and
 404 it is not suppressed by the <tt>--no-verify</tt> option.  A non-zero exit
 405 means a failure of the hook and aborts the commit.  It should not
 406 be used as replacement for pre-commit hook.</p></div>
 407 <div class="para"><p>The sample <tt>prepare-commit-msg</tt> hook that comes with git comments
 408 out the <tt>Conflicts:</tt> part of a merge's commit message.</p></div>
 409 </div>
 410 <h2 id="_commit_msg">commit-msg</h2>
 411 <div class="sectionbody">
 412 <div class="para"><p>This hook is invoked by <em>git-commit</em>, and can be bypassed
 413 with <tt>--no-verify</tt> option.  It takes a single parameter, the
 414 name of the file that holds the proposed commit log message.
 415 Exiting with non-zero status causes the <em>git-commit</em> to
 416 abort.</p></div>
 417 <div class="para"><p>The hook is allowed to edit the message file in place, and can
 418 be used to normalize the message into some project standard
 419 format (if the project has one). It can also be used to refuse
 420 the commit after inspecting the message file.</p></div>
 421 <div class="para"><p>The default <em>commit-msg</em> hook, when enabled, detects duplicate
 422 "Signed-off-by" lines, and aborts the commit if one is found.</p></div>
 423 </div>
 424 <h2 id="_post_commit">post-commit</h2>
 425 <div class="sectionbody">
 426 <div class="para"><p>This hook is invoked by <em>git-commit</em>.  It takes no
 427 parameter, and is invoked after a commit is made.</p></div>
 428 <div class="para"><p>This hook is meant primarily for notification, and cannot affect
 429 the outcome of <em>git-commit</em>.</p></div>
 430 </div>
 431 <h2 id="_pre_rebase">pre-rebase</h2>
 432 <div class="sectionbody">
 433 <div class="para"><p>This hook is called by <em>git-rebase</em> and can be used to prevent a branch
 434 from getting rebased.</p></div>
 435 </div>
 436 <h2 id="_post_checkout">post-checkout</h2>
 437 <div class="sectionbody">
 438 <div class="para"><p>This hook is invoked when a <em>git-checkout</em> is run after having updated the
 439 worktree.  The hook is given three parameters: the ref of the previous HEAD,
 440 the ref of the new HEAD (which may or may not have changed), and a flag
 441 indicating whether the checkout was a branch checkout (changing branches,
 442 flag=1) or a file checkout (retrieving a file from the index, flag=0).
 443 This hook cannot affect the outcome of <em>git-checkout</em>.</p></div>
 444 <div class="para"><p>It is also run after <em>git-clone</em>, unless the --no-checkout (-n) option is
 445 used. The first parameter given to the hook is the null-ref, the second the
 446 ref of the new HEAD and the flag is always 1.</p></div>
 447 <div class="para"><p>This hook can be used to perform repository validity checks, auto-display
 448 differences from the previous HEAD if different, or set working dir metadata
 449 properties.</p></div>
 450 </div>
 451 <h2 id="_post_merge">post-merge</h2>
 452 <div class="sectionbody">
 453 <div class="para"><p>This hook is invoked by <em>git-merge</em>, which happens when a <em>git-pull</em>
 454 is done on a local repository.  The hook takes a single parameter, a status
 455 flag specifying whether or not the merge being done was a squash merge.
 456 This hook cannot affect the outcome of <em>git-merge</em> and is not executed,
 457 if the merge failed due to conflicts.</p></div>
 458 <div class="para"><p>This hook can be used in conjunction with a corresponding pre-commit hook to
 459 save and restore any form of metadata associated with the working tree
 460 (eg: permissions/ownership, ACLS, etc).  See contrib/hooks/setgitperms.perl
 461 for an example of how to do this.</p></div>
 462 </div>
 463 <h2 id="pre-receive">pre-receive</h2>
 464 <div class="sectionbody">
 465 <div class="para"><p>This hook is invoked by <em>git-receive-pack</em> on the remote repository,
 466 which happens when a <em>git-push</em> is done on a local repository.
 467 Just before starting to update refs on the remote repository, the
 468 pre-receive hook is invoked.  Its exit status determines the success
 469 or failure of the update.</p></div>
 470 <div class="para"><p>This hook executes once for the receive operation. It takes no
 471 arguments, but for each ref to be updated it receives on standard
 472 input a line of the format:</p></div>
 473 <div class="literalblock">
 474 <div class="content">
 475 <pre><tt>&lt;old-value&gt; SP &lt;new-value&gt; SP &lt;ref-name&gt; LF</tt></pre>
 476 </div></div>
 477 <div class="para"><p>where <tt>&lt;old-value&gt;</tt> is the old object name stored in the ref,
 478 <tt>&lt;new-value&gt;</tt> is the new object name to be stored in the ref and
 479 <tt>&lt;ref-name&gt;</tt> is the full name of the ref.
 480 When creating a new ref, <tt>&lt;old-value&gt;</tt> is 40 <tt>0</tt>.</p></div>
 481 <div class="para"><p>If the hook exits with non-zero status, none of the refs will be
 482 updated. If the hook exits with zero, updating of individual refs can
 483 still be prevented by the <a href="#update"><em>update</em></a> hook.</p></div>
 484 <div class="para"><p>Both standard output and standard error output are forwarded to
 485 <em>git-send-pack</em> on the other end, so you can simply <tt>echo</tt> messages
 486 for the user.</p></div>
 487 </div>
 488 <h2 id="update">update</h2>
 489 <div class="sectionbody">
 490 <div class="para"><p>This hook is invoked by <em>git-receive-pack</em> on the remote repository,
 491 which happens when a <em>git-push</em> is done on a local repository.
 492 Just before updating the ref on the remote repository, the update hook
 493 is invoked.  Its exit status determines the success or failure of
 494 the ref update.</p></div>
 495 <div class="para"><p>The hook executes once for each ref to be updated, and takes
 496 three parameters:</p></div>
 497 <div class="ilist"><ul>
 498 <li>
 499 <p>
 500 the name of the ref being updated,
 501 </p>
 502 </li>
 503 <li>
 504 <p>
 505 the old object name stored in the ref,
 506 </p>
 507 </li>
 508 <li>
 509 <p>
 510 and the new objectname to be stored in the ref.
 511 </p>
 512 </li>
 513 </ul></div>
 514 <div class="para"><p>A zero exit from the update hook allows the ref to be updated.
 515 Exiting with a non-zero status prevents <em>git-receive-pack</em>
 516 from updating that ref.</p></div>
 517 <div class="para"><p>This hook can be used to prevent <em>forced</em> update on certain refs by
 518 making sure that the object name is a commit object that is a
 519 descendant of the commit object named by the old object name.
 520 That is, to enforce a "fast forward only" policy.</p></div>
 521 <div class="para"><p>It could also be used to log the old..new status.  However, it
 522 does not know the entire set of branches, so it would end up
 523 firing one e-mail per ref when used naively, though.  The
 524 <a href="#post-receive"><em>post-receive</em></a> hook is more suited to that.</p></div>
 525 <div class="para"><p>Another use suggested on the mailing list is to use this hook to
 526 implement access control which is finer grained than the one
 527 based on filesystem group.</p></div>
 528 <div class="para"><p>Both standard output and standard error output are forwarded to
 529 <em>git-send-pack</em> on the other end, so you can simply <tt>echo</tt> messages
 530 for the user.</p></div>
 531 <div class="para"><p>The default <em>update</em> hook, when enabled--and with
 532 <tt>hooks.allowunannotated</tt> config option turned on--prevents
 533 unannotated tags to be pushed.</p></div>
 534 </div>
 535 <h2 id="post-receive">post-receive</h2>
 536 <div class="sectionbody">
 537 <div class="para"><p>This hook is invoked by <em>git-receive-pack</em> on the remote repository,
 538 which happens when a <em>git-push</em> is done on a local repository.
 539 It executes on the remote repository once after all the refs have
 540 been updated.</p></div>
 541 <div class="para"><p>This hook executes once for the receive operation.  It takes no
 542 arguments, but gets the same information as the
 543 <a href="#pre-receive"><em>pre-receive</em></a>
 544 hook does on its standard input.</p></div>
 545 <div class="para"><p>This hook does not affect the outcome of <em>git-receive-pack</em>, as it
 546 is called after the real work is done.</p></div>
 547 <div class="para"><p>This supersedes the <a href="#post-update"><em>post-update</em></a> hook in that it gets
 548 both old and new values of all the refs in addition to their
 549 names.</p></div>
 550 <div class="para"><p>Both standard output and standard error output are forwarded to
 551 <em>git-send-pack</em> on the other end, so you can simply <tt>echo</tt> messages
 552 for the user.</p></div>
 553 <div class="para"><p>The default <em>post-receive</em> hook is empty, but there is
 554 a sample script <tt>post-receive-email</tt> provided in the <tt>contrib/hooks</tt>
 555 directory in git distribution, which implements sending commit
 556 emails.</p></div>
 557 </div>
 558 <h2 id="post-update">post-update</h2>
 559 <div class="sectionbody">
 560 <div class="para"><p>This hook is invoked by <em>git-receive-pack</em> on the remote repository,
 561 which happens when a <em>git-push</em> is done on a local repository.
 562 It executes on the remote repository once after all the refs have
 563 been updated.</p></div>
 564 <div class="para"><p>It takes a variable number of parameters, each of which is the
 565 name of ref that was actually updated.</p></div>
 566 <div class="para"><p>This hook is meant primarily for notification, and cannot affect
 567 the outcome of <em>git-receive-pack</em>.</p></div>
 568 <div class="para"><p>The <em>post-update</em> hook can tell what are the heads that were pushed,
 569 but it does not know what their original and updated values are,
 570 so it is a poor place to do log old..new. The
 571 <a href="#post-receive"><em>post-receive</em></a> hook does get both original and
 572 updated values of the refs. You might consider it instead if you need
 573 them.</p></div>
 574 <div class="para"><p>When enabled, the default <em>post-update</em> hook runs
 575 <em>git-update-server-info</em> to keep the information used by dumb
 576 transports (e.g., HTTP) up-to-date.  If you are publishing
 577 a git repository that is accessible via HTTP, you should
 578 probably enable this hook.</p></div>
 579 <div class="para"><p>Both standard output and standard error output are forwarded to
 580 <em>git-send-pack</em> on the other end, so you can simply <tt>echo</tt> messages
 581 for the user.</p></div>
 582 </div>
 583 <h2 id="_pre_auto_gc">pre-auto-gc</h2>
 584 <div class="sectionbody">
 585 <div class="para"><p>This hook is invoked by <em>git-gc --auto</em>. It takes no parameter, and
 586 exiting with non-zero status from this script causes the <em>git-gc --auto</em>
 587 to abort.</p></div>
 588 </div>
 589 <h2 id="_git">GIT</h2>
 590 <div class="sectionbody">
 591 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
 592 </div>
 593 <div id="footer">
 594 <div id="footer-text">
 595 Last updated 2009-04-02 06:50:09 UTC
 596 </div>
 597 </div>
 598 </body>
 599 </html>