Merge branch 'stable-3.1'

* stable-3.1:
  Fix and clarify documentation of ref-update and commit-received hooks
  Correct documentation of ref-update hook regarding output

Change-Id: I0926e8a9ab58be09ba7c30b3834ddf86b483480f

src/main/resources/Documentation/hooks.md

diff --git a/src/main/resources/Documentation/hooks.md b/src/main/resources/Documentation/hooks.md
index 70bf2c5..16bbc46 100644
--- a/src/main/resources/Documentation/hooks.md
+++ b/src/main/resources/Documentation/hooks.md
@@ -15,8 +15,12 @@
 ref deletion) is received by Gerrit. It allows a request to be rejected before it
 is committed to the Gerrit repository.
 
-If the hook exits with non-zero return code the update will be rejected. Any output
-from the hook will be returned to the user, regardless of the return code.
+When multiple commits are pushed by direct push, this hook is called once with
+the `--oldrev` being the sha1 of the current branch tip, and `--newrev` being the
+sha1 of the commit that will be the new tip of the branch.
+
+If the hook exits with non-zero return code the update will be rejected and any
+output will be returned to the user.
 
 ```
   ref-update --project <project name> --refname <refname> --uploader <uploader> --uploader-username <username> --oldrev <sha1> --newrev <sha1>
@@ -24,8 +28,10 @@
 
 ### commit-received
 
-This is called when a commit is received for review by Gerrit. It allows a push to
-be rejected before the review is created.
+This is called when a commit is received by Gerrit either by direct push or by
+push for review (to `refs/for/branch`). It allows a push to be rejected before
+a review is created, or before the branch is updated in case of a direct push.
+It is called once for each commit in the push.
 
 If the hook exits with non-zero return code the push will be rejected. Any output
 from the hook will be returned to the user, regardless of the return code.