All of lore.kernel.org
 help / color / mirror / Atom feed
* [GSoC PATCH 0/3] doc: improve gitprotocol-pack
@ 2026-03-02 16:09 LorenzoPegorari
  2026-03-02 16:10 ` [GSoC PATCH 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
                   ` (3 more replies)
  0 siblings, 4 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-02 16:09 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

While studying the `gitprotocol-pack` documentation, I found various
small style inconsistencies.

The patches are just tiny, simple improvements, mostly to improve the
clarity of the documentation.

LorenzoPegorari (3):
  doc: gitprotocol-pack: fix pronoun-antecedent agreement
  doc: gitprotocol-pack: improve paragraphs structure
  doc: gitprotocol-pack: normalize inline code formatting

 Documentation/gitprotocol-pack.adoc | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

-- 
2.43.0


^ permalink raw reply	[flat|nested] 15+ messages in thread

* [GSoC PATCH 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement
  2026-03-02 16:09 [GSoC PATCH 0/3] doc: improve gitprotocol-pack LorenzoPegorari
@ 2026-03-02 16:10 ` LorenzoPegorari
  2026-03-02 16:10 ` [GSoC PATCH 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-02 16:10 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Fix "pronoun-antecedent agreement" errors.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index 837b691c89..9952fac188 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -65,7 +65,7 @@ Extra Parameters
 ----------------
 
 The protocol provides a mechanism in which clients can send additional
-information in its first message to the server. These are called "Extra
+information in their first message to the server. These are called "Extra
 Parameters", and are supported by the Git, SSH, and HTTP protocols.
 
 Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
@@ -277,7 +277,7 @@ out of what the server said it could do with the first 'want' line.
   filter-request    =  PKT-LINE("filter" SP filter-spec)
 ----
 
-Clients MUST send all the obj-ids it wants from the reference
+Clients MUST send all the obj-ids they want from the reference
 discovery phase as 'want' lines. Clients MUST send at least one
 'want' command in the request body. Clients MUST NOT mention an
 obj-id in a 'want' command which did not appear in the response
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* [GSoC PATCH 2/3] doc: gitprotocol-pack: improve paragraphs structure
  2026-03-02 16:09 [GSoC PATCH 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  2026-03-02 16:10 ` [GSoC PATCH 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
@ 2026-03-02 16:10 ` LorenzoPegorari
  2026-03-02 16:10 ` [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting LorenzoPegorari
  2026-03-03  1:34 ` [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  3 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-02 16:10 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Logically separate the introductory sentence from the first transport
description to improve readability and structural clarity.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index 9952fac188..f4c9e024b0 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -47,7 +47,9 @@ process defined in this protocol is terminated.
 Transports
 ----------
 There are three transports over which the packfile protocol is
-initiated.  The Git transport is a simple, unauthenticated server that
+initiated.
+
+The Git transport is a simple, unauthenticated server that
 takes the command (almost always 'upload-pack', though Git
 servers can be configured to be globally writable, in which 'receive-
 pack' initiation is also allowed) with which the client wishes to
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting
  2026-03-02 16:09 [GSoC PATCH 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  2026-03-02 16:10 ` [GSoC PATCH 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
  2026-03-02 16:10 ` [GSoC PATCH 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
@ 2026-03-02 16:10 ` LorenzoPegorari
  2026-03-02 23:01   ` Junio C Hamano
  2026-03-03  1:34 ` [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  3 siblings, 1 reply; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-02 16:10 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Uniform inline code usage for command and process names.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index f4c9e024b0..63d3971037 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -117,7 +117,7 @@ process on the server side over the Git protocol is this:
 SSH Transport
 -------------
 
-Initiating the upload-pack or receive-pack processes over SSH is
+Initiating the 'upload-pack' or 'receive-pack' processes over SSH is
 executing the binary on the server via SSH remote execution.
 It is basically equivalent to running this:
 
@@ -131,7 +131,7 @@ two commands, or even just one of them.
 
 In an ssh:// format URI, it's absolute in the URI, so the '/' after
 the host name (or port number) is sent as an argument, which is then
-read by the remote git-upload-pack exactly as is, so it's effectively
+read by the remote `git-upload-pack` exactly as is, so it's effectively
 an absolute path in the remote filesystem.
 
        git clone ssh://user@example.com/project.git
@@ -163,7 +163,7 @@ supports passing environment variables as an argument.
 
 A few things to remember here:
 
-- The "command name" is spelled with dash (e.g. git-upload-pack), but
+- The "command name" is spelled with dash (e.g. `git-upload-pack`), but
   this can be overridden by the client;
 
 - The repository path is always quoted with single quotes.
@@ -377,10 +377,10 @@ In multi_ack_detailed mode:
 
 Without either multi_ack or multi_ack_detailed:
 
- * upload-pack sends "ACK obj-id" on the first common object it finds.
+ * `upload-pack` sends "ACK obj-id" on the first common object it finds.
    After that it says nothing until the client gives it a "done".
 
- * upload-pack sends "NAK" on a flush-pkt if no common object
+ * `upload-pack` sends "NAK" on a flush-pkt if no common object
    has been found yet.  If one has been found, and thus an ACK
    was already sent, it's silent on the flush-pkt.
 
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* Re: [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting
  2026-03-02 16:10 ` [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting LorenzoPegorari
@ 2026-03-02 23:01   ` Junio C Hamano
  2026-03-03  1:26     ` Lorenzo Pegorari
  0 siblings, 1 reply; 15+ messages in thread
From: Junio C Hamano @ 2026-03-02 23:01 UTC (permalink / raw)
  To: LorenzoPegorari; +Cc: git

LorenzoPegorari <lorenzo.pegorari2002@gmail.com> writes:

> Uniform inline code usage for command and process names.
>
> Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
> ---
>  Documentation/gitprotocol-pack.adoc | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
> index f4c9e024b0..63d3971037 100644
> --- a/Documentation/gitprotocol-pack.adoc
> +++ b/Documentation/gitprotocol-pack.adoc
> @@ -117,7 +117,7 @@ process on the server side over the Git protocol is this:
>  SSH Transport
>  -------------
>  
> -Initiating the upload-pack or receive-pack processes over SSH is
> +Initiating the 'upload-pack' or 'receive-pack' processes over SSH is

These are not `backquoted` for <tt>teletype text</tt> typesetting,
like the other hunks in this patch do?

All other things in these three patches I found them reasonable,
except for this hunk.

Thanks.

>  executing the binary on the server via SSH remote execution.
>  It is basically equivalent to running this:
>  
> @@ -131,7 +131,7 @@ two commands, or even just one of them.
>  
>  In an ssh:// format URI, it's absolute in the URI, so the '/' after
>  the host name (or port number) is sent as an argument, which is then
> -read by the remote git-upload-pack exactly as is, so it's effectively
> +read by the remote `git-upload-pack` exactly as is, so it's effectively
>  an absolute path in the remote filesystem.
>  
>         git clone ssh://user@example.com/project.git
> @@ -163,7 +163,7 @@ supports passing environment variables as an argument.
>  
>  A few things to remember here:
>  
> -- The "command name" is spelled with dash (e.g. git-upload-pack), but
> +- The "command name" is spelled with dash (e.g. `git-upload-pack`), but
>    this can be overridden by the client;
>  
>  - The repository path is always quoted with single quotes.
> @@ -377,10 +377,10 @@ In multi_ack_detailed mode:
>  
>  Without either multi_ack or multi_ack_detailed:
>  
> - * upload-pack sends "ACK obj-id" on the first common object it finds.
> + * `upload-pack` sends "ACK obj-id" on the first common object it finds.
>     After that it says nothing until the client gives it a "done".
>  
> - * upload-pack sends "NAK" on a flush-pkt if no common object
> + * `upload-pack` sends "NAK" on a flush-pkt if no common object
>     has been found yet.  If one has been found, and thus an ACK
>     was already sent, it's silent on the flush-pkt.

^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting
  2026-03-02 23:01   ` Junio C Hamano
@ 2026-03-03  1:26     ` Lorenzo Pegorari
  2026-03-03  1:48       ` Junio C Hamano
  0 siblings, 1 reply; 15+ messages in thread
From: Lorenzo Pegorari @ 2026-03-03  1:26 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

On Mon, Mar 02, 2026 at 03:01:17PM -0800, Junio C Hamano wrote:
> LorenzoPegorari <lorenzo.pegorari2002@gmail.com> writes:
> 
> > Uniform inline code usage for command and process names.
> >
> > Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
> > ---
> >  Documentation/gitprotocol-pack.adoc | 10 +++++-----
> >  1 file changed, 5 insertions(+), 5 deletions(-)
> >
> > diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
> > index f4c9e024b0..63d3971037 100644
> > --- a/Documentation/gitprotocol-pack.adoc
> > +++ b/Documentation/gitprotocol-pack.adoc
> > @@ -117,7 +117,7 @@ process on the server side over the Git protocol is this:
> >  SSH Transport
> >  -------------
> >  
> > -Initiating the upload-pack or receive-pack processes over SSH is
> > +Initiating the 'upload-pack' or 'receive-pack' processes over SSH is
> 
> These are not `backquoted` for <tt>teletype text</tt> typesetting,
> like the other hunks in this patch do?
> 
> All other things in these three patches I found them reasonable,
> except for this hunk.
> 
> Thanks.

Thank you so much for catching all my mistakes Junio.

I misread the existing formatting: I mistook the apostrophes for
backticks, and so I incorrectly assumed that the document used inline
code for command and process names. In reality, the rest of the document
uses italics for these elements.

I'm sending a v2 where I correctly uniform command and process names to
use the italic style ASAP.


^ permalink raw reply	[flat|nested] 15+ messages in thread

* [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack
  2026-03-02 16:09 [GSoC PATCH 0/3] doc: improve gitprotocol-pack LorenzoPegorari
                   ` (2 preceding siblings ...)
  2026-03-02 16:10 ` [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting LorenzoPegorari
@ 2026-03-03  1:34 ` LorenzoPegorari
  2026-03-03  1:34   ` [GSoC PATCH v2 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
                     ` (3 more replies)
  3 siblings, 4 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:34 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

While studying the `gitprotocol-pack` documentation, I found various
small style inconsistencies.

These patches are just tiny, simple improvements, mostly to improve the
clarity of the documentation.

V2 DIFF:
 * Fixed final patch to properly conform command and process names to
   italic format, instead of the inline code format

LorenzoPegorari (3):
  doc: gitprotocol-pack: fix pronoun-antecedent agreement
  doc: gitprotocol-pack: improve paragraphs structure
  doc: gitprotocol-pack: normalize italic formatting

 Documentation/gitprotocol-pack.adoc | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

Range-diff against v1:
1:  0d679e5eb5 = 1:  0d679e5eb5 doc: gitprotocol-pack: fix pronoun-antecedent agreement
2:  8a6b5d4c98 = 2:  8a6b5d4c98 doc: gitprotocol-pack: improve paragraphs structure
3:  e0e4ea3d22 ! 3:  6410967d65 doc: gitprotocol-pack: normalize inline code formatting
    @@ Metadata
     Author: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
     
      ## Commit message ##
    -    doc: gitprotocol-pack: normalize inline code formatting
    +    doc: gitprotocol-pack: normalize italic formatting
     
    -    Uniform inline code usage for command and process names.
    +    Uniform italic style usage for command and process names.
     
         Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
     
    @@ Documentation/gitprotocol-pack.adoc: supports passing environment variables as a
      A few things to remember here:
      
     -- The "command name" is spelled with dash (e.g. git-upload-pack), but
    -+- The "command name" is spelled with dash (e.g. `git-upload-pack`), but
    ++- The "command name" is spelled with dash (e.g. 'git-upload-pack'), but
        this can be overridden by the client;
      
      - The repository path is always quoted with single quotes.
    @@ Documentation/gitprotocol-pack.adoc: In multi_ack_detailed mode:
      Without either multi_ack or multi_ack_detailed:
      
     - * upload-pack sends "ACK obj-id" on the first common object it finds.
    -+ * `upload-pack` sends "ACK obj-id" on the first common object it finds.
    ++ * 'upload-pack' sends "ACK obj-id" on the first common object it finds.
         After that it says nothing until the client gives it a "done".
      
     - * upload-pack sends "NAK" on a flush-pkt if no common object
    -+ * `upload-pack` sends "NAK" on a flush-pkt if no common object
    ++ * 'upload-pack' sends "NAK" on a flush-pkt if no common object
         has been found yet.  If one has been found, and thus an ACK
         was already sent, it's silent on the flush-pkt.
      
-- 
2.43.0


^ permalink raw reply	[flat|nested] 15+ messages in thread

* [GSoC PATCH v2 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement
  2026-03-03  1:34 ` [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack LorenzoPegorari
@ 2026-03-03  1:34   ` LorenzoPegorari
  2026-03-03  1:35   ` [GSoC PATCH v2 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
                     ` (2 subsequent siblings)
  3 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:34 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Fix "pronoun-antecedent agreement" errors.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index 837b691c89..9952fac188 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -65,7 +65,7 @@ Extra Parameters
 ----------------
 
 The protocol provides a mechanism in which clients can send additional
-information in its first message to the server. These are called "Extra
+information in their first message to the server. These are called "Extra
 Parameters", and are supported by the Git, SSH, and HTTP protocols.
 
 Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
@@ -277,7 +277,7 @@ out of what the server said it could do with the first 'want' line.
   filter-request    =  PKT-LINE("filter" SP filter-spec)
 ----
 
-Clients MUST send all the obj-ids it wants from the reference
+Clients MUST send all the obj-ids they want from the reference
 discovery phase as 'want' lines. Clients MUST send at least one
 'want' command in the request body. Clients MUST NOT mention an
 obj-id in a 'want' command which did not appear in the response
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* [GSoC PATCH v2 2/3] doc: gitprotocol-pack: improve paragraphs structure
  2026-03-03  1:34 ` [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  2026-03-03  1:34   ` [GSoC PATCH v2 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
@ 2026-03-03  1:35   ` LorenzoPegorari
  2026-03-03  1:38   ` [GSoC PATCH v2 3/3] doc: gitprotocol-pack: normalize italic formatting LorenzoPegorari
  2026-03-03  1:45   ` [GSoC PATCH v3 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  3 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:35 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Logically separate the introductory sentence from the first transport
description to improve readability and structural clarity.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index 9952fac188..f4c9e024b0 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -47,7 +47,9 @@ process defined in this protocol is terminated.
 Transports
 ----------
 There are three transports over which the packfile protocol is
-initiated.  The Git transport is a simple, unauthenticated server that
+initiated.
+
+The Git transport is a simple, unauthenticated server that
 takes the command (almost always 'upload-pack', though Git
 servers can be configured to be globally writable, in which 'receive-
 pack' initiation is also allowed) with which the client wishes to
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* [GSoC PATCH v2 3/3] doc: gitprotocol-pack: normalize italic formatting
  2026-03-03  1:34 ` [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  2026-03-03  1:34   ` [GSoC PATCH v2 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
  2026-03-03  1:35   ` [GSoC PATCH v2 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
@ 2026-03-03  1:38   ` LorenzoPegorari
  2026-03-03  1:45   ` [GSoC PATCH v3 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  3 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:38 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Uniform italic style usage for command and process names.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index f4c9e024b0..7ed591a0bd 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -117,7 +117,7 @@ process on the server side over the Git protocol is this:
 SSH Transport
 -------------
 
-Initiating the upload-pack or receive-pack processes over SSH is
+Initiating the 'upload-pack' or 'receive-pack' processes over SSH is
 executing the binary on the server via SSH remote execution.
 It is basically equivalent to running this:
 
@@ -131,7 +131,7 @@ two commands, or even just one of them.
 
 In an ssh:// format URI, it's absolute in the URI, so the '/' after
 the host name (or port number) is sent as an argument, which is then
-read by the remote git-upload-pack exactly as is, so it's effectively
+read by the remote `git-upload-pack` exactly as is, so it's effectively
 an absolute path in the remote filesystem.
 
        git clone ssh://user@example.com/project.git
@@ -163,7 +163,7 @@ supports passing environment variables as an argument.
 
 A few things to remember here:
 
-- The "command name" is spelled with dash (e.g. git-upload-pack), but
+- The "command name" is spelled with dash (e.g. 'git-upload-pack'), but
   this can be overridden by the client;
 
 - The repository path is always quoted with single quotes.
@@ -377,10 +377,10 @@ In multi_ack_detailed mode:
 
 Without either multi_ack or multi_ack_detailed:
 
- * upload-pack sends "ACK obj-id" on the first common object it finds.
+ * 'upload-pack' sends "ACK obj-id" on the first common object it finds.
    After that it says nothing until the client gives it a "done".
 
- * upload-pack sends "NAK" on a flush-pkt if no common object
+ * 'upload-pack' sends "NAK" on a flush-pkt if no common object
    has been found yet.  If one has been found, and thus an ACK
    was already sent, it's silent on the flush-pkt.
 
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* [GSoC PATCH v3 0/3] doc: improve gitprotocol-pack
  2026-03-03  1:34 ` [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack LorenzoPegorari
                     ` (2 preceding siblings ...)
  2026-03-03  1:38   ` [GSoC PATCH v2 3/3] doc: gitprotocol-pack: normalize italic formatting LorenzoPegorari
@ 2026-03-03  1:45   ` LorenzoPegorari
  2026-03-03  1:45     ` [GSoC PATCH v3 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
                       ` (2 more replies)
  3 siblings, 3 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:45 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

While studying the `gitprotocol-pack` documentation, I found various
small style inconsistencies.

These patches are just tiny, simple improvements, mostly to improve the
clarity of the documentation.

V3 DIFF:
 * Fixed final patch to properly conform command and process names to
   italic format, instead of the inline code format
 * Fixed typo that I forgot to change in v2

LorenzoPegorari (3):
  doc: gitprotocol-pack: fix pronoun-antecedent agreement
  doc: gitprotocol-pack: improve paragraphs structure
  doc: gitprotocol-pack: normalize italic formatting

 Documentation/gitprotocol-pack.adoc | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

Range-diff against v2:
1:  0d679e5eb5 = 1:  0d679e5eb5 doc: gitprotocol-pack: fix pronoun-antecedent agreement
2:  8a6b5d4c98 = 2:  8a6b5d4c98 doc: gitprotocol-pack: improve paragraphs structure
3:  6410967d65 ! 3:  2cf8a13eaf doc: gitprotocol-pack: normalize italic formatting
    @@ Documentation/gitprotocol-pack.adoc: two commands, or even just one of them.
      In an ssh:// format URI, it's absolute in the URI, so the '/' after
      the host name (or port number) is sent as an argument, which is then
     -read by the remote git-upload-pack exactly as is, so it's effectively
    -+read by the remote `git-upload-pack` exactly as is, so it's effectively
    ++read by the remote 'git-upload-pack' exactly as is, so it's effectively
      an absolute path in the remote filesystem.
      
             git clone ssh://user@example.com/project.git
-- 
2.43.0


^ permalink raw reply	[flat|nested] 15+ messages in thread

* [GSoC PATCH v3 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement
  2026-03-03  1:45   ` [GSoC PATCH v3 0/3] doc: improve gitprotocol-pack LorenzoPegorari
@ 2026-03-03  1:45     ` LorenzoPegorari
  2026-03-03  1:46     ` [GSoC PATCH v3 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
  2026-03-03  1:46     ` [GSoC PATCH v3 3/3] doc: gitprotocol-pack: normalize italic formatting LorenzoPegorari
  2 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:45 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Fix "pronoun-antecedent agreement" errors.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index 837b691c89..9952fac188 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -65,7 +65,7 @@ Extra Parameters
 ----------------
 
 The protocol provides a mechanism in which clients can send additional
-information in its first message to the server. These are called "Extra
+information in their first message to the server. These are called "Extra
 Parameters", and are supported by the Git, SSH, and HTTP protocols.
 
 Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
@@ -277,7 +277,7 @@ out of what the server said it could do with the first 'want' line.
   filter-request    =  PKT-LINE("filter" SP filter-spec)
 ----
 
-Clients MUST send all the obj-ids it wants from the reference
+Clients MUST send all the obj-ids they want from the reference
 discovery phase as 'want' lines. Clients MUST send at least one
 'want' command in the request body. Clients MUST NOT mention an
 obj-id in a 'want' command which did not appear in the response
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* [GSoC PATCH v3 2/3] doc: gitprotocol-pack: improve paragraphs structure
  2026-03-03  1:45   ` [GSoC PATCH v3 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  2026-03-03  1:45     ` [GSoC PATCH v3 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
@ 2026-03-03  1:46     ` LorenzoPegorari
  2026-03-03  1:46     ` [GSoC PATCH v3 3/3] doc: gitprotocol-pack: normalize italic formatting LorenzoPegorari
  2 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:46 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Logically separate the introductory sentence from the first transport
description to improve readability and structural clarity.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index 9952fac188..f4c9e024b0 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -47,7 +47,9 @@ process defined in this protocol is terminated.
 Transports
 ----------
 There are three transports over which the packfile protocol is
-initiated.  The Git transport is a simple, unauthenticated server that
+initiated.
+
+The Git transport is a simple, unauthenticated server that
 takes the command (almost always 'upload-pack', though Git
 servers can be configured to be globally writable, in which 'receive-
 pack' initiation is also allowed) with which the client wishes to
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* [GSoC PATCH v3 3/3] doc: gitprotocol-pack: normalize italic formatting
  2026-03-03  1:45   ` [GSoC PATCH v3 0/3] doc: improve gitprotocol-pack LorenzoPegorari
  2026-03-03  1:45     ` [GSoC PATCH v3 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
  2026-03-03  1:46     ` [GSoC PATCH v3 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
@ 2026-03-03  1:46     ` LorenzoPegorari
  2 siblings, 0 replies; 15+ messages in thread
From: LorenzoPegorari @ 2026-03-03  1:46 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano

Uniform italic style usage for command and process names.

Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
---
 Documentation/gitprotocol-pack.adoc | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/gitprotocol-pack.adoc b/Documentation/gitprotocol-pack.adoc
index f4c9e024b0..633deecf2d 100644
--- a/Documentation/gitprotocol-pack.adoc
+++ b/Documentation/gitprotocol-pack.adoc
@@ -117,7 +117,7 @@ process on the server side over the Git protocol is this:
 SSH Transport
 -------------
 
-Initiating the upload-pack or receive-pack processes over SSH is
+Initiating the 'upload-pack' or 'receive-pack' processes over SSH is
 executing the binary on the server via SSH remote execution.
 It is basically equivalent to running this:
 
@@ -131,7 +131,7 @@ two commands, or even just one of them.
 
 In an ssh:// format URI, it's absolute in the URI, so the '/' after
 the host name (or port number) is sent as an argument, which is then
-read by the remote git-upload-pack exactly as is, so it's effectively
+read by the remote 'git-upload-pack' exactly as is, so it's effectively
 an absolute path in the remote filesystem.
 
        git clone ssh://user@example.com/project.git
@@ -163,7 +163,7 @@ supports passing environment variables as an argument.
 
 A few things to remember here:
 
-- The "command name" is spelled with dash (e.g. git-upload-pack), but
+- The "command name" is spelled with dash (e.g. 'git-upload-pack'), but
   this can be overridden by the client;
 
 - The repository path is always quoted with single quotes.
@@ -377,10 +377,10 @@ In multi_ack_detailed mode:
 
 Without either multi_ack or multi_ack_detailed:
 
- * upload-pack sends "ACK obj-id" on the first common object it finds.
+ * 'upload-pack' sends "ACK obj-id" on the first common object it finds.
    After that it says nothing until the client gives it a "done".
 
- * upload-pack sends "NAK" on a flush-pkt if no common object
+ * 'upload-pack' sends "NAK" on a flush-pkt if no common object
    has been found yet.  If one has been found, and thus an ACK
    was already sent, it's silent on the flush-pkt.
 
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 15+ messages in thread

* Re: [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting
  2026-03-03  1:26     ` Lorenzo Pegorari
@ 2026-03-03  1:48       ` Junio C Hamano
  0 siblings, 0 replies; 15+ messages in thread
From: Junio C Hamano @ 2026-03-03  1:48 UTC (permalink / raw)
  To: Lorenzo Pegorari; +Cc: git

Lorenzo Pegorari <lorenzo.pegorari2002@gmail.com> writes:

>> > -Initiating the upload-pack or receive-pack processes over SSH is
>> > +Initiating the 'upload-pack' or 'receive-pack' processes over SSH is
>> 
>> These are not `backquoted` for <tt>teletype text</tt> typesetting,
>> like the other hunks in this patch do?
>> 
>> All other things in these three patches I found them reasonable,
>> except for this hunk.
>> 
>> Thanks.
>
> Thank you so much for catching all my mistakes Junio.
>
> I misread the existing formatting: I mistook the apostrophes for
> backticks, and so I incorrectly assumed that the document used inline
> code for command and process names. In reality, the rest of the document
> uses italics for these elements.
>
> I'm sending a v2 where I correctly uniform command and process names to
> use the italic style ASAP.

Sorry but I am confused.  

I am not sure we want <em>emphasis</em> for most of these things;
when we spell names of commands that users would type literally, in
which case we would do the <tt>monospaced</tt>, no?

I may be way off, though.  I'd appreciate our Doc experts to inject
a bit of sanity.

Thanks.






^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2026-03-03  1:48 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-03-02 16:09 [GSoC PATCH 0/3] doc: improve gitprotocol-pack LorenzoPegorari
2026-03-02 16:10 ` [GSoC PATCH 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
2026-03-02 16:10 ` [GSoC PATCH 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
2026-03-02 16:10 ` [GSoC PATCH 3/3] doc: gitprotocol-pack: normalize inline code formatting LorenzoPegorari
2026-03-02 23:01   ` Junio C Hamano
2026-03-03  1:26     ` Lorenzo Pegorari
2026-03-03  1:48       ` Junio C Hamano
2026-03-03  1:34 ` [GSoC PATCH v2 0/3] doc: improve gitprotocol-pack LorenzoPegorari
2026-03-03  1:34   ` [GSoC PATCH v2 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
2026-03-03  1:35   ` [GSoC PATCH v2 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
2026-03-03  1:38   ` [GSoC PATCH v2 3/3] doc: gitprotocol-pack: normalize italic formatting LorenzoPegorari
2026-03-03  1:45   ` [GSoC PATCH v3 0/3] doc: improve gitprotocol-pack LorenzoPegorari
2026-03-03  1:45     ` [GSoC PATCH v3 1/3] doc: gitprotocol-pack: fix pronoun-antecedent agreement LorenzoPegorari
2026-03-03  1:46     ` [GSoC PATCH v3 2/3] doc: gitprotocol-pack: improve paragraphs structure LorenzoPegorari
2026-03-03  1:46     ` [GSoC PATCH v3 3/3] doc: gitprotocol-pack: normalize italic formatting LorenzoPegorari

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.