threads / patch / 50473

patchprotocol-capabilities.txt: document symref

Subject: [PATCH] protocol-capabilities.txt: document symref

## tl;dr

9 messages between Feb 11, 2019 and Feb 21, 2019. Diffs are folded; open one to read it.

replies: 8people: 4as markdown or json

Josh Steadmon· Feb 11, 2019, 23:52 UTC · lore

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>
---
 Documentation/technical/protocol-capabilities.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
Show changes to Documentation/technical/protocol-capabilities.txt +14 −0
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· Feb 11, 2019, 23:58 UTC · re: Josh Steadmon · lore

Re: [PATCH] protocol-capabilities.txt: document symref

Josh Steadmon wrote:
Show 9 quoted lines
> 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>
> ---
>  Documentation/technical/protocol-capabilities.txt | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Thanks.
Jeff King· Feb 12, 2019, 00:05 UTC · re: Josh Steadmon · lore

Re: [PATCH] protocol-capabilities.txt: document symref

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· Feb 12, 2019, 00:07 UTC · re: Jeff King · lore

Re: [PATCH] protocol-capabilities.txt: document symref

On 2019.02.11 19:05, Jeff King wrote:
Show 16 quoted lines
> 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· Feb 13, 2019, 23:41 UTC · re: Josh Steadmon · lore

[PATCH v2] 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.

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(+)
Show changes to Documentation/technical/protocol-capabilities.txt +18 −0
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· Feb 14, 2019, 03:56 UTC · re: Josh Steadmon · lore

Re: [PATCH v2] protocol-capabilities.txt: document symref

On Wed, Feb 13, 2019 at 03:41:28PM -0800, Josh Steadmon wrote:
Show 18 quoted lines
> ---
> 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· Feb 20, 2019, 00:32 UTC · re: Jeff King · lore

Re: [PATCH v2] protocol-capabilities.txt: document symref

On 2019.02.13 22:56, Jeff King wrote:
Show 36 quoted lines
> 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· Feb 21, 2019, 17:38 UTC · re: Josh Steadmon · lore

Re: [PATCH v2] protocol-capabilities.txt: document symref

Josh Steadmon <steadmon@google.com> writes:
Show 10 quoted lines
> 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.
Show 7 quoted lines
>> 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.
Josh Steadmon· Feb 20, 2019, 00:32 UTC · re: Josh Steadmon · lore

[PATCH v3] 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>
---
 .../technical/protocol-capabilities.txt        | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
Show changes to Documentation/technical/protocol-capabilities.txt +18 −0
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

← back to recent threads