Add git-for-each-ref: helper for language bindings
[gitweb.git] / Documentation / git-receive-pack.txt
index d3a835d4ba575c2173e6c6c7165968979a9cba9e..f9457d45ed684597769124af945c184a7d03a948 100644 (file)
@@ -1,6 +1,5 @@
 git-receive-pack(1)
 ===================
-v0.1, July 2005
 
 NAME
 ----
@@ -19,8 +18,60 @@ information fed from the remote end.
 This command is usually not invoked directly by the end user.
 The UI for the protocol is on the 'git-send-pack' side, and the
 program pair is meant to be used to push updates to remote
-repository.  For pull operations, see 'git-fetch-pack' and
-'git-clone-pack'.
+repository.  For pull operations, see 'git-fetch-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.
+
+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
+       # mail out commit update information.
+       if expr "$2" : '0*$' >/dev/null
+       then
+               echo "Created a new ref, with the following commits:"
+               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
+       exit 0
+
+Another hook $GIT_DIR/hooks/post-update, if exists and
+executable, is called with the list of refs that have been
+updated.  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.  This hook can be used, for
+example, to run "git-update-server-info" if the repository is
+packed and is served via a dumb transport.
+
+       #!/bin/sh
+       exec git-update-server-info
+
+There are other real-world examples of using update and
+post-update hooks found in the Documentation/howto directory.
 
 
 OPTIONS
@@ -28,6 +79,12 @@ OPTIONS
 <directory>::
        The repository to sync into.
 
+
+SEE ALSO
+--------
+gitlink:git-send-pack[1]
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>
@@ -38,4 +95,4 @@ Documentation by Junio C Hamano.
 
 GIT
 ---
-Part of the link:git.html[git] suite
+Part of the gitlink:git[7] suite