Git Mailing List Archive on lore.kernel.org
 help / color / Atom feed
From: Jiang Xin <worldhello.net@gmail.com>
To: Junio C Hamano <gitster@pobox.com>, Git List <git@vger.kernel.org>
Cc: Jiang Xin <zhiyou.jx@alibaba-inc.com>
Subject: [PATCH v10 8/8] doc: add documentation for the proc-receive hook
Date: Sun, 12 Apr 2020 09:30:22 -0400
Message-ID: <20200412133022.17590-9-worldhello.net@gmail.com> (raw)
In-Reply-To: <20200407120813.25025-1-worldhello.net@gmail.com>

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..1c528e2fc4 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(<old-oid> <new-oid> <ref> ok)
+    # NO, I reject it.
+    H: PKT-LINE(<old-oid> <new-oid> <ref> ng <reason>)
+    # Fall through, let 'receive-pack' to execute it.
+    H: PKT-LINE(<old-oid> <new-oid> <ref> ft)
+    # OK, but has an alternate reference.  The alternate reference name
+    # and other status are given in key=value pairs after the null
+    # character.
+    H: PKT-LINE(<old-oid> <new-oid> <ref> ok\0ref=refs/pull/123/head
+                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


  parent reply index

Thread overview: 182+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-03-04 11:33 [PATCH 0/7] New execute-commands hook for centralized workflow Jiang Xin
2020-03-04 11:33 ` [PATCH 1/7] receive-pack: new external execute-commands hook Jiang Xin
2020-03-04 11:33 ` [PATCH 2/7] receive-pack: feed all commands to post-receive Jiang Xin
2020-03-04 11:33 ` [PATCH 3/7] receive-pack: try `execute-commands --pre-receive` Jiang Xin
2020-03-04 11:33 ` [PATCH 4/7] receive-pack: read env from execute-commands output Jiang Xin
2020-03-04 11:33 ` [PATCH 5/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-03-04 11:33 ` [PATCH 6/7] receive-pack: new config receive.executeCommandsHookRefs Jiang Xin
2020-03-04 11:33 ` [PATCH 7/7] hook: add document and example for "execute-commands" hook Jiang Xin
2020-03-04 20:39 ` [PATCH 0/7] New execute-commands hook for centralized workflow Junio C Hamano
2020-03-05 16:51   ` Jiang Xin
2020-03-08 14:56     ` [PATCH v2 0/5] New proc-receive " Jiang Xin
2020-03-08 14:56     ` [PATCH v2 1/5] receive-pack: add new proc-receive hook Jiang Xin
2020-03-09 17:12       ` Junio C Hamano
2020-03-10  6:03         ` Jiang Xin
2020-03-13 12:23           ` [PATCH v3 0/4] New proc-receive hook for centralized workflow Jiang Xin
2020-03-22 13:18             ` [PATCH v4 0/5] " Jiang Xin
2020-03-25  5:19               ` Junio C Hamano
2020-03-22 13:18             ` [PATCH v4 1/5] transport: not report a non-head push as a branch Jiang Xin
2020-03-25  6:04               ` Junio C Hamano
2020-03-22 13:18             ` [PATCH v4 2/5] receive-pack: add new proc-receive hook Jiang Xin
2020-03-25 14:36               ` [PATCH 0/3] Never report references we not push Jiang Xin
2020-03-29 14:33                 ` [PATCH v2 0/4] " Jiang Xin
2020-03-29 14:35                   ` Jiang Xin
2020-04-16 16:24                   ` [PATCH v3 0/5] fix git-push porcelain output and atomic report issue Jiang Xin
2020-04-17  9:45                     ` [PATCH v4 " Jiang Xin
2020-04-17  9:45                     ` [PATCH v4 1/5] send-pack: fix inconsistent porcelain output Jiang Xin
2020-04-17 19:51                       ` Junio C Hamano
2020-04-17  9:45                     ` [PATCH v4 2/5] t5543: never report what we do not push Jiang Xin
2020-04-17  9:45                     ` [PATCH v4 3/5] send-pack: mark failure of atomic push properly Jiang Xin
2020-04-17  9:45                     ` [PATCH v4 4/5] transport-helper: mark failure for atomic push Jiang Xin
2020-04-17  9:45                     ` [PATCH v4 5/5] transport-helper: new method reject_atomic_push() Jiang Xin
2020-04-16 16:24                   ` [PATCH v3 1/5] send-pack: fix inconsistent porcelain output Jiang Xin
2020-04-16 16:24                   ` [PATCH v3 2/5] t5543: never report what we do not push Jiang Xin
2020-04-16 16:24                   ` [PATCH v3 3/5] send-pack: mark failure of atomic push properly Jiang Xin
2020-04-16 16:24                   ` [PATCH v3 4/5] transport-helper: mark failure for atomic push Jiang Xin
2020-04-16 16:24                   ` [PATCH v3 5/5] transport-helper: new method reject_atomic_push() Jiang Xin
2020-03-29 14:33                 ` [PATCH v2 1/4] t5543: never report what we do not push Jiang Xin
2020-03-29 14:33                 ` [PATCH v2 2/4] send-pack: mark failure of atomic push properly Jiang Xin
2020-03-29 14:33                 ` [PATCH v2 3/4] transport-helper: mark failure for atomic push Jiang Xin
2020-03-29 14:33                 ` [PATCH v2 4/4] transport-helper: new method reject_atomic_push() Jiang Xin
2020-03-25 14:36               ` [PATCH 1/3] t5543: never report what we do not push Jiang Xin
2020-03-25 15:05                 ` Junio C Hamano
2020-03-26  2:25                   ` Jiang Xin
2020-03-25 14:36               ` [PATCH 2/3] send-pack: mark failure of atomic push properly Jiang Xin
2020-03-25 15:15                 ` Junio C Hamano
2020-03-25 14:36               ` [PATCH 3/3] transport-helper: enforce atomic in push_refs_with_push Jiang Xin
2020-03-25 15:32                 ` Junio C Hamano
2020-03-22 13:18             ` [PATCH v4 3/5] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-03-22 13:18             ` [PATCH v4 4/5] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-03-22 13:18             ` [PATCH v4 5/5] receive-pack: refactor report for proc-receive Jiang Xin
2020-03-13 12:23           ` [PATCH v3 1/4] receive-pack: add new proc-receive hook Jiang Xin
2020-03-13 12:23           ` [PATCH v3 2/4] receive-pack: refactor report for proc-receive Jiang Xin
2020-03-13 12:23           ` [PATCH v3 3/4] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-03-13 12:23           ` [PATCH v3 4/4] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-03-08 14:56     ` [PATCH v2 2/5] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-03-08 15:38     ` [PATCH v2 3/5] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-03-08 15:38     ` [PATCH v2 4/5] receive-pack: read env from proc-receive output Jiang Xin
2020-03-08 15:38     ` [PATCH v2 5/5] hook: add document and example for "proc-receive" hook Jiang Xin
2020-03-30 16:57 ` [PATCH v5 0/6] New proc-receive hook for centralized workflow Jiang Xin
2020-03-30 16:57 ` [PATCH v5 1/6] transport: not report a non-head push as a branch Jiang Xin
2020-03-30 16:57 ` [PATCH v5 2/6] receive-pack: add new proc-receive hook Jiang Xin
2020-03-31  0:19   ` Junio C Hamano
2020-03-31  0:21   ` Junio C Hamano
2020-03-30 16:57 ` [PATCH v5 3/6] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-03-30 16:57 ` [PATCH v5 4/6] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-03-30 16:57 ` [PATCH v5 5/6] receive-pack: refactor report for proc-receive Jiang Xin
2020-03-30 16:57 ` [PATCH v5 6/6] doc: add documentation for the proc-receive hook Jiang Xin
2020-04-02 16:35 ` [PATCH v6 0/7] New proc-receive hook for centralized workflow Jiang Xin
2020-04-02 18:26   ` Junio C Hamano
2020-04-03 16:08     ` [PATCH v7 " Jiang Xin
2020-04-04 13:43       ` [PATCH v8 " Jiang Xin
2020-04-07 12:08         ` [PATCH v9 0/6] " Jiang Xin
2020-04-12 13:30           ` [PATCH v10 0/8] " Jiang Xin
2020-04-13 16:48             ` [PATCH v11 0/7] " Jiang Xin
2020-04-13 16:48             ` [PATCH v11 1/7] transport: not report a non-head push as a branch Jiang Xin
2020-04-13 16:48             ` [PATCH v11 2/7] connect: export parse_feature_value() Jiang Xin
2020-04-13 16:48             ` [PATCH v11 3/7] receive-pack: add new proc-receive hook Jiang Xin
2020-04-13 16:48             ` [PATCH v11 4/7] send-pack: extension for client-side status report Jiang Xin
2020-04-13 16:48             ` [PATCH v11 5/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-13 16:48             ` [PATCH v11 6/7] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-13 16:48             ` [PATCH v11 7/7] doc: add documentation for the proc-receive hook Jiang Xin
2020-04-12 13:30           ` [PATCH v10 1/8] transport: not report a non-head push as a branch Jiang Xin
2020-04-12 20:26             ` Junio C Hamano
2020-04-13 11:15               ` Jiang Xin
2020-04-12 13:30           ` [PATCH v10 2/8] receive-pack: add new proc-receive hook Jiang Xin
2020-04-12 21:30             ` Junio C Hamano
2020-04-13 10:58               ` Jiang Xin
2020-04-13 21:50                 ` Junio C Hamano
2020-04-14 12:32                   ` [PATCH v12 0/7] New proc-receive hook for centralized workflow Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 0/8] " Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 1/8] transport: not report a non-head push as a branch Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 2/8] connect: export parse_feature_value() Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 3/8] receive-pack: add new proc-receive hook Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 4/8] send-pack: extension for client-side status report Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 5/8] receive-pack: feed extended_status to post-receive Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 6/8] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 7/8] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-18 16:03                     ` [PATCH v13 8/8] doc: add documentation for the proc-receive hook Jiang Xin
2020-04-14 12:32                   ` [PATCH v12 1/7] transport: not report a non-head push as a branch Jiang Xin
2020-04-14 12:32                   ` [PATCH v12 2/7] connect: export parse_feature_value() Jiang Xin
2020-04-14 12:32                   ` [PATCH v12 3/7] receive-pack: add new proc-receive hook Jiang Xin
2020-04-15 15:48                     ` Junio C Hamano
2020-04-15 15:55                       ` Jiang Xin
2020-04-15 18:34                         ` Junio C Hamano
2020-04-27 17:00                           ` Jiang Xin
2020-04-29  7:56                             ` Jeff King
2020-04-30 15:33                               ` Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 0/7] New proc-receive hook for centralized workflow Jiang Xin
2020-05-06 23:14                                   ` Junio C Hamano
2020-05-07  1:37                                     ` Jiang Xin
2020-05-07 11:18                                       ` Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 " Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 00/11] " Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 01/11] transport: not report a non-head push as a branch Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 02/11] t5411: add basic test cases for proc-receive hook Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 03/11] receive-pack: add new " Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 04/11] New capability "report-status-v2" for git-push Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 05/11] doc: add document for capability report-status-v2 Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 06/11] receive-pack: feed report options to post-receive Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 07/11] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 08/11] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 09/11] t5411: test updates of remote-tracking branches Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 10/11] transport: parse report options for tracking refs Jiang Xin
2020-05-18  9:40                                       ` [PATCH v16 11/11] doc: add documentation for the proc-receive hook Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 1/7] transport: not report a non-head push as a branch Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 2/7] receive-pack: add new proc-receive hook Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 3/7] New capability "report-status-v2" for git-push Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 4/7] receive-pack: feed report options to post-receive Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 5/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 6/7] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-05-07 16:10                                     ` [PATCH v15 7/7] doc: add documentation for the proc-receive hook Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 1/7] transport: not report a non-head push as a branch Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 2/7] receive-pack: add new proc-receive hook Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 3/7] New capability "report-status-v2" for git-push Jiang Xin
2020-05-05 15:25                                   ` [PATCH v14 8/7] fixup! " Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 4/7] receive-pack: feed report options to post-receive Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 5/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 6/7] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-05-05 14:41                                 ` [PATCH v14 7/7] doc: add documentation for the proc-receive hook Jiang Xin
2020-05-07 17:27                                 ` [PATCH v12 3/7] receive-pack: add new " Jeff King
2020-04-14 12:32                   ` [PATCH v12 4/7] send-pack: extension for client-side status report Jiang Xin
2020-04-15 20:36                     ` Junio C Hamano
2020-04-14 12:32                   ` [PATCH v12 5/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-14 12:32                   ` [PATCH v12 6/7] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-14 12:32                   ` [PATCH v12 7/7] doc: add documentation for the proc-receive hook Jiang Xin
2020-04-12 13:30           ` [PATCH v10 3/8] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-12 21:38             ` Junio C Hamano
2020-04-13 11:16               ` Jiang Xin
2020-04-12 13:30           ` [PATCH v10 4/8] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-12 21:46             ` Junio C Hamano
2020-04-13 11:16               ` Jiang Xin
2020-04-12 13:30           ` [PATCH v10 5/8] connect: export parse_feature_value() Jiang Xin
2020-04-12 13:30           ` [PATCH v10 6/8] receive-pack: extension for server-side report Jiang Xin
2020-04-12 13:30           ` [PATCH v10 7/8] send-pack: extension for client-side status report Jiang Xin
2020-04-12 13:30           ` Jiang Xin [this message]
2020-04-07 12:08         ` [PATCH v9 1/6] transport: not report a non-head push as a branch Jiang Xin
2020-04-07 12:08         ` [PATCH v9 2/6] receive-pack: add new proc-receive hook Jiang Xin
2020-04-07 12:08         ` [PATCH v9 3/6] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-07 12:08         ` [PATCH v9 4/6] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-07 12:08         ` [PATCH v9 5/6] receive-pack: refactor report for proc-receive Jiang Xin
2020-04-07 12:08         ` [PATCH v9 6/6] doc: add documentation for the proc-receive hook Jiang Xin
2020-04-04 13:43       ` [PATCH v8 1/7] transport: not report a non-head push as a branch Jiang Xin
2020-04-04 13:43       ` [PATCH v8 2/7] receive-pack: add new proc-receive hook Jiang Xin
2020-04-04 13:43       ` [PATCH v8 3/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-04 13:43       ` [PATCH v8 4/7] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-04 13:43       ` [PATCH v8 5/7] receive-pack: refactor report for proc-receive Jiang Xin
2020-04-04 13:43       ` [PATCH v8 6/7] t5412: test the proc-receive hook on HTTP protocol Jiang Xin
2020-04-04 13:43       ` [PATCH v8 7/7] doc: add documentation for the proc-receive hook Jiang Xin
2020-04-03 16:08     ` [PATCH v7 1/7] transport: not report a non-head push as a branch Jiang Xin
2020-04-03 16:08     ` [PATCH v7 2/7] receive-pack: add new proc-receive hook Jiang Xin
2020-04-03 16:08     ` [PATCH v7 3/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-03 16:08     ` [PATCH v7 4/7] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-03 16:08     ` [PATCH v7 5/7] receive-pack: refactor report for proc-receive Jiang Xin
2020-04-03 16:08     ` [PATCH v7 6/7] t5412: test proc-receive hook on HTTP protocol Jiang Xin
2020-04-03 16:08     ` [PATCH v7 7/7] doc: add documentation for the proc-receive hook Jiang Xin
2020-04-02 16:35 ` [PATCH v6 1/7] transport: not report a non-head push as a branch Jiang Xin
2020-04-02 16:35 ` [PATCH v6 2/7] receive-pack: add new proc-receive hook Jiang Xin
2020-04-02 16:35 ` [PATCH v6 3/7] refs.c: refactor to reuse ref_is_hidden() Jiang Xin
2020-04-02 16:35 ` [PATCH v6 4/7] receive-pack: new config receive.procReceiveRefs Jiang Xin
2020-04-02 16:35 ` [PATCH v6 5/7] receive-pack: refactor report for proc-receive Jiang Xin
2020-04-02 16:35 ` [PATCH v6 6/7] t5412: test proc-receive hook on HTTP protocol Jiang Xin
2020-04-02 16:35 ` [PATCH v6 7/7] doc: add documentation for the proc-receive hook Jiang Xin

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200412133022.17590-9-worldhello.net@gmail.com \
    --to=worldhello.net@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=zhiyou.jx@alibaba-inc.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Git Mailing List Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/git/0 git/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 git git/ https://lore.kernel.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.git


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git