t9902: use a non-deprecated command for testing
[git/git.git] / 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/* (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 Hooks can get their arguments via the environment, command-line
31 arguments, and stdin. See the documentation for each hook below for
32 details.
33
34 `git init` may copy hooks to the new repository, depending on its
35 configuration. See the "TEMPLATE DIRECTORY" section in
36 linkgit:git-init[1] for details. When the rest of this document refers
37 to "default hooks" it's talking about the default template shipped
38 with Git.
39
40 The currently supported hooks are described below.
41
42 HOOKS
43 -----
44
45 applypatch-msg
46 ~~~~~~~~~~~~~~
47
48 This hook is invoked by linkgit:git-am[1]. It takes a single
49 parameter, the name of the file that holds the proposed commit
50 log message. Exiting with a non-zero status causes `git am` to abort
51 before applying the patch.
52
53 The hook is allowed to edit the message file in place, and can
54 be used to normalize the message into some project standard
55 format. It can also be used to refuse the commit after inspecting
56 the message file.
57
58 The default 'applypatch-msg' hook, when enabled, runs the
59 'commit-msg' hook, if the latter is enabled.
60
61 pre-applypatch
62 ~~~~~~~~~~~~~~
63
64 This hook is invoked by linkgit:git-am[1]. It takes no parameter, and is
65 invoked after the patch is applied, but before a commit is made.
66
67 If it exits with non-zero status, then the working tree will not be
68 committed after applying the patch.
69
70 It can be used to inspect the current working tree and refuse to
71 make a commit if it does not pass certain test.
72
73 The default 'pre-applypatch' hook, when enabled, runs the
74 'pre-commit' hook, if the latter is enabled.
75
76 post-applypatch
77 ~~~~~~~~~~~~~~~
78
79 This hook is invoked by linkgit:git-am[1]. It takes no parameter,
80 and is invoked after the patch is applied and a commit is made.
81
82 This hook is meant primarily for notification, and cannot affect
83 the outcome of `git am`.
84
85 pre-commit
86 ~~~~~~~~~~
87
88 This hook is invoked by linkgit:git-commit[1], and can be bypassed
89 with the `--no-verify` option. It takes no parameters, and is
90 invoked before obtaining the proposed commit log message and
91 making a commit. Exiting with a non-zero status from this script
92 causes the `git commit` command to abort before creating a commit.
93
94 The default 'pre-commit' hook, when enabled, catches introduction
95 of lines with trailing whitespaces and aborts the commit when
96 such a line is found.
97
98 All the `git commit` hooks are invoked with the environment
99 variable `GIT_EDITOR=:` if the command will not bring up an editor
100 to modify the commit message.
101
102 The default 'pre-commit' hook, when enabled--and with the
103 `hooks.allownonascii` config option unset or set to false--prevents
104 the use of non-ASCII filenames.
105
106 prepare-commit-msg
107 ~~~~~~~~~~~~~~~~~~
108
109 This hook is invoked by linkgit:git-commit[1] right after preparing the
110 default log message, and before the editor is started.
111
112 It takes one to three parameters. The first is the name of the file
113 that contains the commit log message. The second is the source of the commit
114 message, and can be: `message` (if a `-m` or `-F` option was
115 given); `template` (if a `-t` option was given or the
116 configuration option `commit.template` is set); `merge` (if the
117 commit is a merge or a `.git/MERGE_MSG` file exists); `squash`
118 (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by
119 a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given).
120
121 If the exit status is non-zero, `git commit` will abort.
122
123 The purpose of the hook is to edit the message file in place, and
124 it is not suppressed by the `--no-verify` option. A non-zero exit
125 means a failure of the hook and aborts the commit. It should not
126 be used as replacement for pre-commit hook.
127
128 The sample `prepare-commit-msg` hook that comes with Git removes the
129 help message found in the commented portion of the commit template.
130
131 commit-msg
132 ~~~~~~~~~~
133
134 This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and can be
135 bypassed with the `--no-verify` option. It takes a single parameter,
136 the name of the file that holds the proposed commit log message.
137 Exiting with a non-zero status causes the command to abort.
138
139 The hook is allowed to edit the message file in place, and can be used
140 to normalize the message into some project standard format. It
141 can also be used to refuse the commit after inspecting the message
142 file.
143
144 The default 'commit-msg' hook, when enabled, detects duplicate
145 "Signed-off-by" lines, and aborts the commit if one is found.
146
147 post-commit
148 ~~~~~~~~~~~
149
150 This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is
151 invoked after a commit is made.
152
153 This hook is meant primarily for notification, and cannot affect
154 the outcome of `git commit`.
155
156 pre-rebase
157 ~~~~~~~~~~
158
159 This hook is called by linkgit:git-rebase[1] and can be used to prevent a
160 branch from getting rebased. The hook may be called with one or
161 two parameters. The first parameter is the upstream from which
162 the series was forked. The second parameter is the branch being
163 rebased, and is not set when rebasing the current branch.
164
165 post-checkout
166 ~~~~~~~~~~~~~
167
168 This hook is invoked when a linkgit:git-checkout[1] or
169 linkgit:git-switch[1] is run after having updated the
170 worktree. The hook is given three parameters: the ref of the previous HEAD,
171 the ref of the new HEAD (which may or may not have changed), and a flag
172 indicating whether the checkout was a branch checkout (changing branches,
173 flag=1) or a file checkout (retrieving a file from the index, flag=0).
174 This hook cannot affect the outcome of `git switch` or `git checkout`.
175
176 It is also run after linkgit:git-clone[1], unless the `--no-checkout` (`-n`) option is
177 used. The first parameter given to the hook is the null-ref, the second the
178 ref of the new HEAD and the flag is always 1. Likewise for `git worktree add`
179 unless `--no-checkout` is used.
180
181 This hook can be used to perform repository validity checks, auto-display
182 differences from the previous HEAD if different, or set working dir metadata
183 properties.
184
185 post-merge
186 ~~~~~~~~~~
187
188 This hook is invoked by linkgit:git-merge[1], which happens when a `git pull`
189 is done on a local repository. The hook takes a single parameter, a status
190 flag specifying whether or not the merge being done was a squash merge.
191 This hook cannot affect the outcome of `git merge` and is not executed,
192 if the merge failed due to conflicts.
193
194 This hook can be used in conjunction with a corresponding pre-commit hook to
195 save and restore any form of metadata associated with the working tree
196 (e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl
197 for an example of how to do this.
198
199 pre-push
200 ~~~~~~~~
201
202 This hook is called by linkgit:git-push[1] and can be used to prevent
203 a push from taking place. The hook is called with two parameters
204 which provide the name and location of the destination remote, if a
205 named remote is not being used both values will be the same.
206
207 Information about what is to be pushed is provided on the hook's standard
208 input with lines of the form:
209
210 <local ref> SP <local sha1> SP <remote ref> SP <remote sha1> LF
211
212 For instance, if the command +git push origin master:foreign+ were run the
213 hook would receive a line like the following:
214
215 refs/heads/master 67890 refs/heads/foreign 12345
216
217 although the full, 40-character SHA-1s would be supplied. If the foreign ref
218 does not yet exist the `<remote SHA-1>` will be 40 `0`. If a ref is to be
219 deleted, the `<local ref>` will be supplied as `(delete)` and the `<local
220 SHA-1>` will be 40 `0`. If the local commit was specified by something other
221 than a name which could be expanded (such as `HEAD~`, or a SHA-1) it will be
222 supplied as it was originally given.
223
224 If this hook exits with a non-zero status, `git push` will abort without
225 pushing anything. Information about why the push is rejected may be sent
226 to the user by writing to standard error.
227
228 [[pre-receive]]
229 pre-receive
230 ~~~~~~~~~~~
231
232 This hook is invoked by linkgit:git-receive-pack[1] when it reacts to
233 `git push` and updates reference(s) in its repository.
234 Just before starting to update refs on the remote repository, the
235 pre-receive hook is invoked. Its exit status determines the success
236 or failure of the update.
237
238 This hook executes once for the receive operation. It takes no
239 arguments, but for each ref to be updated it receives on standard
240 input a line of the format:
241
242 <old-value> SP <new-value> SP <ref-name> LF
243
244 where `<old-value>` is the old object name stored in the ref,
245 `<new-value>` is the new object name to be stored in the ref and
246 `<ref-name>` is the full name of the ref.
247 When creating a new ref, `<old-value>` is 40 `0`.
248
249 If the hook exits with non-zero status, none of the refs will be
250 updated. If the hook exits with zero, updating of individual refs can
251 still be prevented by the <<update,'update'>> hook.
252
253 Both standard output and standard error output are forwarded to
254 `git send-pack` on the other end, so you can simply `echo` messages
255 for the user.
256
257 The number of push options given on the command line of
258 `git push --push-option=...` can be read from the environment
259 variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are
260 found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,...
261 If it is negotiated to not use the push options phase, the
262 environment variables will not be set. If the client selects
263 to use push options, but doesn't transmit any, the count variable
264 will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.
265
266 See the section on "Quarantine Environment" in
267 linkgit:git-receive-pack[1] for some caveats.
268
269 [[update]]
270 update
271 ~~~~~~
272
273 This hook is invoked by linkgit:git-receive-pack[1] when it reacts to
274 `git push` and updates reference(s) in its repository.
275 Just before updating the ref on the remote repository, the update hook
276 is invoked. Its exit status determines the success or failure of
277 the ref update.
278
279 The hook executes once for each ref to be updated, and takes
280 three parameters:
281
282 - the name of the ref being updated,
283 - the old object name stored in the ref,
284 - and the new object name to be stored in the ref.
285
286 A zero exit from the update hook allows the ref to be updated.
287 Exiting with a non-zero status prevents `git receive-pack`
288 from updating that ref.
289
290 This hook can be used to prevent 'forced' update on certain refs by
291 making sure that the object name is a commit object that is a
292 descendant of the commit object named by the old object name.
293 That is, to enforce a "fast-forward only" policy.
294
295 It could also be used to log the old..new status. However, it
296 does not know the entire set of branches, so it would end up
297 firing one e-mail per ref when used naively, though. The
298 <<post-receive,'post-receive'>> hook is more suited to that.
299
300 In an environment that restricts the users' access only to git
301 commands over the wire, this hook can be used to implement access
302 control without relying on filesystem ownership and group
303 membership. See linkgit:git-shell[1] for how you might use the login
304 shell to restrict the user's access to only git commands.
305
306 Both standard output and standard error output are forwarded to
307 `git send-pack` on the other end, so you can simply `echo` messages
308 for the user.
309
310 The default 'update' hook, when enabled--and with
311 `hooks.allowunannotated` config option unset or set to false--prevents
312 unannotated tags to be pushed.
313
314 [[post-receive]]
315 post-receive
316 ~~~~~~~~~~~~
317
318 This hook is invoked by linkgit:git-receive-pack[1] when it reacts to
319 `git push` and updates reference(s) in its repository.
320 It executes on the remote repository once after all the refs have
321 been updated.
322
323 This hook executes once for the receive operation. It takes no
324 arguments, but gets the same information as the
325 <<pre-receive,'pre-receive'>>
326 hook does on its standard input.
327
328 This hook does not affect the outcome of `git receive-pack`, as it
329 is called after the real work is done.
330
331 This supersedes the <<post-update,'post-update'>> hook in that it gets
332 both old and new values of all the refs in addition to their
333 names.
334
335 Both standard output and standard error output are forwarded to
336 `git send-pack` on the other end, so you can simply `echo` messages
337 for the user.
338
339 The default 'post-receive' hook is empty, but there is
340 a sample script `post-receive-email` provided in the `contrib/hooks`
341 directory in Git distribution, which implements sending commit
342 emails.
343
344 The number of push options given on the command line of
345 `git push --push-option=...` can be read from the environment
346 variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are
347 found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,...
348 If it is negotiated to not use the push options phase, the
349 environment variables will not be set. If the client selects
350 to use push options, but doesn't transmit any, the count variable
351 will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.
352
353 [[post-update]]
354 post-update
355 ~~~~~~~~~~~
356
357 This hook is invoked by linkgit:git-receive-pack[1] when it reacts to
358 `git push` and updates reference(s) in its repository.
359 It executes on the remote repository once after all the refs have
360 been updated.
361
362 It takes a variable number of parameters, each of which is the
363 name of ref that was actually updated.
364
365 This hook is meant primarily for notification, and cannot affect
366 the outcome of `git receive-pack`.
367
368 The 'post-update' hook can tell what are the heads that were pushed,
369 but it does not know what their original and updated values are,
370 so it is a poor place to do log old..new. The
371 <<post-receive,'post-receive'>> hook does get both original and
372 updated values of the refs. You might consider it instead if you need
373 them.
374
375 When enabled, the default 'post-update' hook runs
376 `git update-server-info` to keep the information used by dumb
377 transports (e.g., HTTP) up to date. If you are publishing
378 a Git repository that is accessible via HTTP, you should
379 probably enable this hook.
380
381 Both standard output and standard error output are forwarded to
382 `git send-pack` on the other end, so you can simply `echo` messages
383 for the user.
384
385 push-to-checkout
386 ~~~~~~~~~~~~~~~~
387
388 This hook is invoked by linkgit:git-receive-pack[1] when it reacts to
389 `git push` and updates reference(s) in its repository, and when
390 the push tries to update the branch that is currently checked out
391 and the `receive.denyCurrentBranch` configuration variable is set to
392 `updateInstead`. Such a push by default is refused if the working
393 tree and the index of the remote repository has any difference from
394 the currently checked out commit; when both the working tree and the
395 index match the current commit, they are updated to match the newly
396 pushed tip of the branch. This hook is to be used to override the
397 default behaviour.
398
399 The hook receives the commit with which the tip of the current
400 branch is going to be updated. It can exit with a non-zero status
401 to refuse the push (when it does so, it must not modify the index or
402 the working tree). Or it can make any necessary changes to the
403 working tree and to the index to bring them to the desired state
404 when the tip of the current branch is updated to the new commit, and
405 exit with a zero status.
406
407 For example, the hook can simply run `git read-tree -u -m HEAD "$1"`
408 in order to emulate `git fetch` that is run in the reverse direction
409 with `git push`, as the two-tree form of `git read-tree -u -m` is
410 essentially the same as `git switch` or `git checkout`
411 that switches branches while
412 keeping the local changes in the working tree that do not interfere
413 with the difference between the branches.
414
415
416 pre-auto-gc
417 ~~~~~~~~~~~
418
419 This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It
420 takes no parameter, and exiting with non-zero status from this script
421 causes the `git gc --auto` to abort.
422
423 post-rewrite
424 ~~~~~~~~~~~~
425
426 This hook is invoked by commands that rewrite commits
427 (linkgit:git-commit[1] when called with `--amend` and
428 linkgit:git-rebase[1]; however, full-history (re)writing tools like
429 linkgit:git-fast-import[1] or
430 https://github.com/newren/git-filter-repo[git-filter-repo] typically
431 do not call it!). Its first argument denotes the command it was
432 invoked by: currently one of `amend` or `rebase`. Further
433 command-dependent arguments may be passed in the future.
434
435 The hook receives a list of the rewritten commits on stdin, in the
436 format
437
438 <old-sha1> SP <new-sha1> [ SP <extra-info> ] LF
439
440 The 'extra-info' is again command-dependent. If it is empty, the
441 preceding SP is also omitted. Currently, no commands pass any
442 'extra-info'.
443
444 The hook always runs after the automatic note copying (see
445 "notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and
446 thus has access to these notes.
447
448 The following command-specific comments apply:
449
450 rebase::
451 For the 'squash' and 'fixup' operation, all commits that were
452 squashed are listed as being rewritten to the squashed commit.
453 This means that there will be several lines sharing the same
454 'new-sha1'.
455 +
456 The commits are guaranteed to be listed in the order that they were
457 processed by rebase.
458
459 sendemail-validate
460 ~~~~~~~~~~~~~~~~~~
461
462 This hook is invoked by linkgit:git-send-email[1]. It takes a single parameter,
463 the name of the file that holds the e-mail to be sent. Exiting with a
464 non-zero status causes `git send-email` to abort before sending any
465 e-mails.
466
467 fsmonitor-watchman
468 ~~~~~~~~~~~~~~~~~~
469
470 This hook is invoked when the configuration option `core.fsmonitor` is
471 set to `.git/hooks/fsmonitor-watchman`. It takes two arguments, a version
472 (currently 1) and the time in elapsed nanoseconds since midnight,
473 January 1, 1970.
474
475 The hook should output to stdout the list of all files in the working
476 directory that may have changed since the requested time. The logic
477 should be inclusive so that it does not miss any potential changes.
478 The paths should be relative to the root of the working directory
479 and be separated by a single NUL.
480
481 It is OK to include files which have not actually changed. All changes
482 including newly-created and deleted files should be included. When
483 files are renamed, both the old and the new name should be included.
484
485 Git will limit what files it checks for changes as well as which
486 directories are checked for untracked files based on the path names
487 given.
488
489 An optimized way to tell git "all files have changed" is to return
490 the filename `/`.
491
492 The exit status determines whether git will use the data from the
493 hook to limit its search. On error, it will fall back to verifying
494 all files and folders.
495
496 p4-pre-submit
497 ~~~~~~~~~~~~~
498
499 This hook is invoked by `git-p4 submit`. It takes no parameters and nothing
500 from standard input. Exiting with non-zero status from this script prevent
501 `git-p4 submit` from launching. Run `git-p4 submit --help` for details.
502
503 post-index-change
504 ~~~~~~~~~~~~~~~~~
505
506 This hook is invoked when the index is written in read-cache.c
507 do_write_locked_index.
508
509 The first parameter passed to the hook is the indicator for the
510 working directory being updated. "1" meaning working directory
511 was updated or "0" when the working directory was not updated.
512
513 The second parameter passed to the hook is the indicator for whether
514 or not the index was updated and the skip-worktree bit could have
515 changed. "1" meaning skip-worktree bits could have been updated
516 and "0" meaning they were not.
517
518 Only one parameter should be set to "1" when the hook runs. The hook
519 running passing "1", "1" should not be possible.
520
521 GIT
522 ---
523 Part of the linkgit:git[1] suite