doc: flock of small fixes to various documentation files

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

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

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 <[email protected]>

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

Documentation/git-checkout.adoc +0 -0

index 6f281b298e..43ccf47cf6 100644

Documentation/git-rebase.adoc +0 -0

index 9742833ebe..e177808004 100644
@@ -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},

TRANSPLANTING A TOPIC BRANCH WITH --ONTO
----------------------------------------

Documentation/git-repack.adoc +0 -0

index d12c4985f6..673ce91083 100644

Documentation/git-send-email.adoc +0 -0

index 263b977353..cdaf421cda 100644

Documentation/git-send-email.adoc +0 -3

 	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

Documentation/git-worktree.adoc +0 -0

 `list`::
 
 

base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b --
gitgitgadget

Quoted 1 line

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

This doesn’t say much.

Quoted 5 lines

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

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.

Quoted 4 lines

* 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.

Quoted 23 lines

Signed-off-by Jean-Noël Avila <[email protected]>

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

Documentation/git-checkout.adoc +0 -0

index 6f281b298e..43ccf47cf6 100644

Documentation/git-checkout.adoc ARGUMENT DISAMBIGUATION · line 514

Quoted 7 lines

Documentation/git-checkout.adoc +1 -1

@@ -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.

Quoted 14 lines

Documentation/git-rebase.adoc +0 -0

index 9742833ebe..e177808004 100644
@@ -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},

Documentation/git-rebase.adoc of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still · line 90

Quoted 2 lines

Documentation/git-rebase.adoc +1 -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 ...

Quoted 8 lines

TRANSPLANTING A TOPIC BRANCH WITH --ONTO
----------------------------------------

Documentation/git-repack.adoc +0 -0

index d12c4985f6..673ce91083 100644

Documentation/git-repack.adoc to the new separate pack will be written. · line 82

Quoted 7 lines

Documentation/git-repack.adoc +1 -1

@@ -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.

Documentation/git-repack.adoc to the new separate pack will be written. · line 90

Quoted 10 lines

Documentation/git-repack.adoc +2 -2

 --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”.

Quoted 6 lines

Documentation/git-send-email.adoc +0 -0

index 263b977353..cdaf421cda 100644

Documentation/git-send-email.adoc Sending · line 214

Quoted 8 lines

Documentation/git-send-email.adoc +1 -1

@@ -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.

Documentation/git-send-email.adoc command names. For those use cases, consider using

Quoted 10 lines

Documentation/git-send-email.adoc +1 -1

@@ -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/[email protected]/

Documentation/git-send-email.adoc command names. For those use cases, consider using `--sendmail-cmd` · line 261

Quoted 6 lines

--sendmail-cmd
instead.

--smtp-server-port=<port>::

Documentation/git-send-email.adoc +1 -1

-	Specifies a port different from the default port (SMTP
+	Specify a port different from the default port (SMTP

Same.

Documentation/git-send-email.adoc instead. · line 269

Quoted 9 lines

Documentation/git-send-email.adoc +1 -1

 	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.

Documentation/git-send-email.adoc must be used for each option. · line 283

Quoted 12 lines

Documentation/git-send-email.adoc +1 -1

 	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.

Documentation/git-send-email.adoc Automating · line 351

Quoted 7 lines

Documentation/git-send-email.adoc +1 -1

@@ -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.

Documentation/git-send-email.adoc Automating · line 354

Quoted 4 lines

Documentation/git-send-email.adoc +1 -1

 --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.

Quoted 15 lines

Documentation/git-send-email.adoc +2 -6

 	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

Documentation/git-send-email.adoc have been specified, in which case default to `compose`. · line 519

Quoted 5 lines

Documentation/git-send-email.adoc +4 -0

+  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.

Documentation/git-worktree.adoc associated with a new unborn branch named _<branch>_ (after · line 107

Quoted 12 lines

Documentation/git-send-email.adoc +0 -0

 +
 Default is the value of `sendemail.validate`; if this is not set,

Documentation/git-worktree.adoc +1 -1

index f272f79783..d74ad7b0e9 100644
@@ -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.

Quoted 1 line

Quoted 6 lines

list::

base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b --
gitgitgadget

doc-diff also looks good.

Le 15/12/2025 à 23:50, Kristoffer Haugsbakk a écrit :

Quoted 5 lines

[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.

Quoted 17 lines

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

Quoted 5 lines

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.

Quoted 2 lines

[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.

[snip]

Quoted 1 line

[snip]

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 <[email protected]>

## 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 <[email protected]>

- ## 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`::
     - 

Signature · 1 line

gitgitgadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

* 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 <[email protected]>

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

* 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 <[email protected]>

Quoted 6 lines · Jean-Noël Avila via GitGitGadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

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

Quoted 1 line

Signed-off-by Jean-Noël Avila <[email protected]>

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 <[email protected]>