[PATCH] doc: clarify post-receive hook behavior

[Justin Tobler <jltobler@gmail.com>]

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.

Update the documentation to clarify these points and also provide a
reference to the post-receive hook section of the `git-receive-pack`
documentation which has additional information.

Signed-off-by: Justin Tobler <jltobler@gmail.com>

---

Greetings all,

I was recently looking into post-receive hooks and found some of its
documentation[1] a bit misleading. With this patch, the `githooks`
documentation is updated to better align with the hooks documentation
for `git-receive-pack`[2]. Thanks for taking a look!

-Justin

1: https://git-scm.com/docs/githooks#post-receive
2: https://git-scm.com/docs/git-receive-pack#_post_receive_hook
---
 Documentation/githooks.txt | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

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.
 
-This hook executes once for the receive operation.  It takes no
-arguments, but gets the same information as the
-<<pre-receive,'pre-receive'>>
-hook does on its standard input.
+For a receive operation, this hook executes a single time at most.  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 hook does not affect the outcome of `git receive-pack`, as it
 is called after the real work is done.
@@ -448,6 +448,9 @@ environment variables will not be set. If the client selects
 to use push options, but doesn't transmit any, the count variable
 will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.
 
+See the link:git-receive-pack.html#_post_receive_hook[post-receive hook]
+section in linkgit:git-receive-pack[1] for additional details.
+
 [[post-update]]
 post-update
 ~~~~~~~~~~~

base-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9
-- 
2.45.2