git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[RFCv2 16/16] Document protocol version 2

From
Stefan Beller <sbeller@google.com>
Date
Jun 2, 2015, 00:02 UTC
Message-ID
<1433203338-27493-17-git-send-email-sbeller@google.com>
In-Reply-To
<1433203338-27493-1-git-send-email-sbeller@google.com>
Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/technical/pack-protocol.txt         | 79 +++++++++++++++++++++--
 Documentation/technical/protocol-capabilities.txt | 15 -----
 2 files changed, 74 insertions(+), 20 deletions(-)
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 4064fc7..88bb30a 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -14,6 +14,12 @@ data.  The protocol functions to have a server tell a client what is
 currently on the server, then for the two to negotiate the smallest amount
 of data to send in order to fully update one or the other.
 
+"upload-pack-2" and "receive-pack-2" are the next generation of
+"upload-pack" and "receive-pack" respectively. The first two are
+referred as "version 2" in this document and pack-capabilities.txt
+while the last two are "version 1". Unless stated otherwise, "version 1"
+is implied.
+
 Transports
 ----------
 There are three transports over which the packfile protocol is
@@ -42,7 +48,8 @@ hostname parameter, terminated by a NUL byte.
 
 --
    git-proto-request = request-command SP pathname NUL [ host-parameter NUL ]
-   request-command   = "git-upload-pack" / "git-receive-pack" /
+   request-command   = "git-upload-pack" / "git-upload-pack-2" /
+		       "git-receive-pack" / "git-receive-pack-2" /
 		       "git-upload-archive"   ; case sensitive
    pathname          = *( %x01-ff ) ; exclude NUL
    host-parameter    = "host=" hostname [ ":" port ]
@@ -124,6 +131,49 @@ has, the first can 'fetch' from the second.  This operation determines
 what data the server has that the client does not then streams that
 data down to the client in packfile format.
 
+Capability discovery (v2)
+-------------------------
+
+In version 1, capability discovery is part of reference discovery and
+covered in the reference discovery section.
+
+In version 2, when the client initially connects, the server
+immediately sends its capabilities to the client followed by a flush.
+Then the client must send the list of server capabilities it wants to
+use to the server.
+
+   S: 00XXlang\n
+   S: 00XXthin-pack\n
+   S: 00XXofs-delta\n
+   S: 00XXagent:agent=git/2:3.4.5+custom-739-gb850f98\n
+   S: 0000
+
+   C: 00XXthin-pack\n
+   C: 00XXofs-delta\n
+   C: 00XXlang=en\n
+   C: 00XXagent:agent=git/custom_string\n
+   C: 0000
+
+----
+  capability-list  =  *(capability) flush-pkt
+  capability       =  PKT-LINE(keyvaluepair LF)
+  keyvaluepair     = key ["=" value]
+  key              =  1*(LC_ALPHA / DIGIT / "-" / "_")
+  LC_ALPHA         =  %x61-7A
+  value            = any octet
+
+----
+
+The client MUST ignore any data on pkt-lines with unknown keys.
+
+The client MUST NOT ask for capabilities the server did not say it
+supports. The server MUST diagnose and abort if capabilities it does
+not understand was requested. The server MUST NOT ignore capabilities
+that client requested and server advertised.  As a consequence of these
+rules, server MUST NOT advertise capabilities it does not understand.
+
+See protocol-capabilities.txt for a list of allowed server and client
+capabilities and descriptions.
 
 Reference Discovery
 -------------------
@@ -154,10 +204,14 @@ If HEAD is a valid ref, HEAD MUST appear as the first advertised
 ref.  If HEAD is not a valid ref, HEAD MUST NOT appear in the
 advertisement list at all, but other refs may still appear.
 
-The stream MUST include capability declarations behind a NUL on the
-first ref. The peeled value of a ref (that is "ref^{}") MUST be
-immediately after the ref itself, if presented. A conforming server
-MUST peel the ref if it's an annotated tag.
+In version 1 the stream MUST include capability declarations behind
+a NUL on the first ref. The peeled value of a ref (that is "ref^{}")
+MUST be immediately after the ref itself, if presented. A conforming
+server MUST peel the ref if it's an annotated tag.
+
+In version 2 the capabilities are already negotiated, so the first ref
+MUST NOT be followed by any capability advertisement, but it should be
+treated as any other refs advertising line.
 
 ----
   advertised-refs  =  (no-refs / list-of-refs)
@@ -185,6 +239,21 @@ MUST peel the ref if it's an annotated tag.
 Server and client MUST use lowercase for obj-id, both MUST treat obj-id
 as case-insensitive.
 
+On the very first line of the initial server response of either
+receive-pack and upload-pack the first reference is followed by
+a NUL byte and then a list of space delimited server capabilities.
+These allow the server to declare what it can and cannot support
+to the client.
+
+Client will then send a space separated list of capabilities it wants
+to be in effect. The client MUST NOT ask for capabilities the server
+did not say it supports.
+
+Server MUST diagnose and abort if capabilities it does not understand
+was sent.  Server MUST NOT ignore capabilities that client requested
+and server advertised.  As a consequence of these rules, server MUST
+NOT advertise capabilities it does not understand.
+
 See protocol-capabilities.txt for a list of allowed server capabilities
 and descriptions.
 
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index 4f8a7bf..a6241d8 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -3,21 +3,6 @@ Git Protocol Capabilities
 
 Servers SHOULD support all capabilities defined in this document.
 
-On the very first line of the initial server response of either
-receive-pack and upload-pack the first reference is followed by
-a NUL byte and then a list of space delimited server capabilities.
-These allow the server to declare what it can and cannot support
-to the client.
-
-Client will then send a space separated list of capabilities it wants
-to be in effect. The client MUST NOT ask for capabilities the server
-did not say it supports.
-
-Server MUST diagnose and abort if capabilities it does not understand
-was sent.  Server MUST NOT ignore capabilities that client requested
-and server advertised.  As a consequence of these rules, server MUST
-NOT advertise capabilities it does not understand.
-
 The 'atomic', 'report-status', 'delete-refs', 'quiet', and 'push-cert'
 capabilities are sent and recognized by the receive-pack (push to server)
 process.

-- 
2.4.1.345.gab207b6.dirty
Previous: Junio C Hamano
Message 44 of 44 in “[RFCv2 00/16] Protocol version 2”
  1. Stefan BellerJun 2, 2015
  2. 01/16 stringlist: add from_space_separated_stringStefan Beller, Jun 2, 2015
  3. Duy NguyenJun 2, 2015
  4. Eric SunshineJun 2, 2015
  5. Stefan BellerJun 2, 2015
  6. 02/16 upload-pack: make client capability parsing code a separate functionStefan Beller, Jun 2, 2015
  7. 03/16 connect: rewrite feature parsing to work on string_listStefan Beller, Jun 2, 2015
  8. Junio C HamanoJun 2, 2015
  9. 04/16 upload-pack-2: Implement the version 2 of upload-packStefan Beller, Jun 2, 2015
  10. Junio C HamanoJun 2, 2015
  11. Stefan BellerJun 2, 2015
  12. 05/16 remote.h: Change get_remote_heads return to voidStefan Beller, Jun 2, 2015
  13. Junio C HamanoJun 2, 2015
  14. Stefan BellerJun 2, 2015
  15. Junio C HamanoJun 2, 2015
  16. 06/16 remote.h: add new struct for optionsStefan Beller, Jun 2, 2015
  17. Junio C HamanoJun 2, 2015
  18. Stefan BellerJun 2, 2015
  19. Junio C HamanoJun 2, 2015
  20. 07/16 transport: add infrastructure to support a protocol version numberStefan Beller, Jun 2, 2015
  21. 08/16 transport: select transport version via command line or configStefan Beller, Jun 2, 2015
  22. 09/16 remote.h: add get_remote_capabilities, request_capabilitiesStefan Beller, Jun 2, 2015
  23. Junio C HamanoJun 2, 2015
  24. 10/16 transport: connect_setup appends protocol version numberStefan Beller, Jun 2, 2015
  25. Duy NguyenJun 2, 2015
  26. Stefan BellerJun 2, 2015
  27. Junio C HamanoJun 2, 2015
  28. Stefan BellerJun 2, 2015
  29. Junio C HamanoJun 2, 2015
  30. 11/16 remote: have preselect_capabilitiesStefan Beller, Jun 2, 2015
  31. Junio C HamanoJun 2, 2015
  32. 12/16 transport: get_refs_via_connect exchanges capabilities before refs.Stefan Beller, Jun 2, 2015
  33. Junio C HamanoJun 2, 2015
  34. Stefan BellerJun 2, 2015
  35. 13/16 fetch-pack: use the configured transport protocolStefan Beller, Jun 2, 2015
  36. Duy NguyenJun 2, 2015
  37. Duy NguyenJun 2, 2015
  38. Ilari LiusvaaraJun 2, 2015
  39. 14/16 t5544: add a test case for the new protocolStefan Beller, Jun 2, 2015
  40. Eric SunshineJun 3, 2015
  41. 15/16 Documentation/technical/pack-protocol: Mention http as possible protocolStefan Beller, Jun 2, 2015
  42. Junio C HamanoJun 2, 2015
  43. Junio C HamanoJun 2, 2015
  44. 16/16 Document protocol version 2Stefan Beller, Jun 2, 2015

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.