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
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.
