development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-10-06 00:29:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: add documentation for the proc-receive hook

Browse source 
"git receive-pack" that accepts requests by "git push" learned to
outsource some of the ref updates to the new "proc-receive" hook.

Signed-off-by: Jiang Xin <zhiyou.jx@alibaba-inc.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jiang Xin 2020-08-27 11:45:51 -04:00 committed by Junio C Hamano
parent 1702ae6f61
commit d6edc189f6
1 changed files with 62 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
Documentation/githooks.txt
View file

@ -333,6 +333,68 @@ 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]. 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(ok <ref>)
H: PKT-LINE(option fall-through)
# OK, but has an alternate reference. The alternate reference name
# and other status can be given in option directives.
H: PKT-LINE(ok <ref>)
H: PKT-LINE(option refname <refname>)
H: PKT-LINE(option old-oid <old-oid>)
H: PKT-LINE(option new-oid <new-oid>)
H: PKT-LINE(option 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 will use
"option" directives to report extended attributes for the reference given
by the leading "ok" directive.
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
~~~~~~~~~~~~