@@ -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
~~~~~~~~~~~~