[PATCH] doc: flock of small fixes to various documentation files

[PATCH] doc: flock of small fixes to various documentation files

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

While translating the Git documentation into French, I noticed several small
issues in various files. This commit addresses these issues to improve the
overall quality and consistency of the documentation.

 * enforce consistent imperative mood in option descriptions
 * lighten wording in several places for clarity
 * add missing parameters
 * fix minor asciidoc markup issues

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
    doc: flock of small fixes to various documentation files

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2016/jnavila/doc_small_fixups-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2016

 Documentation/git-checkout.adoc   |  2 +-
 Documentation/git-rebase.adoc     |  2 +-
 Documentation/git-repack.adoc     |  6 +++---
 Documentation/git-send-email.adoc | 26 +++++++++++++-------------
 Documentation/git-worktree.adoc   |  2 +-
 5 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 6f281b298e..43ccf47cf6 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION
 -----------------------
 
 When you run `git checkout <something>`, Git tries to guess whether
-`<something>` is intended to be a branch, a commit, or a set of file(s),
+_<something>_ is intended to be a branch, a commit, or a set of file(s),
 and then either switches to that branch or commit, or restores the
 specified files.
 
diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index 9742833ebe..e177808004 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc
@@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still
 point to that commit at the end of the rebase if other commands that change
 `ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch
 tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,
-see linkgit:gitrevisions[7].
+see linkgit:gitrevisions[7]).
 
 TRANSPLANTING A TOPIC BRANCH WITH --ONTO
 ----------------------------------------
diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc
index d12c4985f6..673ce91083 100644
--- a/Documentation/git-repack.adoc
+++ b/Documentation/git-repack.adoc
@@ -77,14 +77,14 @@ to the new separate pack will be written.
 	Only useful with `--cruft -d`.
 
 --max-cruft-size=<n>::
-	Overrides `--max-pack-size` for cruft packs. Inherits the value of
+	Override `--max-pack-size` for cruft packs. Inherits the value of
 	`--max-pack-size` (if any) by default. See the documentation for
 	`--max-pack-size` for more details.
 
 --combine-cruft-below-size=<n>::
 	When generating cruft packs without pruning, only repack
-	existing cruft packs whose size is strictly less than `<n>`,
-	where `<n>` represents a number of bytes, which can optionally
+	existing cruft packs whose size is strictly less than `<n>`
+	bytes, which can optionally
 	be suffixed with "k", "m", or "g". Cruft packs whose size is
 	greater than or equal to `<n>` are left as-is and not repacked.
 	Useful when you want to avoid repacking large cruft pack(s) in
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 263b977353..cdaf421cda 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -208,7 +208,7 @@ Sending
 	for your own case. Default is the value of `sendemail.smtpEncryption`.
 
 --smtp-domain=<FQDN>::
-	Specifies the Fully Qualified Domain Name (FQDN) used in the
+	Specify the Fully Qualified Domain Name (FQDN) used in the
 	HELO/EHLO command to the SMTP server.  Some servers require the
 	FQDN to match your IP address.  If not set, `git send-email` attempts
 	to determine your FQDN automatically.  Default is the value of
@@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].
 	Disable SMTP authentication. Short hand for `--smtp-auth=none`.
 
 --smtp-server=<host>::
-	If set, specifies the outgoing SMTP server to use (e.g.
+	Specify the outgoing SMTP server to use (e.g.
 	`smtp.example.com` or a raw IP address).  If unspecified, and if
 	`--sendmail-cmd` is also unspecified, the default is to search
 	for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a
@@ -258,7 +258,7 @@ command names.  For those use cases, consider using `--sendmail-cmd`
 instead.
 
 --smtp-server-port=<port>::
-	Specifies a port different from the default port (SMTP
+	Specify a port different from the default port (SMTP
 	servers typically listen to smtp port 25, but may also listen to
 	submission port 587, or the common SSL smtp port 465);
 	symbolic port names (e.g. `submission` instead of 587)
@@ -266,7 +266,7 @@ instead.
 	`sendemail.smtpServerPort` configuration variable.
 
 --smtp-server-option=<option>::
-	If set, specifies the outgoing SMTP server option to use.
+	Specify the outgoing SMTP server option to use.
 	Default value can be specified by the `sendemail.smtpServerOption`
 	configuration option.
 +
@@ -277,7 +277,7 @@ must be used for each option.
 --smtp-ssl::
 	Legacy alias for `--smtp-encryption ssl`.
 
---smtp-ssl-cert-path::
+--smtp-ssl-cert-path <path>::
 	Path to a store of trusted CA certificates for SMTP SSL/TLS
 	certificate validation (either a directory that has been processed
 	by `c_rehash`, or a single file containing one or more PEM format
@@ -347,11 +347,11 @@ Automating
 --no-to::
 --no-cc::
 --no-bcc::
-	Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously
+	Clear any list of `To:`, `Cc:`, `Bcc:` addresses previously
 	set via config.
 
 --no-identity::
-	Clears the previously read value of `sendemail.identity` set
+	Clear the previously read value of `sendemail.identity` set
 	via config, if any.
 
 --to-cmd=<command>::
@@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.
 	Currently, validation means the following:
 +
 --
-		*	Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
-		*	Warn of patches that contain lines longer than
-			998 characters unless a suitable transfer encoding
-			(`auto`, `base64`, or `quoted-printable`) is used;
-			this is due to SMTP limits as described by
-			https://www.ietf.org/rfc/rfc5322.txt.
+* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
+* Warn of patches that contain lines longer than
+  998 characters unless a suitable transfer encoding
+  (`auto`, `base64`, or `quoted-printable`) is used;
+  this is due to SMTP limits as described by
+  https://www.ietf.org/rfc/rfc5322.txt.
 --
 +
 Default is the value of `sendemail.validate`; if this is not set,
diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index f272f79783..d74ad7b0e9 100644
--- a/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc
@@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after
 passed to the command. In the event the repository has a remote and
 `--guess-remote` is used, but no remote or local branches exist, then the
 command fails with a warning reminding the user to fetch from their remote
-first (or override by using `-f/--force`).
+first (or override by using `-f`/`--force`).
 
 `list`::
 

base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b
-- 
gitgitgadget

Re: [PATCH] doc: flock of small fixes to various documentation files

[Kristoffer Haugsbakk]

> [PATCH] doc: flock of small fixes to various documentation files

This doesn’t say much.

On Mon, Dec 15, 2025, at 21:23, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> While translating the Git documentation into French, I noticed several small
> issues in various files. This commit addresses these issues to improve the
> overall quality and consistency of the documentation.

This paragraph doesn’t add any relevant information. The following
bullet list would be fine on its own. That it was stumbled upon while
doing X is typical below the three-dash/hyphen line info.

Any code/doc change aims to improve the overall quality.

>  * enforce consistent imperative mood in option descriptions
>  * lighten wording in several places for clarity
>  * add missing parameters
>  * fix minor asciidoc markup issues

I also use bullet-list commits sometimes. (And it’s cousin: “Let’s
also...”) But this commit does two things:

• Change prose: imperative mood, lighten wording
• Fix mistakes source formatting:
  • Correct markup
  • Add missing paren
  • Split up markup of options: `-f`/`--force`
  • Weird indent

Could this fruitfully be split into at least two commits?

I just think these are two different categories.

Is that just an academic concern? Well, in my experience it is very
pleasant to pickaxe through a snippet of text, stumble upon clearly
marked commits like

• Use USA spelling
• Fix articles (the/a/an)
• *: typos

and just race past them. Because I am looking for the original
motivation for some phrasing (say), typos and missing articles and all,
and these commits are simple to bunny hop. But here, fixing a missing
parentheses is mixed together with

    Replace: less than `<n>`, where `<n>` represents a number of bytes,
    With: less than `<n>` bytes

And now I might have to pause and think which implicated change this is
about for my purposes; a subjective-but-good change or a
fix-objective-mistake change. Because that matters when I want to know
why the text is phrased in a certain way.

>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>     doc: flock of small fixes to various documentation files
>
> Published-As:
> https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git
> pr-2016/jnavila/doc_small_fixups-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/2016
>
>  Documentation/git-checkout.adoc   |  2 +-
>  Documentation/git-rebase.adoc     |  2 +-
>  Documentation/git-repack.adoc     |  6 +++---
>  Documentation/git-send-email.adoc | 26 +++++++++++++-------------
>  Documentation/git-worktree.adoc   |  2 +-
>  5 files changed, 19 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 6f281b298e..43ccf47cf6 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/Documentation/git-checkout.adoc
> @@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION
>  -----------------------
>
>  When you run `git checkout <something>`, Git tries to guess whether
> -`<something>` is intended to be a branch, a commit, or a set of file(s),
> +_<something>_ is intended to be a branch, a commit, or a set of file(s),
>  and then either switches to that branch or commit, or restores the
>  specified files.

Correct markup since this is a `synopsis` document. Good.

>
> diff --git a/Documentation/git-rebase.adoc
> b/Documentation/git-rebase.adoc
> index 9742833ebe..e177808004 100644
> --- a/Documentation/git-rebase.adoc
> +++ b/Documentation/git-rebase.adoc
> @@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is
> not guaranteed to still
>  point to that commit at the end of the rebase if other commands that
> change
>  `ORIG_HEAD` (like `git reset`) are used during the rebase. The
> previous branch
>  tip, however, is accessible using the reflog of the current branch
> (i.e. `@{1}`,
> -see linkgit:gitrevisions[7].
> +see linkgit:gitrevisions[7]).

Add missing end-paren. Good.

*Could* maybe also replace the comma with a semicolon?

    i.e. `@{1}`; see ...

>
>  TRANSPLANTING A TOPIC BRANCH WITH --ONTO
>  ----------------------------------------
> diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc
> index d12c4985f6..673ce91083 100644
> --- a/Documentation/git-repack.adoc
> +++ b/Documentation/git-repack.adoc
> @@ -77,14 +77,14 @@ to the new separate pack will be written.
>  	Only useful with `--cruft -d`.
>
>  --max-cruft-size=<n>::
> -	Overrides `--max-pack-size` for cruft packs. Inherits the value of
> +	Override `--max-pack-size` for cruft packs. Inherits the value of
>  	`--max-pack-size` (if any) by default. See the documentation for
>  	`--max-pack-size` for more details.

Imperative mood.

>
>  --combine-cruft-below-size=<n>::
>  	When generating cruft packs without pruning, only repack
> -	existing cruft packs whose size is strictly less than `<n>`,
> -	where `<n>` represents a number of bytes, which can optionally
> +	existing cruft packs whose size is strictly less than `<n>`
> +	bytes, which can optionally
>  	be suffixed with "k", "m", or "g". Cruft packs whose size is
>  	greater than or equal to `<n>` are left as-is and not repacked.
>  	Useful when you want to avoid repacking large cruft pack(s) in

Here drop a wordy “where `<n>` represents a number of bytes” clause in
favor of just “<n> bytes”.

> diff --git a/Documentation/git-send-email.adoc
> b/Documentation/git-send-email.adoc
> index 263b977353..cdaf421cda 100644
> --- a/Documentation/git-send-email.adoc
> +++ b/Documentation/git-send-email.adoc
> @@ -208,7 +208,7 @@ Sending
>  	for your own case. Default is the value of `sendemail.smtpEncryption`.
>
>  --smtp-domain=<FQDN>::
> -	Specifies the Fully Qualified Domain Name (FQDN) used in the
> +	Specify the Fully Qualified Domain Name (FQDN) used in the
>  	HELO/EHLO command to the SMTP server.  Some servers require the
>  	FQDN to match your IP address.  If not set, `git send-email` attempts
>  	to determine your FQDN automatically.  Default is the value of

Imperative mood.

> @@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].
>  	Disable SMTP authentication. Short hand for `--smtp-auth=none`.
>
>  --smtp-server=<host>::
> -	If set, specifies the outgoing SMTP server to use (e.g.
> +	Specify the outgoing SMTP server to use (e.g.
>  	`smtp.example.com` or a raw IP address).  If unspecified, and if
>  	`--sendmail-cmd` is also unspecified, the default is to search
>  	for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a
> @@ -258,7 +258,7 @@ command names.  For those use cases, consider using

Imperative mood and drop “If set”.

We can see in the resulting file that many commands use this “Specify”
start. Not a mix of “Specify” and “If set, ...”.

Although see also the positive/negative options that start with “If this
is set,”. Maybe unrelated to this change, but maybe they could be
rephrased with less “if set” ceremony. Relevant:

https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/

> `--sendmail-cmd`
>  instead.
>
>  --smtp-server-port=<port>::
> -	Specifies a port different from the default port (SMTP
> +	Specify a port different from the default port (SMTP

Same.

>  	servers typically listen to smtp port 25, but may also listen to
>  	submission port 587, or the common SSL smtp port 465);
>  	symbolic port names (e.g. `submission` instead of 587)
> @@ -266,7 +266,7 @@ instead.
>  	`sendemail.smtpServerPort` configuration variable.
>
>  --smtp-server-option=<option>::
> -	If set, specifies the outgoing SMTP server option to use.
> +	Specify the outgoing SMTP server option to use.

Same.

>  	Default value can be specified by the `sendemail.smtpServerOption`
>  	configuration option.
>  +
> @@ -277,7 +277,7 @@ must be used for each option.
>  --smtp-ssl::
>  	Legacy alias for `--smtp-encryption ssl`.
>
> ---smtp-ssl-cert-path::
> +--smtp-ssl-cert-path <path>::
>  	Path to a store of trusted CA certificates for SMTP SSL/TLS
>  	certificate validation (either a directory that has been processed
>  	by `c_rehash`, or a single file containing one or more PEM format

Add parameter. Makes sense.

> @@ -347,11 +347,11 @@ Automating
>  --no-to::
>  --no-cc::
>  --no-bcc::
> -	Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously
> +	Clear any list of `To:`, `Cc:`, `Bcc:` addresses previously
>  	set via config.

Imperative mood.

>
>  --no-identity::
> -	Clears the previously read value of `sendemail.identity` set
> +	Clear the previously read value of `sendemail.identity` set

Ditto. And these two look like the only relevant `--no` options. So this
looks consistent.

>  	via config, if any.
>
>  --to-cmd=<command>::
> @@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.
>  	Currently, validation means the following:
>  +
>  --
> -		*	Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
> -		*	Warn of patches that contain lines longer than
> -			998 characters unless a suitable transfer encoding
> -			(`auto`, `base64`, or `quoted-printable`) is used;
> -			this is due to SMTP limits as described by
> -			https://www.ietf.org/rfc/rfc5322.txt.
> +* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
> +* Warn of patches that contain lines longer than
> +  998 characters unless a suitable transfer encoding
> +  (`auto`, `base64`, or `quoted-printable`) is used;
> +  this is due to SMTP limits as described by
> +  https://www.ietf.org/rfc/rfc5322.txt.
>  --

Non-functional change it seems. This looks better in the source. 2–3
tabs were not needed here.

>  +
>  Default is the value of `sendemail.validate`; if this is not set,
> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
> index f272f79783..d74ad7b0e9 100644
> --- a/Documentation/git-worktree.adoc
> +++ b/Documentation/git-worktree.adoc
> @@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after
>  passed to the command. In the event the repository has a remote and
>  `--guess-remote` is used, but no remote or local branches exist, then the
>  command fails with a warning reminding the user to fetch from their remote
> -first (or override by using `-f/--force`).
> +first (or override by using `-f`/`--force`).

Fix inline-verbatim since you are quoting two options/switches. So the
`/` does not go inside the (`). Good.

>
>  `list`::
>
>
> base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b
> --
> gitgitgadget

`doc-diff` also looks good.

Re: [PATCH] doc: flock of small fixes to various documentation files

[Jean-Noël Avila]

[-- Attachment #1: Type: text/plain, Size: 11968 bytes --]

Le 15/12/2025 à 23:50, Kristoffer Haugsbakk a écrit :
>> [PATCH] doc: flock of small fixes to various documentation files
> 
> This doesn’t say much.
> 

Yes, this is a set of disparate changes, except that they all relate to
documentation.

> On Mon, Dec 15, 2025, at 21:23, Jean-Noël Avila via GitGitGadget wrote:
>> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>>
>> While translating the Git documentation into French, I noticed several small
>> issues in various files. This commit addresses these issues to improve the
>> overall quality and consistency of the documentation.
> 
> This paragraph doesn’t add any relevant information. The following
> bullet list would be fine on its own. That it was stumbled upon while
> doing X is typical below the three-dash/hyphen line info.

True, will remove.

> 
> Any code/doc change aims to improve the overall quality.
> 
>>  * enforce consistent imperative mood in option descriptions
>>  * lighten wording in several places for clarity
>>  * add missing parameters
>>  * fix minor asciidoc markup issues
> 
> I also use bullet-list commits sometimes. (And it’s cousin: “Let’s
> also...”) But this commit does two things:
> 
> • Change prose: imperative mood, lighten wording
> • Fix mistakes source formatting:
>   • Correct markup
>   • Add missing paren
>   • Split up markup of options: `-f`/`--force`
>   • Weird indent
> 
> Could this fruitfully be split into at least two commits?
> 
> I just think these are two different categories.

For me these changes are so straightforward that splitting/grouping
seemed overkill. But, I understand your point. Style vs. pure formatting
is a good approach, even if here the style is not about the approach to
writing the documentation.

> 
> Is that just an academic concern? Well, in my experience it is very
> pleasant to pickaxe through a snippet of text, stumble upon clearly
> marked commits like
> 
> • Use USA spelling
> • Fix articles (the/a/an)
> • *: typos
> 
> and just race past them. Because I am looking for the original
> motivation for some phrasing (say), typos and missing articles and all,
> and these commits are simple to bunny hop. But here, fixing a missing
> parentheses is mixed together with
> 
>     Replace: less than `<n>`, where `<n>` represents a number of bytes,
>     With: less than `<n>` bytes
> 
> And now I might have to pause and think which implicated change this is
> about for my purposes; a subjective-but-good change or a
> fix-objective-mistake change. Because that matters when I want to know
> why the text is phrased in a certain way.
> 

OK, will split in two.

>>
>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>> ---
>>     doc: flock of small fixes to various documentation files
>>
>> Published-As:
>> https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v1
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git
>> pr-2016/jnavila/doc_small_fixups-v1
>> Pull-Request: https://github.com/gitgitgadget/git/pull/2016
>>
>>  Documentation/git-checkout.adoc   |  2 +-
>>  Documentation/git-rebase.adoc     |  2 +-
>>  Documentation/git-repack.adoc     |  6 +++---
>>  Documentation/git-send-email.adoc | 26 +++++++++++++-------------
>>  Documentation/git-worktree.adoc   |  2 +-
>>  5 files changed, 19 insertions(+), 19 deletions(-)
>>
>> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
>> index 6f281b298e..43ccf47cf6 100644
>> --- a/Documentation/git-checkout.adoc
>> +++ b/Documentation/git-checkout.adoc
>> @@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION
>>  -----------------------
>>
>>  When you run `git checkout <something>`, Git tries to guess whether
>> -`<something>` is intended to be a branch, a commit, or a set of file(s),
>> +_<something>_ is intended to be a branch, a commit, or a set of file(s),
>>  and then either switches to that branch or commit, or restores the
>>  specified files.
> 
> Correct markup since this is a `synopsis` document. Good.
> 
>>
>> diff --git a/Documentation/git-rebase.adoc
>> b/Documentation/git-rebase.adoc
>> index 9742833ebe..e177808004 100644
>> --- a/Documentation/git-rebase.adoc
>> +++ b/Documentation/git-rebase.adoc
>> @@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is
>> not guaranteed to still
>>  point to that commit at the end of the rebase if other commands that
>> change
>>  `ORIG_HEAD` (like `git reset`) are used during the rebase. The
>> previous branch
>>  tip, however, is accessible using the reflog of the current branch
>> (i.e. `@{1}`,
>> -see linkgit:gitrevisions[7].
>> +see linkgit:gitrevisions[7]).
> 
> Add missing end-paren. Good.
> 
> *Could* maybe also replace the comma with a semicolon?
> 
>     i.e. `@{1}`; see ...
> 
>>
>>  TRANSPLANTING A TOPIC BRANCH WITH --ONTO
>>  ----------------------------------------
>> diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc
>> index d12c4985f6..673ce91083 100644
>> --- a/Documentation/git-repack.adoc
>> +++ b/Documentation/git-repack.adoc
>> @@ -77,14 +77,14 @@ to the new separate pack will be written.
>>  	Only useful with `--cruft -d`.
>>
>>  --max-cruft-size=<n>::
>> -	Overrides `--max-pack-size` for cruft packs. Inherits the value of
>> +	Override `--max-pack-size` for cruft packs. Inherits the value of
>>  	`--max-pack-size` (if any) by default. See the documentation for
>>  	`--max-pack-size` for more details.
> 
> Imperative mood.
> 
>>
>>  --combine-cruft-below-size=<n>::
>>  	When generating cruft packs without pruning, only repack
>> -	existing cruft packs whose size is strictly less than `<n>`,
>> -	where `<n>` represents a number of bytes, which can optionally
>> +	existing cruft packs whose size is strictly less than `<n>`
>> +	bytes, which can optionally
>>  	be suffixed with "k", "m", or "g". Cruft packs whose size is
>>  	greater than or equal to `<n>` are left as-is and not repacked.
>>  	Useful when you want to avoid repacking large cruft pack(s) in
> 
> Here drop a wordy “where `<n>` represents a number of bytes” clause in
> favor of just “<n> bytes”.
> 
>> diff --git a/Documentation/git-send-email.adoc
>> b/Documentation/git-send-email.adoc
>> index 263b977353..cdaf421cda 100644
>> --- a/Documentation/git-send-email.adoc
>> +++ b/Documentation/git-send-email.adoc
>> @@ -208,7 +208,7 @@ Sending
>>  	for your own case. Default is the value of `sendemail.smtpEncryption`.
>>
>>  --smtp-domain=<FQDN>::
>> -	Specifies the Fully Qualified Domain Name (FQDN) used in the
>> +	Specify the Fully Qualified Domain Name (FQDN) used in the
>>  	HELO/EHLO command to the SMTP server.  Some servers require the
>>  	FQDN to match your IP address.  If not set, `git send-email` attempts
>>  	to determine your FQDN automatically.  Default is the value of
> 
> Imperative mood.
> 
>> @@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].
>>  	Disable SMTP authentication. Short hand for `--smtp-auth=none`.
>>
>>  --smtp-server=<host>::
>> -	If set, specifies the outgoing SMTP server to use (e.g.
>> +	Specify the outgoing SMTP server to use (e.g.
>>  	`smtp.example.com` or a raw IP address).  If unspecified, and if
>>  	`--sendmail-cmd` is also unspecified, the default is to search
>>  	for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a
>> @@ -258,7 +258,7 @@ command names.  For those use cases, consider using
> 
> Imperative mood and drop “If set”.
> 
> We can see in the resulting file that many commands use this “Specify”
> start. Not a mix of “Specify” and “If set, ...”.
> 
> Although see also the positive/negative options that start with “If this
> is set,”. Maybe unrelated to this change, but maybe they could be
> rephrased with less “if set” ceremony. Relevant:
> 
> https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
> 

Not the purpose of this commit, but maybe, it would make sense to stress
out that the first sentence for explaining an option should describe
bluntly its positive action expressed in imperative mood, with no
ceremony. After this first sentence, the negative equivalient, more
context, more precision or use cases can be described.

>> `--sendmail-cmd`
>>  instead.
>>
>>  --smtp-server-port=<port>::
>> -	Specifies a port different from the default port (SMTP
>> +	Specify a port different from the default port (SMTP
> 
> Same.
> 
>>  	servers typically listen to smtp port 25, but may also listen to
>>  	submission port 587, or the common SSL smtp port 465);
>>  	symbolic port names (e.g. `submission` instead of 587)
>> @@ -266,7 +266,7 @@ instead.
>>  	`sendemail.smtpServerPort` configuration variable.
>>
>>  --smtp-server-option=<option>::
>> -	If set, specifies the outgoing SMTP server option to use.
>> +	Specify the outgoing SMTP server option to use.
> 
> Same.
> 
>>  	Default value can be specified by the `sendemail.smtpServerOption`
>>  	configuration option.
>>  +
>> @@ -277,7 +277,7 @@ must be used for each option.
>>  --smtp-ssl::
>>  	Legacy alias for `--smtp-encryption ssl`.
>>
>> ---smtp-ssl-cert-path::
>> +--smtp-ssl-cert-path <path>::
>>  	Path to a store of trusted CA certificates for SMTP SSL/TLS
>>  	certificate validation (either a directory that has been processed
>>  	by `c_rehash`, or a single file containing one or more PEM format
> 
> Add parameter. Makes sense.
> 
>> @@ -347,11 +347,11 @@ Automating
>>  --no-to::
>>  --no-cc::
>>  --no-bcc::
>> -	Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously
>> +	Clear any list of `To:`, `Cc:`, `Bcc:` addresses previously
>>  	set via config.
> 
> Imperative mood.
> 
>>
>>  --no-identity::
>> -	Clears the previously read value of `sendemail.identity` set
>> +	Clear the previously read value of `sendemail.identity` set
> 
> Ditto. And these two look like the only relevant `--no` options. So this
> looks consistent.
> 
>>  	via config, if any.
>>
>>  --to-cmd=<command>::
>> @@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.
>>  	Currently, validation means the following:
>>  +
>>  --
>> -		*	Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
>> -		*	Warn of patches that contain lines longer than
>> -			998 characters unless a suitable transfer encoding
>> -			(`auto`, `base64`, or `quoted-printable`) is used;
>> -			this is due to SMTP limits as described by
>> -			https://www.ietf.org/rfc/rfc5322.txt.
>> +* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
>> +* Warn of patches that contain lines longer than
>> +  998 characters unless a suitable transfer encoding
>> +  (`auto`, `base64`, or `quoted-printable`) is used;
>> +  this is due to SMTP limits as described by
>> +  https://www.ietf.org/rfc/rfc5322.txt.
>>  --
> 
> Non-functional change it seems. This looks better in the source. 2–3
> tabs were not needed here.
> 

It turns out the tool to translate the manpages Po4a also dislikes (i.e.
does not interpret correctly) the tabs.

>>  +
>>  Default is the value of `sendemail.validate`; if this is not set,
>> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
>> index f272f79783..d74ad7b0e9 100644
>> --- a/Documentation/git-worktree.adoc
>> +++ b/Documentation/git-worktree.adoc
>> @@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after
>>  passed to the command. In the event the repository has a remote and
>>  `--guess-remote` is used, but no remote or local branches exist, then the
>>  command fails with a warning reminding the user to fetch from their remote
>> -first (or override by using `-f/--force`).
>> +first (or override by using `-f`/`--force`).
> 
> Fix inline-verbatim since you are quoting two options/switches. So the
> `/` does not go inside the (`). Good.
> 
>>
>>  `list`::
>>
>>
>> base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b
>> --
>> gitgitgadget
> 
> `doc-diff` also looks good.
> 

[-- Attachment #2: jean-noel_avila.vcf --]
[-- Type: text/vcard, Size: 464 bytes --]

begin:vcard
fn;quoted-printable:Jean-No=C3=ABl Avila
n;quoted-printable:Avila;Jean-No=C3=ABl
org:Scantech S.A.
adr;quoted-printable:Savoie Technolac BP 244;;B=C3=A2timent Androm=C3=A8de - 108 Avenue du Lac L=C3=A9man ; LA MOTTE SERVOLEX;;73290;France
email;internet:jean-noel.avila@scantech.com
title:Embedded systems manager
tel;work:+33 479 25 54 50
tel;cell:+33 633 04 64 18
x-mozilla-html:FALSE
url:http://www.scantech.com
version:2.1
end:vcard

Re: [PATCH] doc: flock of small fixes to various documentation files

[Kristoffer Haugsbakk]

On Wed, Dec 17, 2025, at 14:45, Jean-Noël Avila wrote:
> Le 15/12/2025 à 23:50, Kristoffer Haugsbakk a écrit :
>>[snip]
>>
>> Could this fruitfully be split into at least two commits?
>>
>> I just think these are two different categories.
>
> For me these changes are so straightforward that splitting/grouping
> seemed overkill. But, I understand your point. Style vs. pure formatting
> is a good approach, even if here the style is not about the approach to
> writing the documentation.
>
>>
>> Is that just an academic concern? Well, in my experience it is very
>> pleasant to pickaxe through a snippet of text, stumble upon clearly
>> marked commits like
>>
>> • Use USA spelling
>> • Fix articles (the/a/an)
>> • *: typos
>>
>> and just race past them. Because I am looking for the original
>> motivation for some phrasing (say), typos and missing articles and all,
>> and these commits are simple to bunny hop. But here, fixing a missing
>> parentheses is mixed together with
>>
>>     Replace: less than `<n>`, where `<n>` represents a number of bytes,
>>     With: less than `<n>` bytes
>>
>> And now I might have to pause and think which implicated change this is
>> about for my purposes; a subjective-but-good change or a
>> fix-objective-mistake change. Because that matters when I want to know
>> why the text is phrased in a certain way.
>>
>
> OK, will split in two.

Thanks. Your consideration of this point is enough for me. Appreciated.

>>[snip]
>>
>
> Not the purpose of this commit, but maybe, it would make sense to stress
> out that the first sentence for explaining an option should describe
> bluntly its positive action expressed in imperative mood, with no
> ceremony. After this first sentence, the negative equivalient, more
> context, more precision or use cases can be described.

That sounds excellent.

>[snip]

Re: [PATCH] doc: flock of small fixes to various documentation files

[Kristoffer Haugsbakk]

On Thu, Dec 18, 2025, at 09:05, Kristoffer Haugsbakk wrote:
>>[snip]

This is in `next` now anyway.

[PATCH v2 0/2] doc: flock of small fixes to various documentation files

[Jean-Noël Avila via GitGitGadget]

This second version only splits the changes in two commits, one addressing
asciidoc markup, the other fixing basic style issues.

Jean-Noël Avila (2):
  doc: fix asciidoc markup issues in several files
  doc: correct minor wording issues

 Documentation/git-checkout.adoc   |  2 +-
 Documentation/git-rebase.adoc     |  2 +-
 Documentation/git-repack.adoc     |  6 +++---
 Documentation/git-send-email.adoc | 26 +++++++++++++-------------
 Documentation/git-worktree.adoc   |  2 +-
 5 files changed, 19 insertions(+), 19 deletions(-)


base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2016/jnavila/doc_small_fixups-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2016

Range-diff vs v1:

 -:  ---------- > 1:  31694ab9d3 doc: fix asciidoc markup issues in several files
 1:  b88126ef60 ! 2:  a3a76d448a doc: flock of small fixes to various documentation files
     @@ Metadata
      Author: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Commit message ##
     -    doc: flock of small fixes to various documentation files
     +    doc: correct minor wording issues
      
     -    While translating the Git documentation into French, I noticed several small
     -    issues in various files. This commit addresses these issues to improve the
     -    overall quality and consistency of the documentation.
     -
     -     * enforce consistent imperative mood in option descriptions
     -     * lighten wording in several places for clarity
     -     * add missing parameters
     -     * fix minor asciidoc markup issues
     +    * use imperative mood for consistency in options descriptions
     +    * add missing parenthesis
     +    * reword verbose phrase in git-repack.adoc
      
          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
     - ## Documentation/git-checkout.adoc ##
     -@@ Documentation/git-checkout.adoc: ARGUMENT DISAMBIGUATION
     - -----------------------
     - 
     - When you run `git checkout <something>`, Git tries to guess whether
     --`<something>` is intended to be a branch, a commit, or a set of file(s),
     -+_<something>_ is intended to be a branch, a commit, or a set of file(s),
     - and then either switches to that branch or commit, or restores the
     - specified files.
     - 
     -
       ## Documentation/git-rebase.adoc ##
      @@ Documentation/git-rebase.adoc: of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still
       point to that commit at the end of the rebase if other commands that change
     @@ Documentation/git-send-email.adoc: instead.
       	Default value can be specified by the `sendemail.smtpServerOption`
       	configuration option.
       +
     -@@ Documentation/git-send-email.adoc: must be used for each option.
     - --smtp-ssl::
     - 	Legacy alias for `--smtp-encryption ssl`.
     - 
     ----smtp-ssl-cert-path::
     -+--smtp-ssl-cert-path <path>::
     - 	Path to a store of trusted CA certificates for SMTP SSL/TLS
     - 	certificate validation (either a directory that has been processed
     - 	by `c_rehash`, or a single file containing one or more PEM format
      @@ Documentation/git-send-email.adoc: Automating
       --no-to::
       --no-cc::
     @@ Documentation/git-send-email.adoc: Automating
       	via config, if any.
       
       --to-cmd=<command>::
     -@@ Documentation/git-send-email.adoc: have been specified, in which case default to `compose`.
     - 	Currently, validation means the following:
     - +
     - --
     --		*	Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
     --		*	Warn of patches that contain lines longer than
     --			998 characters unless a suitable transfer encoding
     --			(`auto`, `base64`, or `quoted-printable`) is used;
     --			this is due to SMTP limits as described by
     --			https://www.ietf.org/rfc/rfc5322.txt.
     -+* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
     -+* Warn of patches that contain lines longer than
     -+  998 characters unless a suitable transfer encoding
     -+  (`auto`, `base64`, or `quoted-printable`) is used;
     -+  this is due to SMTP limits as described by
     -+  https://www.ietf.org/rfc/rfc5322.txt.
     - --
     - +
     - Default is the value of `sendemail.validate`; if this is not set,
     -
     - ## Documentation/git-worktree.adoc ##
     -@@ Documentation/git-worktree.adoc: associated with a new unborn branch named _<branch>_ (after
     - passed to the command. In the event the repository has a remote and
     - `--guess-remote` is used, but no remote or local branches exist, then the
     - command fails with a warning reminding the user to fetch from their remote
     --first (or override by using `-f/--force`).
     -+first (or override by using `-f`/`--force`).
     - 
     - `list`::
     - 

-- 
gitgitgadget

[PATCH v2 1/2] doc: fix asciidoc markup issues in several files

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

* fix incorrect use of backticks for markup in
  git-checkout.adoc, git-worktree.adoc
* switch tabs to spaces	in git-send-email.adoc list items

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-checkout.adoc   |  2 +-
 Documentation/git-send-email.adoc | 14 +++++++-------
 Documentation/git-worktree.adoc   |  2 +-
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 6f281b298e..43ccf47cf6 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION
 -----------------------
 
 When you run `git checkout <something>`, Git tries to guess whether
-`<something>` is intended to be a branch, a commit, or a set of file(s),
+_<something>_ is intended to be a branch, a commit, or a set of file(s),
 and then either switches to that branch or commit, or restores the
 specified files.
 
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 263b977353..caf9d693a3 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -277,7 +277,7 @@ must be used for each option.
 --smtp-ssl::
 	Legacy alias for `--smtp-encryption ssl`.
 
---smtp-ssl-cert-path::
+--smtp-ssl-cert-path <path>::
 	Path to a store of trusted CA certificates for SMTP SSL/TLS
 	certificate validation (either a directory that has been processed
 	by `c_rehash`, or a single file containing one or more PEM format
@@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.
 	Currently, validation means the following:
 +
 --
-		*	Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
-		*	Warn of patches that contain lines longer than
-			998 characters unless a suitable transfer encoding
-			(`auto`, `base64`, or `quoted-printable`) is used;
-			this is due to SMTP limits as described by
-			https://www.ietf.org/rfc/rfc5322.txt.
+* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
+* Warn of patches that contain lines longer than
+  998 characters unless a suitable transfer encoding
+  (`auto`, `base64`, or `quoted-printable`) is used;
+  this is due to SMTP limits as described by
+  https://www.ietf.org/rfc/rfc5322.txt.
 --
 +
 Default is the value of `sendemail.validate`; if this is not set,
diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index f272f79783..d74ad7b0e9 100644
--- a/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc
@@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after
 passed to the command. In the event the repository has a remote and
 `--guess-remote` is used, but no remote or local branches exist, then the
 command fails with a warning reminding the user to fetch from their remote
-first (or override by using `-f/--force`).
+first (or override by using `-f`/`--force`).
 
 `list`::
 
-- 
gitgitgadget

[PATCH v2 2/2] doc: correct minor wording issues

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

* use imperative mood for consistency in options descriptions
* add missing parenthesis
* reword verbose phrase in git-repack.adoc

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-rebase.adoc     |  2 +-
 Documentation/git-repack.adoc     |  6 +++---
 Documentation/git-send-email.adoc | 12 ++++++------
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index 9742833ebe..e177808004 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc
@@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still
 point to that commit at the end of the rebase if other commands that change
 `ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch
 tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,
-see linkgit:gitrevisions[7].
+see linkgit:gitrevisions[7]).
 
 TRANSPLANTING A TOPIC BRANCH WITH --ONTO
 ----------------------------------------
diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc
index d12c4985f6..673ce91083 100644
--- a/Documentation/git-repack.adoc
+++ b/Documentation/git-repack.adoc
@@ -77,14 +77,14 @@ to the new separate pack will be written.
 	Only useful with `--cruft -d`.
 
 --max-cruft-size=<n>::
-	Overrides `--max-pack-size` for cruft packs. Inherits the value of
+	Override `--max-pack-size` for cruft packs. Inherits the value of
 	`--max-pack-size` (if any) by default. See the documentation for
 	`--max-pack-size` for more details.
 
 --combine-cruft-below-size=<n>::
 	When generating cruft packs without pruning, only repack
-	existing cruft packs whose size is strictly less than `<n>`,
-	where `<n>` represents a number of bytes, which can optionally
+	existing cruft packs whose size is strictly less than `<n>`
+	bytes, which can optionally
 	be suffixed with "k", "m", or "g". Cruft packs whose size is
 	greater than or equal to `<n>` are left as-is and not repacked.
 	Useful when you want to avoid repacking large cruft pack(s) in
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index caf9d693a3..cdaf421cda 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -208,7 +208,7 @@ Sending
 	for your own case. Default is the value of `sendemail.smtpEncryption`.
 
 --smtp-domain=<FQDN>::
-	Specifies the Fully Qualified Domain Name (FQDN) used in the
+	Specify the Fully Qualified Domain Name (FQDN) used in the
 	HELO/EHLO command to the SMTP server.  Some servers require the
 	FQDN to match your IP address.  If not set, `git send-email` attempts
 	to determine your FQDN automatically.  Default is the value of
@@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].
 	Disable SMTP authentication. Short hand for `--smtp-auth=none`.
 
 --smtp-server=<host>::
-	If set, specifies the outgoing SMTP server to use (e.g.
+	Specify the outgoing SMTP server to use (e.g.
 	`smtp.example.com` or a raw IP address).  If unspecified, and if
 	`--sendmail-cmd` is also unspecified, the default is to search
 	for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a
@@ -258,7 +258,7 @@ command names.  For those use cases, consider using `--sendmail-cmd`
 instead.
 
 --smtp-server-port=<port>::
-	Specifies a port different from the default port (SMTP
+	Specify a port different from the default port (SMTP
 	servers typically listen to smtp port 25, but may also listen to
 	submission port 587, or the common SSL smtp port 465);
 	symbolic port names (e.g. `submission` instead of 587)
@@ -266,7 +266,7 @@ instead.
 	`sendemail.smtpServerPort` configuration variable.
 
 --smtp-server-option=<option>::
-	If set, specifies the outgoing SMTP server option to use.
+	Specify the outgoing SMTP server option to use.
 	Default value can be specified by the `sendemail.smtpServerOption`
 	configuration option.
 +
@@ -347,11 +347,11 @@ Automating
 --no-to::
 --no-cc::
 --no-bcc::
-	Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously
+	Clear any list of `To:`, `Cc:`, `Bcc:` addresses previously
 	set via config.
 
 --no-identity::
-	Clears the previously read value of `sendemail.identity` set
+	Clear the previously read value of `sendemail.identity` set
 	via config, if any.
 
 --to-cmd=<command>::
-- 
gitgitgadget

Re: [PATCH v2 0/2] doc: flock of small fixes to various documentation files

[Kristoffer Haugsbakk]

On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:
> This second version only splits the changes in two commits, one addressing
> asciidoc markup, the other fixing basic style issues.
>[snip]
> Range-diff vs v1:
>
>  -:  ---------- > 1:  31694ab9d3 doc: fix asciidoc markup issues in 
> several files
>  1:  b88126ef60 ! 2:  a3a76d448a doc: flock of small fixes to various 
> documentation files
>      @@ Metadata
>       Author: Jean-Noël Avila <jn.avila@free.fr>
>      
>        ## Commit message ##
>      -    doc: flock of small fixes to various documentation files
>      +    doc: correct minor wording issues
>      
>      -    While translating the Git documentation into French, I 
> noticed several small
>      -    issues in various files. This commit addresses these issues 
> to improve the
>      -    overall quality and consistency of the documentation.
>      -
>      -     * enforce consistent imperative mood in option descriptions
>      -     * lighten wording in several places for clarity
>      -     * add missing parameters
>      -     * fix minor asciidoc markup issues
>      +    * use imperative mood for consistency in options descriptions
>      +    * add missing parenthesis
>      +    * reword verbose phrase in git-repack.adoc
>      
>           Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>      
>      - ## Documentation/git-checkout.adoc ##
>      -@@ Documentation/git-checkout.adoc: ARGUMENT DISAMBIGUATION
>      - -----------------------
>      - 
>      - When you run `git checkout <something>`, Git tries to guess 
> whether
>      --`<something>` is intended to be a branch, a commit, or a set of 
> file(s),
>      -+_<something>_ is intended to be a branch, a commit, or a set of 
> file(s),
>      - and then either switches to that branch or commit, or restores 
> the
>      - specified files.
>      - 
>      -
>        ## Documentation/git-rebase.adoc ##
>       @@ Documentation/git-rebase.adoc: of the to-be-rebased branch. 
> However, `ORIG_HEAD` is not guaranteed to still
>        point to that commit at the end of the rebase if other commands 
> that change
>      @@ Documentation/git-send-email.adoc: instead.
>        	Default value can be specified by the 
> `sendemail.smtpServerOption`
>        	configuration option.
>        +
>      -@@ Documentation/git-send-email.adoc: must be used for each 
> option.
>      - --smtp-ssl::
>      - 	Legacy alias for `--smtp-encryption ssl`.
>      - 
>      ----smtp-ssl-cert-path::
>      -+--smtp-ssl-cert-path <path>::
>      - 	Path to a store of trusted CA certificates for SMTP SSL/TLS
>      - 	certificate validation (either a directory that has been 
> processed
>      - 	by `c_rehash`, or a single file containing one or more PEM 
> format
>       @@ Documentation/git-send-email.adoc: Automating
>        --no-to::
>        --no-cc::
>      @@ Documentation/git-send-email.adoc: Automating
>        	via config, if any.
>       
>        --to-cmd=<command>::
>      -@@ Documentation/git-send-email.adoc: have been specified, in 
> which case default to `compose`.
>      - 	Currently, validation means the following:
>      - +
>      - --
>      --		*	Invoke the sendemail-validate hook if present (see 
> linkgit:githooks[5]).
>      --		*	Warn of patches that contain lines longer than
>      --			998 characters unless a suitable transfer encoding
>      --			(`auto`, `base64`, or `quoted-printable`) is used;
>      --			this is due to SMTP limits as described by
>      --			https://www.ietf.org/rfc/rfc5322.txt.
>      -+* Invoke the sendemail-validate hook if present (see 
> linkgit:githooks[5]).
>      -+* Warn of patches that contain lines longer than
>      -+  998 characters unless a suitable transfer encoding
>      -+  (`auto`, `base64`, or `quoted-printable`) is used;
>      -+  this is due to SMTP limits as described by
>      -+  https://www.ietf.org/rfc/rfc5322.txt.
>      - --
>      - +
>      - Default is the value of `sendemail.validate`; if this is not set,
>      -
>      - ## Documentation/git-worktree.adoc ##
>      -@@ Documentation/git-worktree.adoc: associated with a new unborn 
> branch named _<branch>_ (after
>      - passed to the command. In the event the repository has a remote 
> and
>      - `--guess-remote` is used, but no remote or local branches exist, 
> then the
>      - command fails with a warning reminding the user to fetch from 
> their remote
>      --first (or override by using `-f/--force`).
>      -+first (or override by using `-f`/`--force`).
>      - 
>      - `list`::
>      - 
>
> -- 
> gitgitgadget

Naturally a misleading range-diff. It’s the same change as last
round but split up into two commits.

This looks good to me. Thanks!

Re: [PATCH v2 2/2] doc: correct minor wording issues

[Kristoffer Haugsbakk]

On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> * use imperative mood for consistency in options descriptions
> * add missing parenthesis
> * reword verbose phrase in git-repack.adoc
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>

I have reviewed these changes in v1 since the changes are the same but
split into two commits instead of one.

Acked-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

Re: [PATCH v2 1/2] doc: fix asciidoc markup issues in several files

[Kristoffer Haugsbakk]

On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> * fix incorrect use of backticks for markup in
>   git-checkout.adoc, git-worktree.adoc
> * switch tabs to spaces	in git-send-email.adoc list items
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>

I have reviewed these changes in v1 since the changes are the same but
split into two commits instead of one.

Beyond what the commit message says the only other thing is:

>[snip]
> ---smtp-ssl-cert-path::
> +--smtp-ssl-cert-path <path>::
>  	Path to a store of trusted CA certificates for SMTP SSL/TLS
>  	certificate validation (either a directory that has been processed
>  	by `c_rehash`, or a single file containing one or more PEM format

I only mention this for completeness (of the review).

Acked-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

Re: [PATCH v2 2/2] doc: correct minor wording issues

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:
>> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>>
>> * use imperative mood for consistency in options descriptions
>> * add missing parenthesis
>> * reword verbose phrase in git-repack.adoc
>>
>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>
> I have reviewed these changes in v1 since the changes are the same but
> split into two commits instead of one.
>
> Acked-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

Thanks for reviewing.

I've also reviewed the v2 hours ago and the patches are now already
in 'next'.