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>
Josh Steadmon committed
Feb 19, 2019 at 16:32 UTC
90503a240bc126adc8cddb7b860e19c30b0dfa6f
1 file changed
+18
Documentation/technical/protocol-capabilities.txt
+18
@@ -1,6 +1,10 @@
1
Git Protocol Capabilities
2
=========================
3
4
+NOTE: this document describes capabilities for versions 0 and 1 of the pack
5
+protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
6
+doc.
7
+
8
Servers SHOULD support all capabilities defined in this document.
9
10
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
176
purposes, and MUST NOT be used to programmatically assume the presence
177
or absence of particular features.
178
179
+symref
180
+------
181
+
182
+This parameterized capability is used to inform the receiver which symbolic ref
183
+points to which ref; for example, "symref=HEAD:refs/heads/master" tells the
184
+receiver that HEAD points to master. This capability can be repeated to
185
+represent multiple symrefs.
186
+
187
+Servers SHOULD include this capability for the HEAD symref if it is one of the
188
+refs being sent.
189
+
190
+Clients MAY use the parameters from this capability to select the proper initial
191
+branch when cloning a repository.
192
+
193
shallow
194
-------
195