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