1GITHOOKS(5) Git Manual GITHOOKS(5)
2
6 githooks - Hooks used by Git
7
9 $GIT_DIR/hooks/* (or `git config core.hooksPath`/*)
10
12 Hooks are programs you can place in a hooks directory to trigger
13 actions at certain points in git’s execution. Hooks that don’t have the
14 executable bit set are ignored.
15 By default the hooks directory is $GIT_DIR/hooks, but that can be
17 changed via the core.hooksPath configuration variable (see git-
18 config(1)).
19 Before Git invokes a hook, it changes its working directory to either
21 $GIT_DIR in a bare repository or the root of the working tree in a
22 non-bare repository. An exception are hooks triggered during a push
23 (pre-receive, update, post-receive, post-update, push-to-checkout)
24 which are always executed in $GIT_DIR.
25 Hooks can get their arguments via the environment, command-line
27 arguments, and stdin. See the documentation for each hook below for
28 details.
29 git init may copy hooks to the new repository, depending on its
31 configuration. See the "TEMPLATE DIRECTORY" section in git-init(1) for
32 details. When the rest of this document refers to "default hooks" it’s
33 talking about the default template shipped with Git.
34 The currently supported hooks are described below.
36
38 applypatch-msg
39 This hook is invoked by git-am(1). It takes a single parameter, the
40 name of the file that holds the proposed commit log message. Exiting
41 with a non-zero status causes git am to abort before applying the
42 patch.
43 The hook is allowed to edit the message file in place, and can be used
45 to normalize the message into some project standard format. It can also
46 be used to refuse the commit after inspecting the message file.
47 The default applypatch-msg hook, when enabled, runs the commit-msg
49 hook, if the latter is enabled.
50 pre-applypatch
52 This hook is invoked by git-am(1). It takes no parameter, and is
53 invoked after the patch is applied, but before a commit is made.
54 If it exits with non-zero status, then the working tree will not be
56 committed after applying the patch.
57 It can be used to inspect the current working tree and refuse to make a
59 commit if it does not pass certain test.
60 The default pre-applypatch hook, when enabled, runs the pre-commit
62 hook, if the latter is enabled.
63 post-applypatch
65 This hook is invoked by git-am(1). It takes no parameter, and is
66 invoked after the patch is applied and a commit is made.
67 This hook is meant primarily for notification, and cannot affect the
69 outcome of git am.
70 pre-commit
72 This hook is invoked by git-commit(1), and can be bypassed with the
73 --no-verify option. It takes no parameters, and is invoked before
74 obtaining the proposed commit log message and making a commit. Exiting
75 with a non-zero status from this script causes the git commit command
76 to abort before creating a commit.
77 The default pre-commit hook, when enabled, catches introduction of
79 lines with trailing whitespaces and aborts the commit when such a line
80 is found.
81 All the git commit hooks are invoked with the environment variable
83 GIT_EDITOR=: if the command will not bring up an editor to modify the
84 commit message.
85 The default pre-commit hook, when enabled—and with the
87 hooks.allownonascii config option unset or set to false—prevents the
88 use of non-ASCII filenames.
89 pre-merge-commit
91 This hook is invoked by git-merge(1), and can be bypassed with the
92 --no-verify option. It takes no parameters, and is invoked after the
93 merge has been carried out successfully and before obtaining the
94 proposed commit log message to make a commit. Exiting with a non-zero
95 status from this script causes the git merge command to abort before
96 creating a commit.
97 The default pre-merge-commit hook, when enabled, runs the pre-commit
99 hook, if the latter is enabled.
100 This hook is invoked with the environment variable GIT_EDITOR=: if the
102 command will not bring up an editor to modify the commit message.
103 If the merge cannot be carried out automatically, the conflicts need to
105 be resolved and the result committed separately (see git-merge(1)). At
106 that point, this hook will not be executed, but the pre-commit hook
107 will, if it is enabled.
108 prepare-commit-msg
110 This hook is invoked by git-commit(1) right after preparing the default
111 log message, and before the editor is started.
112 It takes one to three parameters. The first is the name of the file
114 that contains the commit log message. The second is the source of the
115 commit message, and can be: message (if a -m or -F option was given);
116 template (if a -t option was given or the configuration option
117 commit.template is set); merge (if the commit is a merge or a
118 .git/MERGE_MSG file exists); squash (if a .git/SQUASH_MSG file exists);
119 or commit, followed by a commit object name (if a -c, -C or --amend
120 option was given).
121 If the exit status is non-zero, git commit will abort.
123 The purpose of the hook is to edit the message file in place, and it is
125 not suppressed by the --no-verify option. A non-zero exit means a
126 failure of the hook and aborts the commit. It should not be used as
127 replacement for pre-commit hook.
128 The sample prepare-commit-msg hook that comes with Git removes the help
130 message found in the commented portion of the commit template.
131 commit-msg
133 This hook is invoked by git-commit(1) and git-merge(1), and can be
134 bypassed with the --no-verify option. It takes a single parameter, the
135 name of the file that holds the proposed commit log message. Exiting
136 with a non-zero status causes the command to abort.
137 The hook is allowed to edit the message file in place, and can be used
139 to normalize the message into some project standard format. It can also
140 be used to refuse the commit after inspecting the message file.
141 The default commit-msg hook, when enabled, detects duplicate
143 Signed-off-by trailers, and aborts the commit if one is found.
144 post-commit
146 This hook is invoked by git-commit(1). It takes no parameters, and is
147 invoked after a commit is made.
148 This hook is meant primarily for notification, and cannot affect the
150 outcome of git commit.
151 pre-rebase
153 This hook is called by git-rebase(1) and can be used to prevent a
154 branch from getting rebased. The hook may be called with one or two
155 parameters. The first parameter is the upstream from which the series
156 was forked. The second parameter is the branch being rebased, and is
157 not set when rebasing the current branch.
158 post-checkout
160 This hook is invoked when a git-checkout(1) or git-switch(1) is run
161 after having updated the worktree. The hook is given three parameters:
162 the ref of the previous HEAD, the ref of the new HEAD (which may or may
163 not have changed), and a flag indicating whether the checkout was a
164 branch checkout (changing branches, flag=1) or a file checkout
165 (retrieving a file from the index, flag=0). This hook cannot affect the
166 outcome of git switch or git checkout, other than that the hook’s exit
167 status becomes the exit status of these two commands.
168 It is also run after git-clone(1), unless the --no-checkout (-n) option
170 is used. The first parameter given to the hook is the null-ref, the
171 second the ref of the new HEAD and the flag is always 1. Likewise for
172 git worktree add unless --no-checkout is used.
173 This hook can be used to perform repository validity checks,
175 auto-display differences from the previous HEAD if different, or set
176 working dir metadata properties.
177 post-merge
179 This hook is invoked by git-merge(1), which happens when a git pull is
180 done on a local repository. The hook takes a single parameter, a status
181 flag specifying whether or not the merge being done was a squash merge.
182 This hook cannot affect the outcome of git merge and is not executed,
183 if the merge failed due to conflicts.
184 This hook can be used in conjunction with a corresponding pre-commit
186 hook to save and restore any form of metadata associated with the
187 working tree (e.g.: permissions/ownership, ACLS, etc). See
188 contrib/hooks/setgitperms.perl for an example of how to do this.
189 pre-push
191 This hook is called by git-push(1) and can be used to prevent a push
192 from taking place. The hook is called with two parameters which provide
193 the name and location of the destination remote, if a named remote is
194 not being used both values will be the same.
195 Information about what is to be pushed is provided on the hook’s
197 standard input with lines of the form:
198 <local ref> SP <local object name> SP <remote ref> SP <remote object name> LF
200 For instance, if the command git push origin master:foreign were run
202 the hook would receive a line like the following:
203 refs/heads/master 67890 refs/heads/foreign 12345
205 although the full object name would be supplied. If the foreign ref
207 does not yet exist the <remote object name> will be the all-zeroes
208 object name. If a ref is to be deleted, the <local ref> will be
209 supplied as (delete) and the <local object name> will be the all-zeroes
210 object name. If the local commit was specified by something other than
211 a name which could be expanded (such as HEAD~, or an object name) it
212 will be supplied as it was originally given.
213 If this hook exits with a non-zero status, git push will abort without
215 pushing anything. Information about why the push is rejected may be
216 sent to the user by writing to standard error.
217 pre-receive
219 This hook is invoked by git-receive-pack(1) when it reacts to git push
220 and updates reference(s) in its repository. Just before starting to
221 update refs on the remote repository, the pre-receive hook is invoked.
222 Its exit status determines the success or failure of the update.
223 This hook executes once for the receive operation. It takes no
225 arguments, but for each ref to be updated it receives on standard input
226 a line of the format:
227 <old-value> SP <new-value> SP <ref-name> LF
229 where <old-value> is the old object name stored in the ref, <new-value>
231 is the new object name to be stored in the ref and <ref-name> is the
232 full name of the ref. When creating a new ref, <old-value> is the
233 all-zeroes object name.
234 If the hook exits with non-zero status, none of the refs will be
236 updated. If the hook exits with zero, updating of individual refs can
237 still be prevented by the update hook.
238 Both standard output and standard error output are forwarded to git
240 send-pack on the other end, so you can simply echo messages for the
241 user.
242 The number of push options given on the command line of git push
244 --push-option=... can be read from the environment variable
245 GIT_PUSH_OPTION_COUNT, and the options themselves are found in
246 GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,... If it is negotiated to not use
247 the push options phase, the environment variables will not be set. If
248 the client selects to use push options, but doesn’t transmit any, the
249 count variable will be set to zero, GIT_PUSH_OPTION_COUNT=0.
250 See the section on "Quarantine Environment" in git-receive-pack(1) for
252 some caveats.
253 update
255 This hook is invoked by git-receive-pack(1) when it reacts to git push
256 and updates reference(s) in its repository. Just before updating the
257 ref on the remote repository, the update hook is invoked. Its exit
258 status determines the success or failure of the ref update.
259 The hook executes once for each ref to be updated, and takes three
261 parameters:
262 • the name of the ref being updated,
264 • the old object name stored in the ref,
266 • and the new object name to be stored in the ref.
268 A zero exit from the update hook allows the ref to be updated. Exiting
270 with a non-zero status prevents git receive-pack from updating that
271 ref.
272 This hook can be used to prevent forced update on certain refs by
274 making sure that the object name is a commit object that is a
275 descendant of the commit object named by the old object name. That is,
276 to enforce a "fast-forward only" policy.
277 It could also be used to log the old..new status. However, it does not
279 know the entire set of branches, so it would end up firing one e-mail
280 per ref when used naively, though. The post-receive hook is more suited
281 to that.
282 In an environment that restricts the users' access only to git commands
284 over the wire, this hook can be used to implement access control
285 without relying on filesystem ownership and group membership. See git-
286 shell(1) for how you might use the login shell to restrict the user’s
287 access to only git commands.
288 Both standard output and standard error output are forwarded to git
290 send-pack on the other end, so you can simply echo messages for the
291 user.
292 The default update hook, when enabled—and with hooks.allowunannotated
294 config option unset or set to false—prevents unannotated tags to be
295 pushed.
296 proc-receive
298 This hook is invoked by git-receive-pack(1). If the server has set the
299 multi-valued config variable receive.procReceiveRefs, and the commands
300 sent to receive-pack have matching reference names, these commands will
301 be executed by this hook, instead of by the internal execute_commands()
302 function. This hook is responsible for updating the relevant references
303 and reporting the results back to receive-pack.
304 This hook executes once for the receive operation. It takes no
306 arguments, but uses a pkt-line format protocol to communicate with
307 receive-pack to read commands, push-options and send results. In the
308 following example for the protocol, the letter S stands for
309 receive-pack and the letter H stands for this hook.
310 # Version and features negotiation.
312 S: PKT-LINE(version=1\0push-options atomic...)
313 S: flush-pkt
314 H: PKT-LINE(version=1\0push-options...)
315 H: flush-pkt
316 # Send commands from server to the hook.
318 S: PKT-LINE(<old-oid> <new-oid> <ref>)
319 S: ... ...
320 S: flush-pkt
321 # Send push-options only if the 'push-options' feature is enabled.
322 S: PKT-LINE(push-option)
323 S: ... ...
324 S: flush-pkt
325 # Receive result from the hook.
327 # OK, run this command successfully.
328 H: PKT-LINE(ok <ref>)
329 # NO, I reject it.
330 H: PKT-LINE(ng <ref> <reason>)
331 # Fall through, let 'receive-pack' to execute it.
332 H: PKT-LINE(ok <ref>)
333 H: PKT-LINE(option fall-through)
334 # OK, but has an alternate reference. The alternate reference name
335 # and other status can be given in option directives.
336 H: PKT-LINE(ok <ref>)
337 H: PKT-LINE(option refname <refname>)
338 H: PKT-LINE(option old-oid <old-oid>)
339 H: PKT-LINE(option new-oid <new-oid>)
340 H: PKT-LINE(option forced-update)
341 H: ... ...
342 H: flush-pkt
343 Each command for the proc-receive hook may point to a pseudo-reference
345 and always has a zero-old as its old-oid, while the proc-receive hook
346 may update an alternate reference and the alternate reference may exist
347 already with a non-zero old-oid. For this case, this hook will use
348 "option" directives to report extended attributes for the reference
349 given by the leading "ok" directive.
350 The report of the commands of this hook should have the same order as
352 the input. The exit status of the proc-receive hook only determines the
353 success or failure of the group of commands sent to it, unless atomic
354 push is in use.
355 post-receive
357 This hook is invoked by git-receive-pack(1) when it reacts to git push
358 and updates reference(s) in its repository. It executes on the remote
359 repository once after all the refs have been updated.
360 This hook executes once for the receive operation. It takes no
362 arguments, but gets the same information as the pre-receive hook does
363 on its standard input.
364 This hook does not affect the outcome of git receive-pack, as it is
366 called after the real work is done.
367 This supersedes the post-update hook in that it gets both old and new
369 values of all the refs in addition to their names.
370 Both standard output and standard error output are forwarded to git
372 send-pack on the other end, so you can simply echo messages for the
373 user.
374 The default post-receive hook is empty, but there is a sample script
376 post-receive-email provided in the contrib/hooks directory in Git
377 distribution, which implements sending commit emails.
378 The number of push options given on the command line of git push
380 --push-option=... can be read from the environment variable
381 GIT_PUSH_OPTION_COUNT, and the options themselves are found in
382 GIT_PUSH_OPTION_0, GIT_PUSH_OPTION_1,... If it is negotiated to not use
383 the push options phase, the environment variables will not be set. If
384 the client selects to use push options, but doesn’t transmit any, the
385 count variable will be set to zero, GIT_PUSH_OPTION_COUNT=0.
386 post-update
388 This hook is invoked by git-receive-pack(1) when it reacts to git push
389 and updates reference(s) in its repository. It executes on the remote
390 repository once after all the refs have been updated.
391 It takes a variable number of parameters, each of which is the name of
393 ref that was actually updated.
394 This hook is meant primarily for notification, and cannot affect the
396 outcome of git receive-pack.
397 The post-update hook can tell what are the heads that were pushed, but
399 it does not know what their original and updated values are, so it is a
400 poor place to do log old..new. The post-receive hook does get both
401 original and updated values of the refs. You might consider it instead
402 if you need them.
403 When enabled, the default post-update hook runs git update-server-info
405 to keep the information used by dumb transports (e.g., HTTP) up to
406 date. If you are publishing a Git repository that is accessible via
407 HTTP, you should probably enable this hook.
408 Both standard output and standard error output are forwarded to git
410 send-pack on the other end, so you can simply echo messages for the
411 user.
412 reference-transaction
414 This hook is invoked by any Git command that performs reference
415 updates. It executes whenever a reference transaction is prepared,
416 committed or aborted and may thus get called multiple times. The hook
417 does not cover symbolic references (but that may change in the future).
418 The hook takes exactly one argument, which is the current state the
420 given reference transaction is in:
421 • "prepared": All reference updates have been queued to the
423 transaction and references were locked on disk.
424 • "committed": The reference transaction was committed and all
426 references now have their respective new value.
427 • "aborted": The reference transaction was aborted, no changes were
429 performed and the locks have been released.
430 For each reference update that was added to the transaction, the hook
432 receives on standard input a line of the format:
433 <old-value> SP <new-value> SP <ref-name> LF
435 where <old-value> is the old object name passed into the reference
437 transaction, <new-value> is the new object name to be stored in the ref
438 and <ref-name> is the full name of the ref. When force updating the
439 reference regardless of its current value or when the reference is to
440 be created anew, <old-value> is the all-zeroes object name. To
441 distinguish these cases, you can inspect the current value of
442 <ref-name> via git rev-parse.
443 The exit status of the hook is ignored for any state except for the
445 "prepared" state. In the "prepared" state, a non-zero exit status will
446 cause the transaction to be aborted. The hook will not be called with
447 "aborted" state in that case.
448 push-to-checkout
450 This hook is invoked by git-receive-pack(1) when it reacts to git push
451 and updates reference(s) in its repository, and when the push tries to
452 update the branch that is currently checked out and the
453 receive.denyCurrentBranch configuration variable is set to
454 updateInstead. Such a push by default is refused if the working tree
455 and the index of the remote repository has any difference from the
456 currently checked out commit; when both the working tree and the index
457 match the current commit, they are updated to match the newly pushed
458 tip of the branch. This hook is to be used to override the default
459 behaviour.
460 The hook receives the commit with which the tip of the current branch
462 is going to be updated. It can exit with a non-zero status to refuse
463 the push (when it does so, it must not modify the index or the working
464 tree). Or it can make any necessary changes to the working tree and to
465 the index to bring them to the desired state when the tip of the
466 current branch is updated to the new commit, and exit with a zero
467 status.
468 For example, the hook can simply run git read-tree -u -m HEAD "$1" in
470 order to emulate git fetch that is run in the reverse direction with
471 git push, as the two-tree form of git read-tree -u -m is essentially
472 the same as git switch or git checkout that switches branches while
473 keeping the local changes in the working tree that do not interfere
474 with the difference between the branches.
475 pre-auto-gc
477 This hook is invoked by git gc --auto (see git-gc(1)). It takes no
478 parameter, and exiting with non-zero status from this script causes the
479 git gc --auto to abort.
480 post-rewrite
482 This hook is invoked by commands that rewrite commits (git-commit(1)
483 when called with --amend and git-rebase(1); however, full-history
484 (re)writing tools like git-fast-import(1) or git-filter-repo[1]
485 typically do not call it!). Its first argument denotes the command it
486 was invoked by: currently one of amend or rebase. Further
487 command-dependent arguments may be passed in the future.
488 The hook receives a list of the rewritten commits on stdin, in the
490 format
491 <old-object-name> SP <new-object-name> [ SP <extra-info> ] LF
493 The extra-info is again command-dependent. If it is empty, the
495 preceding SP is also omitted. Currently, no commands pass any
496 extra-info.
497 The hook always runs after the automatic note copying (see
499 "notes.rewrite.<command>" in git-config(1)) has happened, and thus has
500 access to these notes.
501 The following command-specific comments apply:
503 rebase
505 For the squash and fixup operation, all commits that were squashed
506 are listed as being rewritten to the squashed commit. This means
507 that there will be several lines sharing the same new-object-name.
508 The commits are guaranteed to be listed in the order that they were
510 processed by rebase.
511 sendemail-validate
513 This hook is invoked by git-send-email(1). It takes a single parameter,
514 the name of the file that holds the e-mail to be sent. Exiting with a
515 non-zero status causes git send-email to abort before sending any
516 e-mails.
517 fsmonitor-watchman
519 This hook is invoked when the configuration option core.fsmonitor is
520 set to .git/hooks/fsmonitor-watchman or .git/hooks/fsmonitor-watchmanv2
521 depending on the version of the hook to use.
522 Version 1 takes two arguments, a version (1) and the time in elapsed
524 nanoseconds since midnight, January 1, 1970.
525 Version 2 takes two arguments, a version (2) and a token that is used
527 for identifying changes since the token. For watchman this would be a
528 clock id. This version must output to stdout the new token followed by
529 a NUL before the list of files.
530 The hook should output to stdout the list of all files in the working
532 directory that may have changed since the requested time. The logic
533 should be inclusive so that it does not miss any potential changes. The
534 paths should be relative to the root of the working directory and be
535 separated by a single NUL.
536 It is OK to include files which have not actually changed. All changes
538 including newly-created and deleted files should be included. When
539 files are renamed, both the old and the new name should be included.
540 Git will limit what files it checks for changes as well as which
542 directories are checked for untracked files based on the path names
543 given.
544 An optimized way to tell git "all files have changed" is to return the
546 filename /.
547 The exit status determines whether git will use the data from the hook
549 to limit its search. On error, it will fall back to verifying all files
550 and folders.
551 p4-changelist
553 This hook is invoked by git-p4 submit.
554 The p4-changelist hook is executed after the changelist message has
556 been edited by the user. It can be bypassed with the --no-verify
557 option. It takes a single parameter, the name of the file that holds
558 the proposed changelist text. Exiting with a non-zero status causes the
559 command to abort.
560 The hook is allowed to edit the changelist file and can be used to
562 normalize the text into some project standard format. It can also be
563 used to refuse the Submit after inspect the message file.
564 Run git-p4 submit --help for details.
566 p4-prepare-changelist
568 This hook is invoked by git-p4 submit.
569 The p4-prepare-changelist hook is executed right after preparing the
571 default changelist message and before the editor is started. It takes
572 one parameter, the name of the file that contains the changelist text.
573 Exiting with a non-zero status from the script will abort the process.
574 The purpose of the hook is to edit the message file in place, and it is
576 not suppressed by the --no-verify option. This hook is called even if
577 --prepare-p4-only is set.
578 Run git-p4 submit --help for details.
580 p4-post-changelist
582 This hook is invoked by git-p4 submit.
583 The p4-post-changelist hook is invoked after the submit has
585 successfully occurred in P4. It takes no parameters and is meant
586 primarily for notification and cannot affect the outcome of the git p4
587 submit action.
588 Run git-p4 submit --help for details.
590 p4-pre-submit
592 This hook is invoked by git-p4 submit. It takes no parameters and
593 nothing from standard input. Exiting with non-zero status from this
594 script prevent git-p4 submit from launching. It can be bypassed with
595 the --no-verify command line option. Run git-p4 submit --help for
596 details.
597 post-index-change
599 This hook is invoked when the index is written in read-cache.c
600 do_write_locked_index.
601 The first parameter passed to the hook is the indicator for the working
603 directory being updated. "1" meaning working directory was updated or
604 "0" when the working directory was not updated.
605 The second parameter passed to the hook is the indicator for whether or
607 not the index was updated and the skip-worktree bit could have changed.
608 "1" meaning skip-worktree bits could have been updated and "0" meaning
609 they were not.
610 Only one parameter should be set to "1" when the hook runs. The hook
612 running passing "1", "1" should not be possible.
613
615 Part of the git(1) suite
616
618 1. git-filter-repo
619 https://github.com/newren/git-filter-repo
620Git 2.33.1 2021-10-12 GITHOOKS(5)