Re: Documentation of post-receive hook

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

Junio C Hamano <gitster@pobox.com> writes:

>>     This hook is invoked by 'git-receive-pack' on the remote repository,
>>     which happens when a 'git push' is done on a local repository and
>>     successfully transfers at least 1 commit.
>
> I am not sure "at least 1 commit" is a good phrase to use here.
> There are transfer that sends objects but no commit object, and the
> above makes it sound as if such a transfer will not trigger the
> hook.  Would
>
> 	This hook is run by 'git receive-pack' on the remote
> 	repository, after it receives objects sent by 'git push'.
>
> be clear enough to teach readers that a no-op push that recieve-pack
> does not receive any object does not trigger the hook?

Actually I take this back.  Your original observation "only when at
least one commit is transferred" is not even correct.

You can try what I just tried to make sure:

        $ git clone --no-local . ../victim
        $ cat >../victim/.git/hooks/post-receive <<\EOF
        #!/bin/sh
        (
            echo "post receive was here at $(date)"
            cat 
        ) >>../STAMP
        EOF
        $ chmod +x ../victim/.git/hooks/post-receive
        $ git push ../victim master:foo

The last "push" does not transfer any object (and obviously does not
satisfy your "at least 1 commit" requirement), but it does update
the STAMP file.  This is because it updates a ref and that is what
post-receive wants to react to, even if there is no new objects
placed in the receiving repository.

So an updated suggestion for the text would be:

     This hook is invoked by 'git-receive-pack' on the remote repository,
     which happens when a 'git push' is done on a local repository.

Oh, wait.  That is what we already have ;-).

Having said all that, there is one case that running 'git push' does
*NOT* cause 'receive-pack' to be invoked at the other end, and in
that scenario, obviously the hook cannot be run, simply because the
command that would run the hook is not run in the first place.

After the above sequence against the "victim" test repository, you
could try:

        $ git push ../victim master:foo
	Everything up-to-date

and observe that the STAMP file is not updated.

What is happening is that "git push" notices that there is nothing
gained by invoking receive-pack on the other side, because the
branch 'foo' already points at the commit at the tip of our
'master'.

So it might technically be an improvement to update the text to
mention that 'git push' does not necessarily always lead to
invocation of receive-pack, something like:

     This hook is invoked by 'git-receive-pack' on the remote
     repository, which may happen when a 'git push' is done on a
     local repository.

but then that introduces the need to make the reader understand what
"may happen" is trying to say, iow, when does a user 'push' and it
does not trigger receive-pack?

But I do not think teaching that (i.e. when does receive-pack run?)
is the job of this paragraph, whose primary objective is to teach
about this hook that is run when receive-pack is run.  So...