Documentation/githooks.txt

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