X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Fhooks.txt;h=3824a9517ccec80ba0325578929a2ea95dca7296;hb=fe77bb1a02d5b8dd3915cd27a83b660debaecda4;hp=ca0efeeccf0a9f82f62c484f26ad26d97f531b4b;hpb=215a7ad1ef790467a4cd3f0dcffbd6e5f04c38f7;p=git.git

diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt
index ca0efeec..3824a951 100644
--- a/Documentation/hooks.txt
+++ b/Documentation/hooks.txt
@@ -1,6 +1,5 @@
-Hooks used by GIT
+Hooks used by git
 =================
-v0.99.6, Sep 2005
 
 Hooks are little scripts you can place in `$GIT_DIR/hooks`
 directory to trigger action at certain points.  When
@@ -57,7 +56,7 @@ pre-commit
 ----------
 
 This hook is invoked by `git-commit`, and can be bypassed
-with `--no-verify` option.  It takes no parameter, and is
+with `\--no-verify` option.  It takes no parameter, and is
 invoked before obtaining the proposed commit log message and
 making a commit.  Exiting with non-zero status from this script
 causes the `git-commit` to abort.
@@ -70,7 +69,7 @@ commit-msg
 ----------
 
 This hook is invoked by `git-commit`, and can be bypassed
-with `--no-verify` option.  It takes a single parameter, the
+with `\--no-verify` option.  It takes a single parameter, the
 name of the file that holds the proposed commit log message.
 Exiting with non-zero status causes the `git-commit` to
 abort.
@@ -98,31 +97,64 @@ 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 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.
 
-This can be used to prevent 'forced' update on certain refs by
+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.
 
+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,
+you can redirect your output to your stderr.