doc: flock of small fixes to various documentation files

[jnavila]

cc: "Kristoffer Haugsbakk" kristofferhaugsbakk@fastmail.com

[jnavila]

/submit

[gitgitgadget]

Submitted as pull.2016.git.1765830229824.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2016/jnavila/doc_small_fixups-v1

To fetch this version to local tag pr-2016/jnavila/doc_small_fixups-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2016/jnavila/doc_small_fixups-v1

[gitgitgadget]

On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this):

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

[gitgitgadget]

User "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> has been added to the cc: list.

[gitgitgadget]

This patch series was integrated into seen via git@f3ed17c.