doc: add document for capability report-status-v2
Add ABNF notation for capability 'report-status-v2' which extends capability 'report-status' by adding additional option lines. 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
b913075cb8bd55a6c2ecac4aa7af0de6fb98d5b6
2 files changed
+52
-6
Documentation/technical/pack-protocol.txt
+38
-3
@@ -503,8 +503,8 @@ The reference discovery phase is done nearly the same way as it is in the
503
fetching protocol. Each reference obj-id and name on the server is sent
504
in packet-line format to the client, followed by a flush-pkt. The only
505
real difference is that the capability listing is different - the only
506
-possible values are 'report-status', 'delete-refs', 'ofs-delta' and
507
-'push-options'.
506
+possible values are 'report-status', 'report-status-v2', 'delete-refs',
507
+'ofs-delta', 'atomic' and 'push-options'.
508
509
Reference Update Request and Packfile Transfer
510
----------------------------------------------
@@ -625,7 +625,7 @@ Report Status
625
-------------
626
627
After receiving the pack data from the sender, the receiver sends a
628
-report if 'report-status' capability is in effect.
628
+report if 'report-status' or 'report-status-v2' capability is in effect.
629
It is a short listing of what happened in that update. It will first
630
list the status of the packfile unpacking as either 'unpack ok' or
631
'unpack [error]'. Then it will list the status for each of the references
@@ -647,6 +647,41 @@ update was successful, or 'ng [refname] [error]' if the update was not.
647
error-msg = 1*(OCTET) ; where not "ok"
648
----
649
650
+The 'report-status-v2' capability extends the protocol by adding new option
651
+lines in order to support reporting of reference rewritten by the
652
+'proc-receive' hook. The 'proc-receive' hook may handle a command for a
653
+pseudo-reference which may create or update one or more references, and each
654
+reference may have different name, different new-oid, and different old-oid.
655
+
656
+----
657
+ report-status-v2 = unpack-status
658
+ 1*(command-status-v2)
659
+ flush-pkt
660
+
661
+ unpack-status = PKT-LINE("unpack" SP unpack-result)
662
+ unpack-result = "ok" / error-msg
663
+
664
+ command-status-v2 = command-ok-v2 / command-fail
665
+ command-ok-v2 = command-ok
666
+ *option-line
667
+
668
+ command-ok = PKT-LINE("ok" SP refname)
669
+ command-fail = PKT-LINE("ng" SP refname SP error-msg)
670
+
671
+ error-msg = 1*(OCTET) ; where not "ok"
672
+
673
+ option-line = *1(option-refname)
674
+ *1(option-old-oid)
675
+ *1(option-new-oid)
676
+ *1(option-forced-update)
677
+
678
+ option-refname = PKT-LINE("option" SP "refname" SP refname)
679
+ option-old-oid = PKT-LINE("option" SP "old-oid" SP obj-id)
680
+ option-new-oid = PKT-LINE("option" SP "new-oid" SP obj-id)
681
+ option-force = PKT-LINE("option" SP "forced-update")
682
+
683
+----
684
+
685
Updates can be unsuccessful for a number of reasons. The reference can have
686
changed since the reference discovery phase was originally sent, meaning
687
someone pushed in the meantime. The reference being pushed could be a
Documentation/technical/protocol-capabilities.txt
+14
-3
@@ -22,9 +22,9 @@ was sent. Server MUST NOT ignore capabilities that client requested
22
and server advertised. As a consequence of these rules, server MUST
23
NOT advertise capabilities it does not understand.
24
25
-The 'atomic', 'report-status', 'delete-refs', 'quiet', and 'push-cert'
26
-capabilities are sent and recognized by the receive-pack (push to server)
27
-process.
25
+The 'atomic', 'report-status', 'report-status-v2', 'delete-refs', 'quiet',
26
+and 'push-cert' capabilities are sent and recognized by the receive-pack
27
+(push to server) process.
28
29
The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
30
by both upload-pack and receive-pack protocols. The 'agent' capability
@@ -269,6 +269,17 @@ each reference was updated successfully. If any of those were not
269
successful, it will send back an error message. See pack-protocol.txt
270
for example messages.
271
272
+report-status-v2
273
+----------------
274
+
275
+Capability 'report-status-v2' extends capability 'report-status' by
276
+adding new "option" directives in order to support reference rewritten by
277
+the "proc-receive" hook. The "proc-receive" hook may handle a command
278
+for a pseudo-reference which may create or update a reference with
279
+different name, new-oid, and old-oid. While the capability
280
+'report-status' cannot report for such case. See pack-protocol.txt
281
+for details.
282
+
283
delete-refs
284
-----------
285