Merge branch 'maint'
[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
15This hook is invoked by `git-applypatch` script, which is
16typically invoked by `git-applymbox`. It takes a single
17parameter, the name of the file that holds the proposed commit
45ad9b50
JF
18log message. Exiting with non-zero status causes
19`git-applypatch` to abort before applying the patch.
6d35cc76
JH
20
21The hook is allowed to edit the message file in place, and can
22be used to normalize the message into some project standard
23format (if the project has one). It can also be used to refuse
24the commit after inspecting the message file.
25
45ad9b50
JF
26The default 'applypatch-msg' hook, when enabled, runs the
27'commit-msg' hook, if the latter is enabled.
6d35cc76
JH
28
29pre-applypatch
30--------------
31
32This hook is invoked by `git-applypatch` script, which is
33typically invoked by `git-applymbox`. It takes no parameter,
34and is invoked after the patch is applied, but before a commit
35is made. Exiting with non-zero status causes the working tree
36after application of the patch not committed.
37
38It can be used to inspect the current working tree and refuse to
39make a commit if it does not pass certain test.
40
45ad9b50
JF
41The default 'pre-applypatch' hook, when enabled, runs the
42'pre-commit' hook, if the latter is enabled.
6d35cc76
JH
43
44post-applypatch
45---------------
46
47This hook is invoked by `git-applypatch` script, which is
48typically invoked by `git-applymbox`. It takes no parameter,
49and is invoked after the patch is applied and a commit is made.
50
51This hook is meant primarily for notification, and cannot affect
52the outcome of `git-applypatch`.
53
54pre-commit
55----------
56
215a7ad1 57This hook is invoked by `git-commit`, and can be bypassed
e1ccf53a 58with `\--no-verify` option. It takes no parameter, and is
6d35cc76
JH
59invoked before obtaining the proposed commit log message and
60making a commit. Exiting with non-zero status from this script
215a7ad1 61causes the `git-commit` to abort.
6d35cc76 62
45ad9b50 63The default 'pre-commit' hook, when enabled, catches introduction
6d35cc76 64of lines with trailing whitespaces and aborts the commit when
45ad9b50 65such a line is found.
6d35cc76
JH
66
67commit-msg
68----------
69
215a7ad1 70This hook is invoked by `git-commit`, and can be bypassed
e1ccf53a 71with `\--no-verify` option. It takes a single parameter, the
6d35cc76 72name of the file that holds the proposed commit log message.
215a7ad1 73Exiting with non-zero status causes the `git-commit` to
6d35cc76
JH
74abort.
75
76The hook is allowed to edit the message file in place, and can
77be used to normalize the message into some project standard
78format (if the project has one). It can also be used to refuse
79the commit after inspecting the message file.
80
45ad9b50
JF
81The default 'commit-msg' hook, when enabled, detects duplicate
82"Signed-off-by" lines, and aborts the commit if one is found.
6d35cc76
JH
83
84post-commit
85-----------
86
215a7ad1 87This hook is invoked by `git-commit`. It takes no
6d35cc76
JH
88parameter, and is invoked after a commit is made.
89
90This hook is meant primarily for notification, and cannot affect
215a7ad1 91the outcome of `git-commit`.
6d35cc76 92
cbb84e5d
JH
93[[pre-receive]]
94pre-receive
95-----------
96
97This hook is invoked by `git-receive-pack` on the remote repository,
98which happens when a `git push` is done on a local repository.
99Just before starting to update refs on the remote repository, the
100pre-receive hook is invoked. Its exit status determines the success
101or failure of the update.
102
103This hook executes once for the receive operation. It takes no
104arguments, but for each ref to be updated it receives on standard
105input a line of the format:
106
107 <old-value> SP <new-value> SP <ref-name> LF
108
109where `<old-value>` is the old object name stored in the ref,
110`<new-value>` is the new object name to be stored in the ref and
111`<ref-name>` is the full name of the ref.
112When creating a new ref, `<old-value>` is 40 `0`.
113
114If the hook exits with non-zero status, none of the refs will be
115updated. If the hook exits with zero, updating of individual refs can
116still be prevented by the <<update,'update'>> hook.
117
118If you want to report something to the `git-send-pack` on the other end,
119you can simply `echo` your messages.
120
121[[update]]
6d35cc76
JH
122update
123------
124
6250ad1e 125This hook is invoked by `git-receive-pack` on the remote repository,
45ad9b50 126which happens when a `git push` is done on a local repository.
6250ad1e 127Just before updating the ref on the remote repository, the update hook
37425065 128is invoked. Its exit status determines the success or failure of
6250ad1e
JL
129the ref update.
130
131The hook executes once for each ref to be updated, and takes
132three parameters:
45ad9b50
JF
133
134 - the name of the ref being updated,
135 - the old object name stored in the ref,
136 - and the new objectname to be stored in the ref.
6250ad1e
JL
137
138A zero exit from the update hook allows the ref to be updated.
139Exiting with a non-zero status prevents `git-receive-pack`
cbb84e5d 140from updating that ref.
6250ad1e
JL
141
142This hook can be used to prevent 'forced' update on certain refs by
6d35cc76
JH
143making sure that the object name is a commit object that is a
144descendant of the commit object named by the old object name.
6250ad1e
JL
145That is, to enforce a "fast forward only" policy.
146
147It could also be used to log the old..new status. However, it
148does not know the entire set of branches, so it would end up
cbb84e5d
JH
149firing one e-mail per ref when used naively, though. The
150<<post-receive,'post-receive'>> hook is more suited to that.
6250ad1e 151
6d35cc76
JH
152Another use suggested on the mailing list is to use this hook to
153implement access control which is finer grained than the one
154based on filesystem group.
155
87a3d29f 156The standard output of this hook is sent to `stderr`, so if you
45ad9b50 157want to report something to the `git-send-pack` on the other end,
87a3d29f 158you can simply `echo` your messages.
3aadad1b 159
cbb84e5d
JH
160The default 'update' hook, when enabled--and with
161`hooks.allowunannotated` config option turned on--prevents
162unannotated tags to be pushed.
163
164[[post-receive]]
165post-receive
166------------
6250ad1e 167
cbb84e5d
JH
168This hook is invoked by `git-receive-pack` on the remote repository,
169which happens when a `git push` is done on a local repository.
170It executes on the remote repository once after all the refs have
171been updated.
172
173This hook executes once for the receive operation. It takes no
174arguments, but gets the same information as the `pre-receive`
175hook does on its standard input.
176
177This hook does not affect the outcome of `git-receive-pack`, as it
178is called after the real work is done.
179
180This supersedes the [[post-update]] hook in that it actually get's
181both old and new values of all the refs.
182
183If you want to report something to the `git-send-pack` on the
184other end, you can simply `echo` your messages.
185
186The default 'post-receive' hook is empty, but there is
187a sample script `post-receive-email` provided in the `contrib/hooks`
188directory in git distribution, which implements sending commit
189emails.
190
191[[post-update]]
6d35cc76
JH
192post-update
193-----------
194
6250ad1e 195This hook is invoked by `git-receive-pack` on the remote repository,
45ad9b50 196which happens when a `git push` is done on a local repository.
6250ad1e
JL
197It executes on the remote repository once after all the refs have
198been updated.
199
200It takes a variable number of parameters, each of which is the
201name of ref that was actually updated.
6d35cc76
JH
202
203This hook is meant primarily for notification, and cannot affect
204the outcome of `git-receive-pack`.
205
45ad9b50 206The 'post-update' hook can tell what are the heads that were pushed,
6250ad1e
JL
207but it does not know what their original and updated values are,
208so it is a poor place to do log old..new.
209
cbb84e5d
JH
210In general, `post-receive` hook is preferred when the hook needs
211to decide its acion on the status of the entire set of refs
212being updated, as this hook is called once per ref, with
213information only on a single ref at a time.
214
45ad9b50 215When enabled, the default 'post-update' hook runs
6d35cc76 216`git-update-server-info` to keep the information used by dumb
45ad9b50
JF
217transports (e.g., HTTP) up-to-date. If you are publishing
218a git repository that is accessible via HTTP, you should
6250ad1e 219probably enable this hook.
3aadad1b 220
cbb84e5d
JH
221Both standard output and standard error output are forwarded to
222`git-send-pack` on the other end.