{"thread":{"id":"50473","subject":"[PATCH] protocol-capabilities.txt: document symref","startedAt":"2019-02-11T23:52:28Z","lastAt":"2019-02-21T17:38:11Z","messageCount":9,"participants":["Josh Steadmon","Jonathan Nieder","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"369056","messageId":"4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com","threadId":"50473","inReplyTo":null,"subject":"[PATCH] protocol-capabilities.txt: document symref","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2019-02-11T23:52:24Z","receivedAt":"2019-02-11T23:52:28Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"In 7171d8c15f (\"upload-pack: send symbolic ref information as\ncapability\"), we added a symref capability to the pack protocol, but it\nwas never documented. Adapt the patch notes from that commit and add\nthem to the capabilities documentation.\n\nSigned-off-by: Josh Steadmon <steadmon@google.com>\n---\n Documentation/technical/protocol-capabilities.txt | 14 ++++++++++++++\n 1 file changed, 14 insertions(+)\n\ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt\nindex 332d209b58..0ccdbadbe9 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/technical/protocol-capabilities.txt\n@@ -172,6 +172,20 @@ agent strings are purely informative for statistics and debugging\n purposes, and MUST NOT be used to programmatically assume the presence\n or absence of particular features.\n \n+symref\n+------\n+\n+This parameterized capability is used to inform the receiver which symbolic ref\n+points to which ref; for example, \"symref=HEAD:refs/heads/master\" tells the\n+receiver that HEAD points to master. This capability can be repeated to\n+represent multiple symrefs.\n+\n+Servers SHOULD include this capability for the HEAD symref if it is one of the\n+refs being sent.\n+\n+Clients MAY use the parameters from this capability to select the proper initial\n+branch when cloning a repository.\n+\n shallow\n -------\n \n-- \n2.20.1.791.gb4d0f1c61a-goog\n\n"},{"id":"369059","messageId":"20190211235853.GA8714@google.com","threadId":"50473","inReplyTo":"4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com","subject":"Re: [PATCH] protocol-capabilities.txt: document symref","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2019-02-11T23:58:53Z","receivedAt":"2019-02-11T23:58:57Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Josh Steadmon wrote:\n\n> In 7171d8c15f (\"upload-pack: send symbolic ref information as\n> capability\"), we added a symref capability to the pack protocol, but it\n> was never documented. Adapt the patch notes from that commit and add\n> them to the capabilities documentation.\n>\n> Signed-off-by: Josh Steadmon <steadmon@google.com>\n> ---\n>  Documentation/technical/protocol-capabilities.txt | 14 ++++++++++++++\n>  1 file changed, 14 insertions(+)\n\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\nThanks.\n"},{"id":"369061","messageId":"20190212000530.GC13301@sigill.intra.peff.net","threadId":"50473","inReplyTo":"4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com","subject":"Re: [PATCH] protocol-capabilities.txt: document symref","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-02-12T00:05:30Z","receivedAt":"2019-02-12T00:05:33Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Feb 11, 2019 at 03:52:24PM -0800, Josh Steadmon wrote:\n\n> In 7171d8c15f (\"upload-pack: send symbolic ref information as\n> capability\"), we added a symref capability to the pack protocol, but it\n> was never documented. Adapt the patch notes from that commit and add\n> them to the capabilities documentation.\n\nGood catch, and your explanation (especially the SHOULD/MAY bits) looks\ngood.\n\nI think this is obsoleted by v2, which will send symref info along with\neach ref. I don't know if it's worth mentioning that here (the v2 docs\ndiscuss it, but I don't know if this capabilities document is clear\nabout which ones apply only to v0).\n\n-Peff\n"},{"id":"369062","messageId":"20190212000749.GF72177@google.com","threadId":"50473","inReplyTo":"20190212000530.GC13301@sigill.intra.peff.net","subject":"Re: [PATCH] protocol-capabilities.txt: document symref","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2019-02-12T00:07:49Z","receivedAt":"2019-02-12T00:07:57Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2019.02.11 19:05, Jeff King wrote:\n> On Mon, Feb 11, 2019 at 03:52:24PM -0800, Josh Steadmon wrote:\n> \n> > In 7171d8c15f (\"upload-pack: send symbolic ref information as\n> > capability\"), we added a symref capability to the pack protocol, but it\n> > was never documented. Adapt the patch notes from that commit and add\n> > them to the capabilities documentation.\n> \n> Good catch, and your explanation (especially the SHOULD/MAY bits) looks\n> good.\n> \n> I think this is obsoleted by v2, which will send symref info along with\n> each ref. I don't know if it's worth mentioning that here (the v2 docs\n> discuss it, but I don't know if this capabilities document is clear\n> about which ones apply only to v0).\n> \n> -Peff\n\nI believe this doc is only for v0/v1. I'll add a note.\n"},{"id":"369268","messageId":"cb1b2834b7365f6277d1ec573cee7fd68a7329d0.1550100949.git.steadmon@google.com","threadId":"50473","inReplyTo":"4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com","subject":"[PATCH v2] protocol-capabilities.txt: document symref","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2019-02-13T23:41:28Z","receivedAt":"2019-02-13T23:41:34Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"In 7171d8c15f (\"upload-pack: send symbolic ref information as\ncapability\"), we added a symref capability to the pack protocol, but it\nwas never documented. Adapt the patch notes from that commit and add\nthem to the capabilities documentation.\n\nSigned-off-by: Josh Steadmon <steadmon@google.com>\n---\nRange-diff against v1:\n1:  4ffb11ff77 ! 1:  cb1b2834b7 protocol-capabilities.txt: document symref\n    @@ -12,6 +12,17 @@\n      diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt\n      --- a/Documentation/technical/protocol-capabilities.txt\n      +++ b/Documentation/technical/protocol-capabilities.txt\n    +@@\n    + Git Protocol Capabilities\n    + =========================\n    + \n    ++NOTE: this document describes capabilities for versions 0 and 1 of the pack\n    ++protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n    ++doc.\n    ++\n    + Servers SHOULD support all capabilities defined in this document.\n    + \n    + On the very first line of the initial server response of either\n     @@\n      purposes, and MUST NOT be used to programmatically assume the presence\n      or absence of particular features.\n\n .../technical/protocol-capabilities.txt        | 18 ++++++++++++++++++\n 1 file changed, 18 insertions(+)\n\ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt\nindex 332d209b58..2b267c0da6 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/technical/protocol-capabilities.txt\n@@ -1,6 +1,10 @@\n Git Protocol Capabilities\n =========================\n \n+NOTE: this document describes capabilities for versions 0 and 1 of the pack\n+protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+doc.\n+\n Servers SHOULD support all capabilities defined in this document.\n \n On the very first line of the initial server response of either\n@@ -172,6 +176,20 @@ agent strings are purely informative for statistics and debugging\n purposes, and MUST NOT be used to programmatically assume the presence\n or absence of particular features.\n \n+symref\n+------\n+\n+This parameterized capability is used to inform the receiver which symbolic ref\n+points to which ref; for example, \"symref=HEAD:refs/heads/master\" tells the\n+receiver that HEAD points to master. This capability can be repeated to\n+represent multiple symrefs.\n+\n+Servers SHOULD include this capability for the HEAD symref if it is one of the\n+refs being sent.\n+\n+Clients MAY use the parameters from this capability to select the proper initial\n+branch when cloning a repository.\n+\n shallow\n -------\n \n-- \n2.20.1.791.gb4d0f1c61a-goog\n\n"},{"id":"369273","messageId":"20190214035602.GA7209@sigill.intra.peff.net","threadId":"50473","inReplyTo":"cb1b2834b7365f6277d1ec573cee7fd68a7329d0.1550100949.git.steadmon@google.com","subject":"Re: [PATCH v2] protocol-capabilities.txt: document symref","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-02-14T03:56:02Z","receivedAt":"2019-02-14T03:56:06Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Feb 13, 2019 at 03:41:28PM -0800, Josh Steadmon wrote:\n\n> ---\n> Range-diff against v1:\n> 1:  4ffb11ff77 ! 1:  cb1b2834b7 protocol-capabilities.txt: document symref\n>     @@ -12,6 +12,17 @@\n>       diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt\n>       --- a/Documentation/technical/protocol-capabilities.txt\n>       +++ b/Documentation/technical/protocol-capabilities.txt\n>     +@@\n>     + Git Protocol Capabilities\n>     + =========================\n>     + \n>     ++NOTE: this document describes capabilities for versions 0 and 1 of the pack\n>     ++protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n>     ++doc.\n>     ++\n>     + Servers SHOULD support all capabilities defined in this document.\n>     + \n>     + On the very first line of the initial server response of either\n\nI think this makes sense. I wondered to what degree the v2 protocol doc\nmay say \"...and you can use capabilities from protocol-capabilities.txt\nhere\". But it doesn't. It newly lists the capabilities, which makes this\nparagraph the right thing to say.\n\nIt does mean that if we teach v1 a new capability, we'll have to\ndocument it in both places. But moving forward, we'd hopefully not be\ndoing that too often (I haven't seen talk of flipping the v2 switch yet\nby default, but obviously that's where we want to end up).\n\nI probably would have put this in its own patch, but barring that we\nshould probably at least mention in the commit message what this\nparagraph is doing here.\n\n-Peff\n"},{"id":"369684","messageId":"f8de6411ffccf98f51dfa2eaf16073515933e4ec.1550622671.git.steadmon@google.com","threadId":"50473","inReplyTo":"4ffb11ff776166944673ba3bdb96a9d20eb14df7.1549929088.git.steadmon@google.com","subject":"[PATCH v3] protocol-capabilities.txt: document symref","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2019-02-20T00:32:26Z","receivedAt":"2019-02-20T00:32:33Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"In 7171d8c15f (\"upload-pack: send symbolic ref information as\ncapability\"), we added a symref capability to the pack protocol, but it\nwas never documented. Adapt the patch notes from that commit and add\nthem to the capabilities documentation.\n\nWhile we're at it, add a disclaimer to the top of\nprotocol-capabilities.txt noting that the doc only applies to v0/v1 of\nthe wire protocol.\n\nSigned-off-by: Josh Steadmon <steadmon@google.com>\n---\n .../technical/protocol-capabilities.txt        | 18 ++++++++++++++++++\n 1 file changed, 18 insertions(+)\n\ndiff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt\nindex 332d209b58..2b267c0da6 100644\n--- a/Documentation/technical/protocol-capabilities.txt\n+++ b/Documentation/technical/protocol-capabilities.txt\n@@ -1,6 +1,10 @@\n Git Protocol Capabilities\n =========================\n \n+NOTE: this document describes capabilities for versions 0 and 1 of the pack\n+protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n+doc.\n+\n Servers SHOULD support all capabilities defined in this document.\n \n On the very first line of the initial server response of either\n@@ -172,6 +176,20 @@ agent strings are purely informative for statistics and debugging\n purposes, and MUST NOT be used to programmatically assume the presence\n or absence of particular features.\n \n+symref\n+------\n+\n+This parameterized capability is used to inform the receiver which symbolic ref\n+points to which ref; for example, \"symref=HEAD:refs/heads/master\" tells the\n+receiver that HEAD points to master. This capability can be repeated to\n+represent multiple symrefs.\n+\n+Servers SHOULD include this capability for the HEAD symref if it is one of the\n+refs being sent.\n+\n+Clients MAY use the parameters from this capability to select the proper initial\n+branch when cloning a repository.\n+\n shallow\n -------\n \n-- \n2.21.0.rc0.258.g878e2cd30e-goog\n\n"},{"id":"369685","messageId":"20190220003248.GA160251@google.com","threadId":"50473","inReplyTo":"20190214035602.GA7209@sigill.intra.peff.net","subject":"Re: [PATCH v2] protocol-capabilities.txt: document symref","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2019-02-20T00:32:48Z","receivedAt":"2019-02-20T00:32:57Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2019.02.13 22:56, Jeff King wrote:\n> On Wed, Feb 13, 2019 at 03:41:28PM -0800, Josh Steadmon wrote:\n> \n> > ---\n> > Range-diff against v1:\n> > 1:  4ffb11ff77 ! 1:  cb1b2834b7 protocol-capabilities.txt: document symref\n> >     @@ -12,6 +12,17 @@\n> >       diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt\n> >       --- a/Documentation/technical/protocol-capabilities.txt\n> >       +++ b/Documentation/technical/protocol-capabilities.txt\n> >     +@@\n> >     + Git Protocol Capabilities\n> >     + =========================\n> >     + \n> >     ++NOTE: this document describes capabilities for versions 0 and 1 of the pack\n> >     ++protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]\n> >     ++doc.\n> >     ++\n> >     + Servers SHOULD support all capabilities defined in this document.\n> >     + \n> >     + On the very first line of the initial server response of either\n> \n> I think this makes sense. I wondered to what degree the v2 protocol doc\n> may say \"...and you can use capabilities from protocol-capabilities.txt\n> here\". But it doesn't. It newly lists the capabilities, which makes this\n> paragraph the right thing to say.\n> \n> It does mean that if we teach v1 a new capability, we'll have to\n> document it in both places. But moving forward, we'd hopefully not be\n> doing that too often (I haven't seen talk of flipping the v2 switch yet\n> by default, but obviously that's where we want to end up).\n> \n> I probably would have put this in its own patch, but barring that we\n> should probably at least mention in the commit message what this\n> paragraph is doing here.\n> \n> -Peff\n\nDone in V3. Thanks!\n"},{"id":"369825","messageId":"xmqqd0nlujnm.fsf@gitster-ct.c.googlers.com","threadId":"50473","inReplyTo":"20190220003248.GA160251@google.com","subject":"Re: [PATCH v2] protocol-capabilities.txt: document symref","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-02-21T17:38:05Z","receivedAt":"2019-02-21T17:38:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> On 2019.02.13 22:56, Jeff King wrote:\n> ...\n>> may say \"...and you can use capabilities from protocol-capabilities.txt\n>> here\". But it doesn't. It newly lists the capabilities, which makes this\n>> paragraph the right thing to say.\n>> \n>> It does mean that if we teach v1 a new capability, we'll have to\n>> document it in both places. But moving forward, we'd hopefully not be\n>> doing that too often (I haven't seen talk of flipping the v2 switch yet\n>> by default, but obviously that's where we want to end up).\n\nYes.\n\n>> I probably would have put this in its own patch, but barring that we\n>> should probably at least mention in the commit message what this\n>> paragraph is doing here.\n>> \n>> -Peff\n>\n> Done in V3. Thanks!\n\nWill replace (easy to do as nothing is moving to 'next', unless it\nis for the upcoming release, during the freeze anyway ;-)\n\nThanks.\n"}]}