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

From: Junio C Hamano <junkio@cox.net>
Date: May 12, 2007, 19:27 UTC
Message-ID: <7vmz09yh8n.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <20070512171113.GA8100@efreet.light.src>

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?

Show 12 quoted lines

> +[[pre-receive]]
> +pre-receive
>...
> +This hook executes once for the receive operation. It takes no
> +arguments, but for each ref to be updated it receives on standard
> +input a line of the format:
> +
> +  <old-value> SP <new-value> SP <ref-name> NL
> +
> +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.

s/NL/LF/ When creating a new ref, `<old-value>` is 40 `0`.

> +If the hook exits with non-zero status, none of the refs will be
> +updated. If the hook returs zero, updating of individual refs can
> +still be prevented by the <<update,'update'>> hook.

s/returs/exits with/

> +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.

Show 18 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.

Show 5 quoted lines

> +This hook cannot affect the outcome of `git-receive-pack`, as it's
> +called after the real work is done.
> +
> +This superceedes the [[post-update]] hook in that it actually get's
> +both old and new values of all the refs.

s/superceedes/supersedes/

> +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.

Ditto.

Show 11 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.