@matheusbsbs / matheus-bagliano / commits / 6250ad1e7a
Fork 0

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