Re: [WIP RFC 1/5] Documentation: order protocol v2 sections

[Jonathan Tan]

> > The git command line expects Git servers to follow a specific order of
> 
> "Command line"?  It sounds like you are talking about the order of
> command line arguments and options, but apparently that is not what
> you are doing.  Is it "The git over-the-wire protocol"?

I meant to say the current Git implementation, as opposed to what is
written in the specification. I'll replace it with "The current C Git
implementation".

> Earlier, we said that shallow-info is not given when packfile is not
> there.  That is captured in the updated EBNF above.  We don't have a
> corresponding removal of a bullet point for wanted-refs section below
> but probably that is because the original did not have corresponding
> bullet point to begin with.

That's because the corresponding bullet point had other information.
Quoted in full below:

>   * This section is only included if the client has requested a
> ref using a 'want-ref' line and if a packfile section is also
> included in the response.

I could reword it to "If a packfile section is included in the response,
this section is only included if the client has requested a ref using a
'want-ref' line", but I don't think that is significantly clearer.

Re: [WIP RFC 1/5] Documentation: order protocol v2 sections

[Junio C Hamano]

Jonathan Tan  writes:

> The git command line expects Git servers to follow a specific order of

"Command line"?  It sounds like you are talking about the order of
command line arguments and options, but apparently that is not what
you are doing.  Is it "The git over-the-wire protocol"?

> +output = acknowledgements flush-pkt |
> +  [acknowledgments delim-pkt] [shallow-info delim-pkt]
> +  [wanted-refs delim-pkt] packfile flush-pkt

So the output can be either 

 - acks followed by flush (and nothing else) or

 - (possibly) acks, followed by (possibly) shallow, followed by
   (possibly) wanted-refs, followed by the pack stream and flush at
   the end.

> @@ -335,9 +335,10 @@ header.
>  *PKT-LINE(%x01-03 *%x00-ff)
>  
>  acknowledgments section
> - * If the client determines that it is finished with negotiations
> -   by sending a "done" line, the acknowledgments sections MUST be
> -   omitted from the server's response.
> + * If the client determines that it is finished with negotiations by
> +   sending a "done" line (thus requiring the server to send a packfile),
> +   the acknowledgments sections MUST be omitted from the server's
> +   response.

OK.  

>   * Always begins with the section header "acknowledgments"
>  
> @@ -388,9 +389,6 @@ header.
> which the client has not indicated was shallow as a part of
> its request.
>  
> - * This section is only included if a packfile section is also
> -   included in the response.
> -

Earlier, we said that shallow-info is not given when packfile is not
there.  That is captured in the updated EBNF above.  We don't have a
corresponding removal of a bullet point for wanted-refs section below
but probably that is because the original did not have corresponding
bullet point to begin with.

>  wanted-refs section
>   * This section is only included if the client has requested a
> ref using a 'want-ref' line and if a packfile section is also

[WIP RFC 1/5] Documentation: order protocol v2 sections

[Jonathan Tan]

The git command line expects Git servers to follow a specific order of
sections when transmitting protocol v2 responses, but this is not
explicit in the documentation. Make the order explicit.

Signed-off-by: Jonathan Tan 
---
 Documentation/technical/protocol-v2.txt | 18 --
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/Documentation/technical/protocol-v2.txt 
b/Documentation/technical/protocol-v2.txt
index 09e4e0273f..345c00e08c 100644
--- a/Documentation/technical/protocol-v2.txt
+++ b/Documentation/technical/protocol-v2.txt
@@ -309,11 +309,11 @@ the 'wanted-refs' section in the server's response as 
explained below.
 
 The response of `fetch` is broken into a number of sections separated by
 delimiter packets (0001), with each section beginning with its section
-header.
+header. Most sections are sent only when the packfile is sent.
 
-output = *section
-section = (acknowledgments | shallow-info | wanted-refs | packfile)
- (flush-pkt | delim-pkt)
+output = acknowledgements flush-pkt |
+[acknowledgments delim-pkt] [shallow-info delim-pkt]
+[wanted-refs delim-pkt] packfile flush-pkt
 
 acknowledgments = PKT-LINE("acknowledgments" LF)
  (nak | *ack)
@@ -335,9 +335,10 @@ header.
   *PKT-LINE(%x01-03 *%x00-ff)
 
 acknowledgments section
-   * If the client determines that it is finished with negotiations
- by sending a "done" line, the acknowledgments sections MUST be
- omitted from the server's response.
+   * If the client determines that it is finished with negotiations by
+ sending a "done" line (thus requiring the server to send a packfile),
+ the acknowledgments sections MUST be omitted from the server's
+ response.
 
* Always begins with the section header "acknowledgments"
 
@@ -388,9 +389,6 @@ header.
  which the client has not indicated was shallow as a part of
  its request.
 
-   * This section is only included if a packfile section is also
- included in the response.
-
 wanted-refs section
* This section is only included if the client has requested a
  ref using a 'want-ref' line and if a packfile section is also
-- 
2.19.0.271.gfe8321ec05.dirty