From: "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>
To: "Jean-Noël Avila" <gitgitgadget@gmail•com>, git@vger•kernel.org
Cc: "Jean-Noël AVILA" <jn.avila@free•fr>
Subject: Re: [PATCH 3/4] doc: fix some style issues in git-clone and for-each-ref-options
Date: Sun, 01 Feb 2026 13:11:26 +0100 [thread overview]
Message-ID: <29bd35be-3bc7-40ed-aff5-f37da5c4eaf1@app.fastmail.com> (raw)
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
next prev parent reply other threads:[~2026-02-01 12:11 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-01-23 21:14 [PATCH 0/4] doc: some more synopsis conversions and fixes Jean-Noël Avila via GitGitGadget
2026-01-23 21:15 ` [PATCH 1/4] convert git-submodule doc to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-01 12:04 ` Kristoffer Haugsbakk
2026-01-23 21:15 ` [PATCH 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-02-01 12:04 ` Kristoffer Haugsbakk
2026-02-01 13:14 ` Jean-Noël AVILA
2026-02-02 8:36 ` Kristoffer Haugsbakk
2026-01-23 21:15 ` [PATCH 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-02-01 12:11 ` Kristoffer Haugsbakk [this message]
2026-01-23 21:15 ` [PATCH 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-01-25 19:27 ` Kristoffer Haugsbakk
2026-01-25 21:11 ` Jean-Noël AVILA
2026-01-26 5:58 ` Kristoffer Haugsbakk
2026-01-26 21:25 ` [PATCH v2 0/4] doc: some more synopsis conversions and fixes Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 1/4] convert git-submodule doc to synopsis style Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-01-26 21:25 ` [PATCH v2 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-01 12:12 ` Kristoffer Haugsbakk
2026-02-01 16:39 ` Jean-Noël AVILA
2026-02-03 17:03 ` [PATCH v3 0/4] doc: some more synopsis conversions and fixes Jean-Noël Avila via GitGitGadget
2026-02-03 17:03 ` [PATCH v3 1/4] doc: convert git-submodule to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-03 21:45 ` Kristoffer Haugsbakk
2026-02-06 3:55 ` Jean-Noël Avila
2026-02-03 17:03 ` [PATCH v3 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-02-03 21:45 ` Kristoffer Haugsbakk
2026-02-03 17:03 ` [PATCH v3 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-02-03 21:46 ` Kristoffer Haugsbakk
2026-02-03 17:03 ` [PATCH v3 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-03 21:44 ` Kristoffer Haugsbakk
2026-02-03 21:44 ` [PATCH v3 0/4] doc: some more synopsis conversions and fixes Kristoffer Haugsbakk
2026-02-04 16:24 ` Kristoffer Haugsbakk
2026-02-06 4:12 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 1/4] doc: convert git-submodule to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 2/4] doc: finalize git-clone documentation conversion " Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 3/4] doc: fix some style issues in git-clone and for-each-ref-options Jean-Noël Avila via GitGitGadget
2026-02-06 4:12 ` [PATCH v4 4/4] doc: convert git-show to synopsis style Jean-Noël Avila via GitGitGadget
2026-02-07 14:24 ` [PATCH v4 0/4] doc: some more synopsis conversions and fixes Kristoffer Haugsbakk
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=29bd35be-3bc7-40ed-aff5-f37da5c4eaf1@app.fastmail.com \
--to=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=jn.avila@free$(echo .)fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox