development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-09-12 21:04:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: add document for capability report-status-v2

Browse source 
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>
This commit is contained in:
Jiang Xin 2020-08-27 11:45:47 -04:00 committed by Junio C Hamano
parent 63518a574a
commit b913075cb8
2 changed files with 52 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
Documentation/technical/pack-protocol.txt
View file

@ -503,8 +503,8 @@ The reference discovery phase is done nearly the same way as it is in the
fetching protocol. Each reference obj-id and name on the server is sent fetching protocol. Each reference obj-id and name on the server is sent
in packet-line format to the client, followed by a flush-pkt. The only in packet-line format to the client, followed by a flush-pkt. The only
real difference is that the capability listing is different - the only real difference is that the capability listing is different - the only
possible values are 'report-status', 'delete-refs', 'ofs-delta' and possible values are 'report-status', 'report-status-v2', 'delete-refs',
'push-options'. 'ofs-delta', 'atomic' and 'push-options'.
Reference Update Request and Packfile Transfer Reference Update Request and Packfile Transfer
---------------------------------------------- ----------------------------------------------
@ -625,7 +625,7 @@ Report Status
------------- -------------
After receiving the pack data from the sender, the receiver sends a After receiving the pack data from the sender, the receiver sends a
report if 'report-status' capability is in effect. report if 'report-status' or 'report-status-v2' capability is in effect.
It is a short listing of what happened in that update. It will first It is a short listing of what happened in that update. It will first
list the status of the packfile unpacking as either 'unpack ok' or list the status of the packfile unpacking as either 'unpack ok' or
'unpack [error]'. Then it will list the status for each of the references '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.
error-msg = 1*(OCTET) ; where not "ok" error-msg = 1*(OCTET) ; where not "ok"
---- ----
The 'report-status-v2' capability extends the protocol by adding new option
lines in order to support reporting of reference rewritten by the
'proc-receive' hook. The 'proc-receive' hook may handle a command for a
pseudo-reference which may create or update one or more references, and each
reference may have different name, different new-oid, and different old-oid.
----
report-status-v2 = unpack-status
1*(command-status-v2)
flush-pkt
unpack-status = PKT-LINE("unpack" SP unpack-result)
unpack-result = "ok" / error-msg
command-status-v2 = command-ok-v2 / command-fail
command-ok-v2 = command-ok
*option-line
command-ok = PKT-LINE("ok" SP refname)
command-fail = PKT-LINE("ng" SP refname SP error-msg)
error-msg = 1*(OCTET) ; where not "ok"
option-line = *1(option-refname)
*1(option-old-oid)
*1(option-new-oid)
*1(option-forced-update)
option-refname = PKT-LINE("option" SP "refname" SP refname)
option-old-oid = PKT-LINE("option" SP "old-oid" SP obj-id)
option-new-oid = PKT-LINE("option" SP "new-oid" SP obj-id)
option-force = PKT-LINE("option" SP "forced-update")
----
Updates can be unsuccessful for a number of reasons. The reference can have Updates can be unsuccessful for a number of reasons. The reference can have
changed since the reference discovery phase was originally sent, meaning changed since the reference discovery phase was originally sent, meaning
someone pushed in the meantime. The reference being pushed could be a someone pushed in the meantime. The reference being pushed could be a

17
Documentation/technical/protocol-capabilities.txt
View file

@ -22,9 +22,9 @@ was sent. Server MUST NOT ignore capabilities that client requested
and server advertised. As a consequence of these rules, server MUST and server advertised. As a consequence of these rules, server MUST
NOT advertise capabilities it does not understand. NOT advertise capabilities it does not understand.
The 'atomic', 'report-status', 'delete-refs', 'quiet', and 'push-cert' The 'atomic', 'report-status', 'report-status-v2', 'delete-refs', 'quiet',
capabilities are sent and recognized by the receive-pack (push to server) and 'push-cert' capabilities are sent and recognized by the receive-pack
process. (push to server) process.
The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
by both upload-pack and receive-pack protocols. The 'agent' capability 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
successful, it will send back an error message. See pack-protocol.txt successful, it will send back an error message. See pack-protocol.txt
for example messages. for example messages.
report-status-v2
----------------
Capability 'report-status-v2' extends capability 'report-status' by
adding new "option" directives in order to support reference rewritten by
the "proc-receive" hook. The "proc-receive" hook may handle a command
for a pseudo-reference which may create or update a reference with
different name, new-oid, and old-oid. While the capability
'report-status' cannot report for such case. See pack-protocol.txt
for details.
delete-refs delete-refs
----------- -----------