# [PATCH] protocol-capabilities.txt: document symref 9 messages from 2019-02-11 to 2019-02-21. Participants: Josh Steadmon, Jonathan Nieder, Jeff King, Junio C Hamano. Thread: https://gitlist.dev/t/50473 ## Josh Steadmon, 2019-02-11 23:52 Subject: [PATCH] protocol-capabilities.txt: document symref Message-ID: <4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com> URL: https://gitlist.dev/e/4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon%40google.com ``` 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 --- Documentation/technical/protocol-capabilities.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 332d209b58..0ccdbadbe9 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -172,6 +172,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 ``` ## Jonathan Nieder, 2019-02-11 23:58 Subject: Re: [PATCH] protocol-capabilities.txt: document symref Message-ID: <20190211235853.GA8714@google.com> URL: https://gitlist.dev/e/20190211235853.GA8714%40google.com In-Reply-To: <4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com> ``` Josh Steadmon wrote: > 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 > --- > Documentation/technical/protocol-capabilities.txt | 14 ++++++++++++++ > 1 file changed, 14 insertions(+) Reviewed-by: Jonathan Nieder Thanks. ``` ## Jeff King, 2019-02-12 00:05 Subject: Re: [PATCH] protocol-capabilities.txt: document symref Message-ID: <20190212000530.GC13301@sigill.intra.peff.net> URL: https://gitlist.dev/e/20190212000530.GC13301%40sigill.intra.peff.net In-Reply-To: <4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com> ``` On Mon, Feb 11, 2019 at 03:52:24PM -0800, Josh Steadmon wrote: > 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. Good catch, and your explanation (especially the SHOULD/MAY bits) looks good. I think this is obsoleted by v2, which will send symref info along with each ref. I don't know if it's worth mentioning that here (the v2 docs discuss it, but I don't know if this capabilities document is clear about which ones apply only to v0). -Peff ``` ## Josh Steadmon, 2019-02-12 00:07 Subject: Re: [PATCH] protocol-capabilities.txt: document symref Message-ID: <20190212000749.GF72177@google.com> URL: https://gitlist.dev/e/20190212000749.GF72177%40google.com In-Reply-To: <20190212000530.GC13301@sigill.intra.peff.net> ``` On 2019.02.11 19:05, Jeff King wrote: > On Mon, Feb 11, 2019 at 03:52:24PM -0800, Josh Steadmon wrote: > > > 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. > > Good catch, and your explanation (especially the SHOULD/MAY bits) looks > good. > > I think this is obsoleted by v2, which will send symref info along with > each ref. I don't know if it's worth mentioning that here (the v2 docs > discuss it, but I don't know if this capabilities document is clear > about which ones apply only to v0). > > -Peff I believe this doc is only for v0/v1. I'll add a note. ``` ## Josh Steadmon, 2019-02-13 23:41 Subject: [PATCH v2] protocol-capabilities.txt: document symref Message-ID: URL: https://gitlist.dev/e/cb1b2834b7365f6277d1ec573cee7fd68a7329d0.1550100949.git.steadmon%40google.com In-Reply-To: <4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com> ``` 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 --- 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 ``` ## Jeff King, 2019-02-14 03:56 Subject: Re: [PATCH v2] protocol-capabilities.txt: document symref Message-ID: <20190214035602.GA7209@sigill.intra.peff.net> URL: https://gitlist.dev/e/20190214035602.GA7209%40sigill.intra.peff.net In-Reply-To: ``` 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 ``` ## Josh Steadmon, 2019-02-20 00:32 Subject: [PATCH v3] protocol-capabilities.txt: document symref Message-ID: URL: https://gitlist.dev/e/f8de6411ffccf98f51dfa2eaf16073515933e4ec.1550622671.git.steadmon%40google.com In-Reply-To: <4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com> ``` 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 --- .../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.21.0.rc0.258.g878e2cd30e-goog ``` ## Josh Steadmon, 2019-02-20 00:32 Subject: Re: [PATCH v2] protocol-capabilities.txt: document symref Message-ID: <20190220003248.GA160251@google.com> URL: https://gitlist.dev/e/20190220003248.GA160251%40google.com In-Reply-To: <20190214035602.GA7209@sigill.intra.peff.net> ``` 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! ``` ## Junio C Hamano, 2019-02-21 17:38 Subject: Re: [PATCH v2] protocol-capabilities.txt: document symref Message-ID: URL: https://gitlist.dev/e/xmqqd0nlujnm.fsf%40gitster-ct.c.googlers.com In-Reply-To: <20190220003248.GA160251@google.com> ``` Josh Steadmon 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. ```