From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Sun, 01 Feb 2026 12:11:26 GMT
Subject: Re: [PATCH 3/4] doc: fix some style issues in git-clone and for-each-ref-options
Message-ID: <29bd35be-3bc7-40ed-aff5-f37da5c4eaf1@app.fastmail.com>
In-Reply-To: <bcd6fcd1190fe21c667b5253a4a33b833e658609.1769202903.git.gitgitgadget@gmail.com>

On Fri, Jan 23, 2026, at 22:15, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
>  * spell out all forms of --[no-]reject-shallow in git-clone
>  * use imperative mood for the first line of options
>  * Use asciidoc NOTE macro
>  * fix markups
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/for-each-ref-options.adoc |  4 ++--
>  Documentation/git-clone.adoc            | 30 ++++++++++++-------------
>  2 files changed, 17 insertions(+), 17 deletions(-)
>
> diff --git a/Documentation/for-each-ref-options.adoc
> b/Documentation/for-each-ref-options.adoc
> index f13efb5f25..54e2fa95c2 100644
> --- a/Documentation/for-each-ref-options.adoc
> +++ b/Documentation/for-each-ref-options.adoc
> @@ -30,8 +30,8 @@ TAB %(refname)`.
>
>  `--color[=<when>]`::
>  	Respect any colors specified in the `--format` option. The
> -	_<when__ field must be one of `always`, `never`, or `auto` (if
> -	`<when>` is absent, behave as if `always` was given).
> +	_<when>_ field must be one of `always`, `never`, or `auto` (if
> +	_<when>_ is absent, behave as if `always` was given).

Good. I also checked the placeholders in this doc (by searching for `<`)
and couldn’t find any others that need updating.

>
>  `--shell`::
>  `--perl`::
> diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc
> index 7a0e147384..fceeb43475 100644
> --- a/Documentation/git-clone.adoc
> +++ b/Documentation/git-clone.adoc
> @@ -84,7 +84,7 @@ _<src>_.
>  	with the source repository.  The resulting repository
>  	starts out without any object of its own.
>  +
> -*NOTE*: this is a possibly dangerous operation; do *not* use
> +NOTE: this is a possibly dangerous operation; do *not* use
>  it unless you understand what it does. If you clone your
>  repository using this option and then delete branches (or use any
>  other Git command that makes any existing commit unreferenced) in the

A nice Note block.

> @@ -104,7 +104,8 @@ If you want to break the dependency of a repository
> cloned with `--shared` on
>  its source repository, you can simply run `git repack -a` to copy all
>  objects from the source repository into a pack in the cloned
> repository.
>
> -`--reference[-if-able] <repository>`::
> +`--reference <repository>`::
> +`--reference-if-able <repository>`::

Proper split between the two variants, both spelled out. Good.

>  	If the reference _<repository>_ is on the local machine,
>  	automatically setup `.git/objects/info/alternates` to
>  	obtain objects from the reference _<repository>_.  Using
> @@ -115,7 +116,7 @@ objects from the source repository into a pack in
> the cloned repository.
>  	directory is skipped with a warning instead of aborting
>  	the clone.
>  +
> -*NOTE*: see the NOTE for the `--shared` option, and also the
> +NOTE: see the NOTE for the `--shared` option, and also the
>  `--dissociate` option.

Good.

>
>  `--dissociate`::
> @@ -140,14 +141,14 @@ objects from the source repository into a pack in
> the cloned repository.
>  	to the standard error stream.
>
>  `--progress`::
> -	Progress status is reported on the standard error stream
> -	by default when it is attached to a terminal, unless `--quiet`
> +	Report progress status on the standard error stream
> +	by default when attached to a terminal, unless `--quiet`

Imperative mood. Good.

>  	is specified. This flag forces progress status even if the
>  	standard error stream is not directed to a terminal.
>
>  `--server-option=<option>`::
>  	Transmit the given string to the server when communicating using
> -	protocol version 2.  The given string must not contain a NUL or LF
> +	protocol version 2.  The given string must not contain a _NUL_ or _LF_

Using emphasis for these ASCII char names looks much better IMO.

>  	character.  The server's handling of server options, including
>  	unknown ones, is server-specific.
>  	When multiple `--server-option=<option>` are given, they are all
> @@ -158,9 +159,10 @@ objects from the source repository into a pack in
> the cloned repository.
>
>  `-n`::
>  `--no-checkout`::
> -	No checkout of `HEAD` is performed after the clone is complete.
> +	Do not checkout `HEAD` after the clone is complete.

Good.

>
> -`--`[`no-`]`reject-shallow`::
> +`--no-reject-shallow`::
> +`--reject-shallow`::
>  	Fail if the source repository is a shallow repository.
>  	The `clone.rejectShallow` configuration variable can be used to
>  	specify the default.

Spelling out each option, good.

> @@ -214,10 +216,9 @@ objects from the source repository into a pack in
> the cloned repository.
>
>  `-b <name>`::
>  `--branch <name>`::
> -	Instead of pointing the newly created `HEAD` to the branch pointed
> -	to by the cloned repository's `HEAD`, point to _<name>_ branch
> -	instead. In a non-bare repository, this is the branch that will
> -	be checked out.
> +	Point the newly created `HEAD` to _<name>_ branch instead of the branch
> +	pointed to by the cloned repository's `HEAD`. In a non-bare repository,
> +	this is the branch that will be checked out.

This looks better. Leading with what the option does instead of starting
with a whole “instead” clause about what some *other* option or mode
does.

>  	`--branch` can also take tags and detaches the `HEAD` at that commit
>  	in the resulting repository.
>
> @@ -232,9 +233,8 @@ objects from the source repository into a pack in
> the cloned repository.
>
>  `-u <upload-pack>`::
>  `--upload-pack <upload-pack>`::
> -	When given, and the repository to clone from is accessed
> -	via ssh, this specifies a non-default path for the command
> -	run on the other end.
> +	Specify a non-default path for the command run on the other end when the
> +	repository to clone from is accessed via ssh.

Waging war on the “When given,” introduction. Good.

>
>  `--template=<template-directory>`::
>  	Specify the directory from which templates will be used;
> --
> gitgitgadget