Fix and clarify documentation of ref-update and commit-received hooks
- Clarify behavior of ref-update when multiple commits are pushed, i.e.
that it is only called once for the entire ref update.
- Fix the documentation of commit-received which states that it is called
for changes pushed for review. In fact it is also called for direct
pushes, but unlike ref-update it is called once for each commit.
Change-Id: Ie3e2dcab37eeb5d0ed06e05322e72d3fc73925fd
diff --git a/src/main/resources/Documentation/hooks.md b/src/main/resources/Documentation/hooks.md
index c4b5fd7..dad750f 100644
--- a/src/main/resources/Documentation/hooks.md
+++ b/src/main/resources/Documentation/hooks.md
@@ -15,6 +15,10 @@
ref deletion) is received by Gerrit. It allows a request to be rejected before it
is committed to the Gerrit repository.
+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.
@@ -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.
