Re: [PATCH] Updated documentation of hooks in git-receive-pack.

From: Jan Hudec <bulb@ucw.cz>
Date: May 12, 2007, 20:13 UTC
Message-ID: <20070512201309.GB8983@efreet.light.src>
In-Reply-To: <7vmz09yh8n.fsf@assigned-by-dhcp.cox.net>

On Sat, May 12, 2007 at 12:27:52 -0700, Junio C Hamano wrote:

Show 9 quoted lines

> Jan Hudec <bulb@ucw.cz> writes:
> 
> > Added documentation of pre-receive and post-receive hooks and updated
> > documentation of update and post-update hooks.
> >
> > Signed-off-by: Jan Hudec <bulb@ucw.cz>
> 
> Thanks, much appreciated.  Domain ucw.cz sounds familiar; are
> you close by to Pasky?

Studied the same faculty.

Show 8 quoted lines

> [...]
> > +The standard output of this hook is sent to `stderr`, so if you
> > +want to report something to the `git-send-pack` on the other end,
> > +you can simply `echo` your messages.
> 
> I think "sent to stderr" is a implementation detail between
> receive-pack and hook scripts.  I would just keep the "if you
> want to..." part.

It's actually original wording from description of 'update'. I think just leaving out the stderr thing is not right, because it's important that both stdout and stderr go to the same place. I'll change it to:

  Both standard output and error output are forwarded to `git-send-pack` on
  the other end, so you can simply `echo` messages for the user.

Show 25 quoted lines

> > +[[post-receive]]
> > +post-receive
> > +------------
> > +
> > +This hook is invoked by `git-receive-pack` on the remote repository,
> > +which 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.
> > +
> > +This hook executes once for the receive operation.  It takes no
> > +arguments, but for each ref that was updated it receives on standard
> > +input a line of the format:
> > +
> > +  <old-value> SP <new-value> SP <ref-name> NL
> > +
> > +on stdin, where `<old-value>` is the old object name stored in the
> > +ref, `<new-value>` is the new object name to be stored in the ref and
> > +`<ref-name>` is the full name of the ref.
> 
> Maybe
> 
> 	It takes no arguments, but gets the same information as
> 	the `pre-receive` hook does on its standard input.
> 
> to avoid the duplicated description.

Makes sense.

Show 20 quoted lines

> > +[[post-update]]
> >  post-update
> >  -----------
> >  
> > @@ -146,7 +214,8 @@ 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.
> > +so it is a poor place to do log old..new. See
> > +<<post-receive,'post-receive'>> hook above for a better one.
> 
> Instead of just passing 'a better one' judgement without
> rationale, it is more helpful to explain why the newer ones are
> recommended, so that the reader can agree to it.
> 
>         In general, `post-receive` hook is preferred when the hook needs
>         to decide its acion on the status of the entire set of refs
>         being updated, as this hook is called once per ref, with
>         information only on a single ref at a time.

Yes, it's probably better. Though in this case the post-update hook should be really obsoleted. It takes names of all updated refs on command-line, which is unlikely to fail on linux, but might fail on Windows where the command-line lenght is much more limited. But for now I'll just mention that the other hook does have the information this one does not.

-- 
						 Jan 'Bulb' Hudec <bulb@ucw.cz>