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