[PATCH] Added hook in git-receive-pack

Just before updating a ref,

    $GIT_DIR/hooks/update refname old-sha1 new-sha1

is called if executable.  The hook can decline the ref to be
updated by exiting with a non-zero status, or allow it to be
updated by exiting with a zero status.  The mechanism also
allows e.g sending of a mail with pushed commits on the remote
repository.

Documentation update with an example hook is included.

jc: The credits of the basic idea and initial implementation go
to Josef, but I ended up rewriting major parts of his patch, so
bugs are all mine.  Also I changed the semantics for the hook
from his original version (which were post-update hook) so that
the hook can optionally decline to update the ref, and also can
be used to implement the overall cleanups.  The latter was
primarily to implement a suggestion from Linus that calling
update-server-info should be made optional.

Signed-off-by: Junio C Hamano <junkio@cox.net>

1 files changed, 49 insertions, 0 deletions

diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index d3a835d4ba..7f95e44046 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -22,6 +22,55 @@ program pair is meant to be used to push updates to remote
 repository.  For pull operations, see 'git-fetch-pack' and
 'git-clone-pack'.
 
+The command allows for creation and fast forwarding of sha1 refs
+(heads/tags) on the remote end (strictly speaking, it is the
+local end receive-pack runs, but to the user who is sitting at
+the send-pack end, it is updating the remote.  Confused?)
+
+Before each ref is updated, if $GIT_DIR/hooks/update file exists
+and executable, it is called with three parameters:
+
+       $GIT_DIR/hooks/update refname sha1-old sha1-new
+
+The refname parameter is relative to $GIT_DIR; e.g. for the
+master head this is "refs/heads/master".  Two sha1 are the
+object names for the refname before and after the update.  Note
+that the hook is called before the refname is updated, so either
+sha1-old is 0{40} (meaning there is no such ref yet), or it
+should match what is recorded in refname.
+
+The hook should exit with non-zero status if it wants to
+disallow updating the named ref.  Otherwise it should exit with
+zero.
+
+The same hook is also called with an empty string as refname and
+no other arguments just before git-receive-pack exits.  This can
+be used to implement repository wide cleanup task if needed.
+The exit code from this hook invocation is ignored; the only
+thing left for git-receive-pack to do at that point is to exit
+itself anyway.
+
+Using this hook, it is easy to generate mails on updates to
+the local repository. This example script sends a mail with
+the commits pushed to the repository:
+
+	#!/bin/sh
+	case "$#,$1" in
+	1,) # help packed repository pulled via dumb protocol.
+	    git-update-server-info
+	    ;;
+	*)  # mail out commit update information.
+	    if expr "$2" : '0*$' >/dev/null
+	    then
+		echo "Created now ref."
+		git-rev-list --pretty "$2"
+	    else
+		echo "New commits"
+		git-rev-list --pretty "$3" "^$2"
+	    fi |
+	    mail -s "Changes to ref $1" commit-list@mydomain
+        esac
+	exit 0
 
 OPTIONS
 -------