[PATCH v12 7/7] doc: add documentation for the proc-receive hook
From: Jiang Xin <zhiyou.jx@alibaba-inc.com>
Add documentation for the new "proc-receive" hook.
Signed-off-by: Jiang Xin <zhiyou.jx@alibaba-inc.com>
---
Documentation/githooks.txt | 58 ++++++++++++++++++++++++++++++++++++++
1 file changed, 58 insertions(+)
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 3dccab5375..a0ea829435 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -333,6 +333,64 @@ The default 'update' hook, when enabled--and with
`hooks.allowunannotated` config option unset or set to false--prevents
unannotated tags to be pushed.
+proc-receive
+~~~~~~~~~~~~
+
+This hook is invoked by linkgit:git-receive-pack[1]. If the server has
+set the multi-valued config variable `receive.procReceiveRefs`, and the
+commands sent to 'receive-pack' have matching reference names, these
+commands will be executed by this hook, instead of by the internal
+`execute_commands()` function. This hook is responsible for updating
+the relevant references and reporting the results back to 'receive-pack'.
+
+This hook executes once for the receive operation. It takes no
+arguments, but uses a pkt-line format protocol to communicate with
+'receive-pack' to read commands, push-options and send results. In the
+following example for the protocol, the letter 'S' stands for
+'receive-pack' and the letter 'H' stands for this hook.
+
+ # Version and features negotiation.
+ S: PKT-LINE(version=1\0push-options atomic...)
+ S: flush-pkt
+ H: PKT-LINE(version=1\0push-options...)
+ H: flush-pkt
+
+ # Send commands from server to the hook.
+ S: PKT-LINE(<old-oid> <new-oid> <ref>)
+ S: ... ...
+ S: flush-pkt
+ # Send push-options only if the 'push-options' feature is enabled.
+ S: PKT-LINE(push-option)
+ S: ... ...
+ S: flush-pkt
+
+ # Receive result from the hook.
+ # OK, run this command successfully.
+ H: PKT-LINE(ok <ref>)
+ # NO, I reject it.
+ H: PKT-LINE(ng <ref> <reason>)
+ # Fall through, let 'receive-pack' to execute it.
+ H: PKT-LINE(ft <ref>)
+ # OK, but has an alternate reference. The alternate reference name
+ # is given in the third parameter, and other status can be given in
+ # key-value pairs.
+ H: PKT-LINE(alt <ref> <alt-ref> old-oid=<old-oid> new-oid=<new-oid>
+ forced-update)
+ H: ... ...
+ H: flush-pkt
+
+Each command for the 'proc-receive' hook may point to a pseudo-reference
+and always has a zero-old as its old-oid, while the 'proc-receive' hook
+may update an alternate reference and the alternate reference may exist
+already with a non-zero old-oid. For this case, this hook may return
+different OID and different reference name as extended status of the
+report line.
+
+The report of the commands of this hook should have the same order as
+the input. The exit status of the 'proc-receive' hook only determines
+the success or failure of the group of commands sent to it, unless
+atomic push is in use.
+
[[post-receive]]
post-receive
~~~~~~~~~~~~
--
2.24.1.15.g448c31058d.agit.4.5
Jiang Xin <worldhello.net@gmail.com>