doc: add documentation for the proc-receive hook
"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>
Jiang Xin committed
Aug 27, 2020 at 11:45 UTC
d6edc189f6b3d8606150a52fd2c2fcd781b8550f
1 file changed
+62
Documentation/githooks.txt
+62
@@ -333,6 +333,68 @@ The default 'update' hook, when enabled--and with
333
`hooks.allowunannotated` config option unset or set to false--prevents
334
unannotated tags to be pushed.
335
336
+[[proc-receive]]
337
+proc-receive
338
+~~~~~~~~~~~~
339
+
340
+This hook is invoked by linkgit:git-receive-pack[1]. If the server has
341
+set the multi-valued config variable `receive.procReceiveRefs`, and the
342
+commands sent to 'receive-pack' have matching reference names, these
343
+commands will be executed by this hook, instead of by the internal
344
+`execute_commands()` function. This hook is responsible for updating
345
+the relevant references and reporting the results back to 'receive-pack'.
346
+
347
+This hook executes once for the receive operation. It takes no
348
+arguments, but uses a pkt-line format protocol to communicate with
349
+'receive-pack' to read commands, push-options and send results. In the
350
+following example for the protocol, the letter 'S' stands for
351
+'receive-pack' and the letter 'H' stands for this hook.
352
+
353
+ # Version and features negotiation.
354
+ S: PKT-LINE(version=1\0push-options atomic...)
355
+ S: flush-pkt
356
+ H: PKT-LINE(version=1\0push-options...)
357
+ H: flush-pkt
358
+
359
+ # Send commands from server to the hook.
360
+ S: PKT-LINE(<old-oid> <new-oid> <ref>)
361
+ S: ... ...
362
+ S: flush-pkt
363
+ # Send push-options only if the 'push-options' feature is enabled.
364
+ S: PKT-LINE(push-option)
365
+ S: ... ...
366
+ S: flush-pkt
367
+
368
+ # Receive result from the hook.
369
+ # OK, run this command successfully.
370
+ H: PKT-LINE(ok <ref>)
371
+ # NO, I reject it.
372
+ H: PKT-LINE(ng <ref> <reason>)
373
+ # Fall through, let 'receive-pack' to execute it.
374
+ H: PKT-LINE(ok <ref>)
375
+ H: PKT-LINE(option fall-through)
376
+ # OK, but has an alternate reference. The alternate reference name
377
+ # and other status can be given in option directives.
378
+ H: PKT-LINE(ok <ref>)
379
+ H: PKT-LINE(option refname <refname>)
380
+ H: PKT-LINE(option old-oid <old-oid>)
381
+ H: PKT-LINE(option new-oid <new-oid>)
382
+ H: PKT-LINE(option forced-update)
383
+ H: ... ...
384
+ H: flush-pkt
385
+
386
+Each command for the 'proc-receive' hook may point to a pseudo-reference
387
+and always has a zero-old as its old-oid, while the 'proc-receive' hook
388
+may update an alternate reference and the alternate reference may exist
389
+already with a non-zero old-oid. For this case, this hook will use
390
+"option" directives to report extended attributes for the reference given
391
+by the leading "ok" directive.
392
+
393
+The report of the commands of this hook should have the same order as
394
+the input. The exit status of the 'proc-receive' hook only determines
395
+the success or failure of the group of commands sent to it, unless
396
+atomic push is in use.
397
+
398
[[post-receive]]
399
post-receive
400
~~~~~~~~~~~~