Updated documentation of hooks in git-receive-pack.
Added documentation of pre-receive and post-receive hooks and updated documentation of update and post-update hooks. [jc: with minor copy-editing] Signed-off-by: Jan Hudec <bulb@ucw.cz> Signed-off-by: Junio C Hamano <junkio@cox.net>
Jan Hudec committed
May 12, 2007 at 19:11 UTC
cbb84e5d174cf33fd4dcf3136de50a886ff9a2e2
1 file changed
+70
-7
Documentation/hooks.txt
+70
-7
@@ -90,6 +90,35 @@ parameter, and is invoked after a commit is made.
90
This hook is meant primarily for notification, and cannot affect
91
the outcome of `git-commit`.
92
93
+[[pre-receive]]
94
+pre-receive
95
+-----------
96
+
97
+This hook is invoked by `git-receive-pack` on the remote repository,
98
+which happens when a `git push` is done on a local repository.
99
+Just before starting to update refs on the remote repository, the
100
+pre-receive hook is invoked. Its exit status determines the success
101
+or failure of the update.
102
+
103
+This hook executes once for the receive operation. It takes no
104
+arguments, but for each ref to be updated it receives on standard
105
+input a line of the format:
106
+
107
+ <old-value> SP <new-value> SP <ref-name> LF
108
+
109
+where `<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.
112
+When creating a new ref, `<old-value>` is 40 `0`.
113
+
114
+If the hook exits with non-zero status, none of the refs will be
115
+updated. If the hook exits with zero, updating of individual refs can
116
+still be prevented by the <<update,'update'>> hook.
117
+
118
+If you want to report something to the `git-send-pack` on the other end,
119
+you can simply `echo` your messages.
120
+
121
+[[update]]
122
update
123
------
124
@@ -108,7 +137,7 @@ three parameters:
137
138
A zero exit from the update hook allows the ref to be updated.
139
Exiting with a non-zero status prevents `git-receive-pack`
111
-from updating the ref.
140
+from updating that ref.
141
142
This hook can be used to prevent 'forced' update on certain refs by
143
making sure that the object name is a commit object that is a
@@ -117,7 +146,8 @@ That is, to enforce a "fast forward only" policy.
146
147
It could also be used to log the old..new status. However, it
148
does not know the entire set of branches, so it would end up
120
-firing one e-mail per ref when used naively, though.
149
+firing one e-mail per ref when used naively, though. The
150
+<<post-receive,'post-receive'>> hook is more suited to that.
151
152
Another use suggested on the mailing list is to use this hook to
153
implement access control which is finer grained than the one
@@ -127,9 +157,38 @@ The standard output of this hook is sent to `stderr`, so if you
157
want to report something to the `git-send-pack` on the other end,
158
you can simply `echo` your messages.
159
130
-The default 'update' hook, when enabled, demonstrates how to
131
-send out a notification e-mail.
160
+The default 'update' hook, when enabled--and with
161
+`hooks.allowunannotated` config option turned on--prevents
162
+unannotated tags to be pushed.
163
+
164
+[[post-receive]]
165
+post-receive
166
+------------
167
168
+This hook is invoked by `git-receive-pack` on the remote repository,
169
+which happens when a `git push` is done on a local repository.
170
+It executes on the remote repository once after all the refs have
171
+been updated.
172
+
173
+This hook executes once for the receive operation. It takes no
174
+arguments, but gets the same information as the `pre-receive`
175
+hook does on its standard input.
176
+
177
+This hook does not affect the outcome of `git-receive-pack`, as it
178
+is called after the real work is done.
179
+
180
+This supersedes the [[post-update]] hook in that it actually get's
181
+both old and new values of all the refs.
182
+
183
+If you want to report something to the `git-send-pack` on the
184
+other end, you can simply `echo` your messages.
185
+
186
+The default 'post-receive' hook is empty, but there is
187
+a sample script `post-receive-email` provided in the `contrib/hooks`
188
+directory in git distribution, which implements sending commit
189
+emails.
190
+
191
+[[post-update]]
192
post-update
193
-----------
194
@@ -148,12 +207,16 @@ The 'post-update' hook can tell what are the heads that were pushed,
207
but it does not know what their original and updated values are,
208
so it is a poor place to do log old..new.
209
210
+In general, `post-receive` hook is preferred when the hook needs
211
+to decide its acion on the status of the entire set of refs
212
+being updated, as this hook is called once per ref, with
213
+information only on a single ref at a time.
214
+
215
When enabled, the default 'post-update' hook runs
216
`git-update-server-info` to keep the information used by dumb
217
transports (e.g., HTTP) up-to-date. If you are publishing
218
a git repository that is accessible via HTTP, you should
219
probably enable this hook.
220
157
-The standard output of this hook is sent to `/dev/null`; if you
158
-want to report something to the `git-send-pack` on the other end,
159
-you can redirect your output to your `stderr`.
221
+Both standard output and standard error output are forwarded to
222
+`git-send-pack` on the other end.