git-applymbox: Remove command
[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
d45cc6e2 16typically invoked by `git-am`. It takes a single
6d35cc76 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
d45cc6e2 33typically invoked by `git-am`. It takes no parameter,
6d35cc76
JH
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
d45cc6e2 48typically invoked by `git-am`. It takes no parameter,
6d35cc76
JH
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
24a0d61e
JH
118Both standard output and standard error output are forwarded to
119`git-send-pack` on the other end, so you can simply `echo` messages
120for the user.
cbb84e5d
JH
121
122[[update]]
6d35cc76
JH
123update
124------
125
6250ad1e 126This hook is invoked by `git-receive-pack` on the remote repository,
45ad9b50 127which happens when a `git push` is done on a local repository.
6250ad1e 128Just before updating the ref on the remote repository, the update hook
37425065 129is invoked. Its exit status determines the success or failure of
6250ad1e
JL
130the ref update.
131
132The hook executes once for each ref to be updated, and takes
133three parameters:
45ad9b50
JF
134
135 - the name of the ref being updated,
136 - the old object name stored in the ref,
137 - and the new objectname to be stored in the ref.
6250ad1e
JL
138
139A zero exit from the update hook allows the ref to be updated.
140Exiting with a non-zero status prevents `git-receive-pack`
cbb84e5d 141from updating that ref.
6250ad1e
JL
142
143This hook can be used to prevent 'forced' update on certain refs by
6d35cc76
JH
144making sure that the object name is a commit object that is a
145descendant of the commit object named by the old object name.
6250ad1e
JL
146That is, to enforce a "fast forward only" policy.
147
148It could also be used to log the old..new status. However, it
149does not know the entire set of branches, so it would end up
cbb84e5d
JH
150firing one e-mail per ref when used naively, though. The
151<<post-receive,'post-receive'>> hook is more suited to that.
6250ad1e 152
6d35cc76
JH
153Another use suggested on the mailing list is to use this hook to
154implement access control which is finer grained than the one
155based on filesystem group.
156
24a0d61e
JH
157Both standard output and standard error output are forwarded to
158`git-send-pack` on the other end, so you can simply `echo` messages
159for the user.
3aadad1b 160
cbb84e5d
JH
161The default 'update' hook, when enabled--and with
162`hooks.allowunannotated` config option turned on--prevents
163unannotated tags to be pushed.
164
165[[post-receive]]
166post-receive
167------------
6250ad1e 168
cbb84e5d
JH
169This hook is invoked by `git-receive-pack` on the remote repository,
170which happens when a `git push` is done on a local repository.
171It executes on the remote repository once after all the refs have
172been updated.
173
174This hook executes once for the receive operation. It takes no
24a0d61e
JH
175arguments, but gets the same information as the
176<<pre-receive,'pre-receive'>>
cbb84e5d
JH
177hook does on its standard input.
178
179This hook does not affect the outcome of `git-receive-pack`, as it
180is called after the real work is done.
181
24a0d61e
JH
182This supersedes the <<post-update,'post-update'>> hook in that it get's
183both old and new values of all the refs in addition to their
184names.
cbb84e5d 185
24a0d61e
JH
186Both standard output and standard error output are forwarded to
187`git-send-pack` on the other end, so you can simply `echo` messages
188for the user.
cbb84e5d
JH
189
190The default 'post-receive' hook is empty, but there is
191a sample script `post-receive-email` provided in the `contrib/hooks`
192directory in git distribution, which implements sending commit
193emails.
194
195[[post-update]]
6d35cc76
JH
196post-update
197-----------
198
6250ad1e 199This hook is invoked by `git-receive-pack` on the remote repository,
45ad9b50 200which happens when a `git push` is done on a local repository.
6250ad1e
JL
201It executes on the remote repository once after all the refs have
202been updated.
203
204It takes a variable number of parameters, each of which is the
205name of ref that was actually updated.
6d35cc76
JH
206
207This hook is meant primarily for notification, and cannot affect
208the outcome of `git-receive-pack`.
209
45ad9b50 210The 'post-update' hook can tell what are the heads that were pushed,
6250ad1e 211but it does not know what their original and updated values are,
24a0d61e
JH
212so it is a poor place to do log old..new. The
213<<post-receive,'post-receive'>> hook does get both original and
214updated values of the refs. You might consider it instead if you need
215them.
cbb84e5d 216
45ad9b50 217When enabled, the default 'post-update' hook runs
6d35cc76 218`git-update-server-info` to keep the information used by dumb
45ad9b50
JF
219transports (e.g., HTTP) up-to-date. If you are publishing
220a git repository that is accessible via HTTP, you should
6250ad1e 221probably enable this hook.
3aadad1b 222
cbb84e5d 223Both standard output and standard error output are forwarded to
24a0d61e
JH
224`git-send-pack` on the other end, so you can simply `echo` messages
225for the user.