| Message ID | cb1b2834b7365f6277d1ec573cee7fd68a7329d0.1550100949.git.steadmon@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] protocol-capabilities.txt: document symref | expand |
On Wed, Feb 13, 2019 at 03:41:28PM -0800, Josh Steadmon wrote: > --- > 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 I think this makes sense. I wondered to what degree the v2 protocol doc may say "...and you can use capabilities from protocol-capabilities.txt here". But it doesn't. It newly lists the capabilities, which makes this paragraph the right thing to say. It does mean that if we teach v1 a new capability, we'll have to document it in both places. But moving forward, we'd hopefully not be doing that too often (I haven't seen talk of flipping the v2 switch yet by default, but obviously that's where we want to end up). I probably would have put this in its own patch, but barring that we should probably at least mention in the commit message what this paragraph is doing here. -Peff
On 2019.02.13 22:56, Jeff King wrote: > On Wed, Feb 13, 2019 at 03:41:28PM -0800, Josh Steadmon wrote: > > > --- > > 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 > > I think this makes sense. I wondered to what degree the v2 protocol doc > may say "...and you can use capabilities from protocol-capabilities.txt > here". But it doesn't. It newly lists the capabilities, which makes this > paragraph the right thing to say. > > It does mean that if we teach v1 a new capability, we'll have to > document it in both places. But moving forward, we'd hopefully not be > doing that too often (I haven't seen talk of flipping the v2 switch yet > by default, but obviously that's where we want to end up). > > I probably would have put this in its own patch, but barring that we > should probably at least mention in the commit message what this > paragraph is doing here. > > -Peff Done in V3. Thanks!
Josh Steadmon <steadmon@google.com> writes: > On 2019.02.13 22:56, Jeff King wrote: > ... >> may say "...and you can use capabilities from protocol-capabilities.txt >> here". But it doesn't. It newly lists the capabilities, which makes this >> paragraph the right thing to say. >> >> It does mean that if we teach v1 a new capability, we'll have to >> document it in both places. But moving forward, we'd hopefully not be >> doing that too often (I haven't seen talk of flipping the v2 switch yet >> by default, but obviously that's where we want to end up). Yes. >> I probably would have put this in its own patch, but barring that we >> should probably at least mention in the commit message what this >> paragraph is doing here. >> >> -Peff > > Done in V3. Thanks! Will replace (easy to do as nothing is moving to 'next', unless it is for the upcoming release, during the freeze anyway ;-) Thanks.
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 -------
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. 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(+)