From: Jiang Xin <zhiyou.jx@xxxxxxxxxxxxxxx> Add documentation for the new "proc-receive" hook. Signed-off-by: Jiang Xin <zhiyou.jx@xxxxxxxxxxxxxxx> --- Documentation/githooks.txt | 70 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 3dccab5375..10ea5c1f18 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -333,6 +333,76 @@ 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]] +proc-receive +~~~~~~~~~~~~ +This hook is invoked by linkgit:git-receive-pack[1] when it reacts to +special `git push` command. According to refnames of the commands which +`git push` sends to 'git-receive-pack', the commands will be devided +into two groups by matching what the `receive.procReceiveRefs` +configuration variable defines. One group of the commands will execute +the internal `execute_commands` function to update the corresponding +refnames, and the other group of commands which have matching refnames +will execute this 'proc-receive' hook to create pull requests, etc. +If there is no `receive.procReceiveRefs` settings, this hook won't +execute at all, and all commands are sent to the internal +`execute_commands` function. + +Its exit status only determines the success or failure of the group of +commands with special refnames, unless atomic push is in use. + +This hook executes once for the receive operation. It takes no +arguments, but will talk a protocol in pkt-line format with the +'receive-pack' for reading commands, push-options (optional), and +sending result. In the following example, The letter "S" stands for +"receive-pack" and letter "H" stands for the hook. + + # Version and capabilities 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 + # Only if push-options have been negotiated. + S: PKT-LINE(push-option) + S: ... ... + S: flush-pkt + + # Receive result from the hook. + # OK, run this command successfully. + H: PKT-LINE(old-oid new-oid ref ok) + # NO, I reject it. + H: PKT-LINE(old-oid new-oid ref ng reason) + # OK, but use an alternate reference. + H: PKT-LINE(old-oid new-oid ref ok ref:alt-ref) + # It will fallthrough to receive-pack to execute. + H: PKT-LINE(old-oid new-oid ref ft) + H: ... ... + H: flush-pkt + +The "proc-receive" hook may update one or more references, and will send +its result one by one in pkt-line format. Each line of the result has +four fields and one optional message field, like "<old-oid> <new-oid> +<ref> <status> [<message>]". + +The first three fields are the same as those of the commands for +"receive-pack". + +The forth field has a two-letter status code. Available status codes: + +* ok: The command runs successfully. If the optional message has a + prefix "ref:", the hook has created/updated an alternate reference + instead. + +* ng: Fail to run the command. Error message is given in the optional + message field. + +* ft: Will fallthrough to receive-pack to execute. + [[post-receive]] post-receive ~~~~~~~~~~~~ -- 2.24.1.15.g448c31058d.agit.4.5
