Clarify and expand some hook documentation.
Clarify update and post-update hooks. Made a few references to the hooks documentation. Signed-off-by: Jon Loeliger <jdl@jdl.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
Jon Loeliger committed
Mar 24, 2006 at 21:21 UTC
6250ad1e7aacbcb9a2a8944e0c664f1e7ec93ef6
3 files changed
+42
-13
Documentation/git.txt
+2
@@ -531,6 +531,8 @@ File/Directory Structure
531
532
Please see link:repository-layout.html[repository layout] document.
533
534
+Read link:hooks.html[hooks] for more details about each hook.
535
+
536
Higher level SCMs may provide and manage additional information in the
537
`$GIT_DIR`.
538
Documentation/hooks.txt
+38
-13
@@ -97,16 +97,31 @@ send out a commit notification e-mail.
97
update
98
------
99
100
-This hook is invoked by `git-receive-pack`, which is invoked
101
-when a `git push` is done against the repository. It takes
102
-three parameters, name of the ref being updated, old object name
103
-stored in the ref, and the new objectname to be stored in the
104
-ref. Exiting with non-zero status from this hook prevents
105
-`git-receive-pack` from updating the ref.
106
-
107
-This can be used to prevent 'forced' update on certain refs by
100
+This hook is invoked by `git-receive-pack` on the remote repository,
101
+which is happens when a `git push` is done on a local repository.
102
+Just before updating the ref on the remote repository, the update hook
103
+is invoked. It's exit status determins the success or failure of
104
+the ref update.
105
+
106
+The hook executes once for each ref to be updated, and takes
107
+three parameters:
108
+ - the name of the ref being updated,
109
+ - the old object name stored in the ref,
110
+ - and the new objectname to be stored in the ref.
111
+
112
+A zero exit from the update hook allows the ref to be updated.
113
+Exiting with a non-zero status prevents `git-receive-pack`
114
+from updating the ref.
115
+
116
+This hook can be used to prevent 'forced' update on certain refs by
117
making sure that the object name is a commit object that is a
118
descendant of the commit object named by the old object name.
119
+That is, to enforce a "fast forward only" policy.
120
+
121
+It could also be used to log the old..new status. However, it
122
+does not know the entire set of branches, so it would end up
123
+firing one e-mail per ref when used naively, though.
124
+
125
Another use suggested on the mailing list is to use this hook to
126
implement access control which is finer grained than the one
127
based on filesystem group.
@@ -115,20 +130,30 @@ The standard output of this hook is sent to /dev/null; if you
130
want to report something to the git-send-pack on the other end,
131
you can redirect your output to your stderr.
132
133
+
134
post-update
135
-----------
136
121
-This hook is invoked by `git-receive-pack`, which is invoked
122
-when a `git push` is done against the repository. It takes
123
-variable number of parameters; each of which is the name of ref
124
-that was actually updated.
137
+This hook is invoked by `git-receive-pack` on the remote repository,
138
+which is happens when a `git push` is done on a local repository.
139
+It executes on the remote repository once after all the refs have
140
+been updated.
141
+
142
+It takes a variable number of parameters, each of which is the
143
+name of ref that was actually updated.
144
145
This hook is meant primarily for notification, and cannot affect
146
the outcome of `git-receive-pack`.
147
148
+The post-update hook can tell what are the heads that were pushed,
149
+but it does not know what their original and updated values are,
150
+so it is a poor place to do log old..new.
151
+
152
The default post-update hook, when enabled, runs
153
`git-update-server-info` to keep the information used by dumb
131
-transport up-to-date.
154
+transports (eg, http) up-to-date. If you are publishing
155
+a git repository that is accessible via http, you should
156
+probably enable this hook.
157
158
The standard output of this hook is sent to /dev/null; if you
159
want to report something to the git-send-pack on the other end,
Documentation/repository-layout.txt
+2
@@ -89,6 +89,8 @@ hooks::
89
commands. A handful of sample hooks are installed when
90
`git init-db` is run, but all of them are disabled by
91
default. To enable, they need to be made executable.
92
+ Read link:hooks.html[hooks] for more details about
93
+ each hook.
94
95
index::
96
The current index file for the repository. It is