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