protocol-capabilities.txt: document symref

In 7171d8c15f ("upload-pack: send symbolic ref information as
capability"), we added a symref capability to the pack protocol, but it
was never documented. Adapt the patch notes from that commit and add
them to the capabilities documentation.

While we're at it, add a disclaimer to the top of
protocol-capabilities.txt noting that the doc only applies to v0/v1 of
the wire protocol.

Signed-off-by: Josh Steadmon <steadmon@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index 332d209b58ca42dc303c757f2b31f7a4f3d033f4..2b267c0da6b2d88c8ab9425745b7239e3f867b6e 100644 (file)
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -1,6 +1,10 @@
 Git Protocol Capabilities
 =========================
 
 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
 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.
 
 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
 -------
 
 shallow
 -------