[PATCH v2] protocol-capabilities.txt: document symref

From

Josh Steadmon <steadmon@google.com>

Date

Feb 13, 2019, 23:41 UTC

Message-ID

<cb1b2834b7365f6277d1ec573cee7fd68a7329d0.1550100949.git.steadmon@google.com>

In-Reply-To

<4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com>

Signed-off-by: Josh Steadmon <steadmon@google.com>
---
Range-diff against v1:
1:  4ffb11ff77 ! 1:  cb1b2834b7 protocol-capabilities.txt: document symref
    @@ -12,6 +12,17 @@
      diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
      --- a/Documentation/technical/protocol-capabilities.txt
      +++ b/Documentation/technical/protocol-capabilities.txt
    +@@
    + Git Protocol Capabilities
    + =========================
    + 
    ++NOTE: this document describes capabilities for versions 0 and 1 of the pack
    ++protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
    ++doc.
    ++
    + Servers SHOULD support all capabilities defined in this document.
    + 
    + On the very first line of the initial server response of either
     @@
      purposes, and MUST NOT be used to programmatically assume the presence
      or absence of particular features.

 .../technical/protocol-capabilities.txt        | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index 332d209b58..2b267c0da6 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -1,6 +1,10 @@
 Git Protocol Capabilities
 =========================
 
+NOTE: this document describes capabilities for versions 0 and 1 of the pack
+protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
+doc.
+
 Servers SHOULD support all capabilities defined in this document.
 
 On the very first line of the initial server response of either
@@ -172,6 +176,20 @@ agent strings are purely informative for statistics and debugging
 purposes, and MUST NOT be used to programmatically assume the presence
 or absence of particular features.
 
+symref
+------
+
+This parameterized capability is used to inform the receiver which symbolic ref
+points to which ref; for example, "symref=HEAD:refs/heads/master" tells the
+receiver that HEAD points to master. This capability can be repeated to
+represent multiple symrefs.
+
+Servers SHOULD include this capability for the HEAD symref if it is one of the
+refs being sent.
+
+Clients MAY use the parameters from this capability to select the proper initial
+branch when cloning a repository.
+
 shallow
 -------
 

-- 
2.20.1.791.gb4d0f1c61a-goog