summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJon Loeliger <jdl@jdl.com>2006-03-25 03:21:07 (GMT)
committerJunio C Hamano <junkio@cox.net>2006-03-25 06:24:02 (GMT)
commit6250ad1e7aacbcb9a2a8944e0c664f1e7ec93ef6 (patch)
tree5c426a1922e25efd00ca9c8186b79973a1a92090 /Documentation
parent7561d9f54412fcf443ebb28040bad67cd054a986 (diff)
downloadgit-6250ad1e7aacbcb9a2a8944e0c664f1e7ec93ef6.zip
git-6250ad1e7aacbcb9a2a8944e0c664f1e7ec93ef6.tar.gz
git-6250ad1e7aacbcb9a2a8944e0c664f1e7ec93ef6.tar.bz2
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>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/git.txt2
-rw-r--r--Documentation/hooks.txt51
-rw-r--r--Documentation/repository-layout.txt2
3 files changed, 42 insertions, 13 deletions
diff --git a/Documentation/git.txt b/Documentation/git.txt
index de3934d..0c424ff8 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -531,6 +531,8 @@ File/Directory Structure
Please see link:repository-layout.html[repository layout] document.
+Read link:hooks.html[hooks] for more details about each hook.
+
Higher level SCMs may provide and manage additional information in the
`$GIT_DIR`.
diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt
index 4ad1920..3824a95 100644
--- a/Documentation/hooks.txt
+++ b/Documentation/hooks.txt
@@ -97,16 +97,31 @@ send out a commit notification e-mail.
update
------
-This hook is invoked by `git-receive-pack`, which is invoked
-when a `git push` is done against the repository. It takes
-three parameters, name of the ref being updated, old object name
-stored in the ref, and the new objectname to be stored in the
-ref. Exiting with non-zero status from this hook prevents
-`git-receive-pack` from updating the ref.
-
-This can be used to prevent 'forced' update on certain refs by
+This hook is invoked by `git-receive-pack` on the remote repository,
+which is happens when a `git push` is done on a local repository.
+Just before updating the ref on the remote repository, the update hook
+is invoked. It's exit status determins the success or failure of
+the ref update.
+
+The hook executes once for each ref to be updated, and takes
+three parameters:
+ - the name of the ref being updated,
+ - the old object name stored in the ref,
+ - and the new objectname to be stored in the ref.
+
+A zero exit from the update hook allows the ref to be updated.
+Exiting with a non-zero status prevents `git-receive-pack`
+from updating the ref.
+
+This hook can be used to prevent 'forced' update on certain refs by
making sure that the object name is a commit object that is a
descendant of the commit object named by the old object name.
+That is, to enforce a "fast forward only" policy.
+
+It could also be used to log the old..new status. However, it
+does not know the entire set of branches, so it would end up
+firing one e-mail per ref when used naively, though.
+
Another use suggested on the mailing list is to use this hook to
implement access control which is finer grained than the one
based on filesystem group.
@@ -115,20 +130,30 @@ The standard output of this hook is sent to /dev/null; if you
want to report something to the git-send-pack on the other end,
you can redirect your output to your stderr.
+
post-update
-----------
-This hook is invoked by `git-receive-pack`, which is invoked
-when a `git push` is done against the repository. It takes
-variable number of parameters; each of which is the name of ref
-that was actually updated.
+This hook is invoked by `git-receive-pack` on the remote repository,
+which is happens when a `git push` is done on a local repository.
+It executes on the remote repository once after all the refs have
+been updated.
+
+It takes a variable number of parameters, each of which is the
+name of ref that was actually updated.
This hook is meant primarily for notification, and cannot affect
the outcome of `git-receive-pack`.
+The post-update hook can tell what are the heads that were pushed,
+but it does not know what their original and updated values are,
+so it is a poor place to do log old..new.
+
The default post-update hook, when enabled, runs
`git-update-server-info` to keep the information used by dumb
-transport up-to-date.
+transports (eg, http) up-to-date. If you are publishing
+a git repository that is accessible via http, you should
+probably enable this hook.
The standard output of this hook is sent to /dev/null; if you
want to report something to the git-send-pack on the other end,
diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt
index 1f19bf8..98fbe7d 100644
--- a/Documentation/repository-layout.txt
+++ b/Documentation/repository-layout.txt
@@ -89,6 +89,8 @@ hooks::
commands. A handful of sample hooks are installed when
`git init-db` is run, but all of them are disabled by
default. To enable, they need to be made executable.
+ Read link:hooks.html[hooks] for more details about
+ each hook.
index::
The current index file for the repository. It is