Re: [PATCH] doc: clarify post-receive hook behavior

[Junio C Hamano <gitster@pobox.com>]

Justin Tobler <jltobler@gmail.com> writes:

> The `githooks` documentation mentions that the post-receive hook
> executes once after git-receive-pack(1) updates all references and that
> it also receives the same information as the pre-receive hook on
> standard input. This is misleading though because the hook only
> executes once if at least one of the attempted reference updates is
> successful. Also, while each line provided on standard input is in the
> same format as the pre-receive hook, the information received only
> includes the set of references that were successfully updated.

Yup, it sounds like is a sensible design that gives the most useful
information to the hook.

> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
> index 06e997131b..f9eb396a79 100644
> --- a/Documentation/githooks.txt
> +++ b/Documentation/githooks.txt
> @@ -415,13 +415,13 @@ post-receive
>  
>  This hook is invoked by linkgit:git-receive-pack[1] when it reacts to
>  `git push` and updates reference(s) in its repository.
> -It executes on the remote repository once after all the refs have
> -been updated.
> +It executes on the remote repository once if any of the attempted ref
> +updates are successful.

We could instead say "at least one of", but "any of" should be fine.
OK.

> -This hook executes once for the receive operation.  
> +For a receive operation, this hook executes a single time at most.  

Hmph, maybe we can strike this sentence as we already said "once" in
the previous paragraph.  The intention of the original description
that said "only after" was to convey two things:

 (1) it runs only once, and
 (2) it does not run before all the ref-update requests have been
     processed (either successfully or unsuccessfully).  

If the "only after" was not serving the original purpose of
conveying both of the two, then perhaps we should remove the word
"once" from the previous paragraph instead and keep this sentence.

My preference is revert your "once after" -> "once if" to get back
to the original "once after", and then remove "this hook executes
once for the receive operaiton" of the original, without adding your
"For a receieve ... at most".

    The hook executes on the remote repository once after all the
    proposed ref updates are processed and if at least one ref is
    updated as the result.

> -It takes no
> -arguments, but gets the same information as the
> -<<pre-receive,'pre-receive'>>
> -hook does on its standard input.
> -It
> +takes no arguments, but for each ref successfully updated, it receives a
> +line on standard input that follows the same format as the
> +<<pre-receive,'pre-receive'>> hook.

This part of the update is great.  The "but" there is annoying, but
that badness was inherited from the original and not a fault of this
patch.  If I were writing it from scratch I would probably have said
something like:

    The hook takes no arguments.  It receives one line on standard
    input for each ref that is successfully updated in the same
    format as the pre-receive hook.

Thanks.