post-receive-email: document command-line mode

According to the default hooks/post-receive file, the hook is called
with three arguments on stdin:

  <oldrev> <newrev> <refname>

In command-line mode, the arguments come in a different order, because
the email hook instead calls:

  generate_email $2 $3 $1

Add a comment to explain why, based on comments from the mailing list
and the commit message to v1.5.1~9.  Thanks to Andy for the
explanation.

Requested-by: martin f. krafft <madduck@debian.org>
Cc: Andy Parkins <andyparkins@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/contrib/hooks/post-receive-email b/contrib/hooks/post-receive-email
index 58a35c82870c54f844fd1154a82237891655f38f..30ae63d74da065a31cced0b161708680f39c04c0 100755 (executable)
--- a/contrib/hooks/post-receive-email
+++ b/contrib/hooks/post-receive-email
@@ -23,6 +23,13 @@
 # possible for the email to be from someone other than the person doing the
 # push.
 #
+# To help with debugging and use on pre-v1.5.1 git servers, this script will
+# also obey the interface of hooks/update, taking its arguments on the
+# command line.  Unfortunately, hooks/update is called once for each ref.
+# To avoid firing one email per ref, this script just prints its output to
+# the screen when used in this mode.  The output can then be redirected if
+# wanted.
+#
 # Config
 # ------
 # hooks.mailinglist