[PATCH] protocol-capabilities.txt: document symref

[PATCH] protocol-capabilities.txt: document symref

[Josh Steadmon]

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(+)

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

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

[Jonathan Nieder]

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 <steadmon@google.com>
> ---
>  Documentation/technical/protocol-capabilities.txt | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks.

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

[Jeff King]

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

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

[Josh Steadmon]

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.

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

[Josh Steadmon]

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(+)

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

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

[Jeff King]

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

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

[Josh Steadmon]

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(+)

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

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

[Josh Steadmon]

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!

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

[Junio C Hamano]

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.