doc: some more synopsis conversions and fixes #2036
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -81,12 +81,18 @@ endif::backend-xhtml11[] | |
|
|
||
|
There was a problem hiding this comment. "Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email): On Mon, Jan 26, 2026, at 22:25, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> * add synopsis block definition in asciidoc.conf.in
> * convert commands to synopsis style
> * use _<placeholder>_ for arguments
> * minor formatting fixes
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
I will go through and discuss both the markup as well as the HTML
rendering at the same time when relevant.
(Confession. I never check the man page output since I haven’t managed
to set it up. I don’t know if that is a potential reviewer blindspot.)
> Documentation/asciidoc.conf.in | 6 ++
> Documentation/git-show.adoc | 16 +--
> Documentation/pretty-formats.adoc | 164 +++++++++++++++++-------------
> 3 files changed, 108 insertions(+), 78 deletions(-)
>
> diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in
>[snip]
> diff --git a/Documentation/git-show.adoc b/Documentation/git-show.adoc
> index 51044c814f..3b180e8c7a 100644
> --- a/Documentation/git-show.adoc
> +++ b/Documentation/git-show.adoc
> @@ -8,8 +8,8 @@ git-show - Show various types of objects
>
> SYNOPSIS
> --------
> -[verse]
> -'git show' [<options>] [<object>...]
> +[synopsis]
> +git show [<options>] [<object>...]
Ok.
>
> DESCRIPTION
> -----------
> @@ -17,16 +17,16 @@ Shows one or more objects (blobs, trees, tags and commits).
>
> For commits it shows the log message and textual diff. It also
> presents the merge commit in a special format as produced by
> -'git diff-tree --cc'.
> +`git diff-tree --cc`.
Ok.
>
> For tags, it shows the tag message and the referenced objects.
>
> -For trees, it shows the names (equivalent to 'git ls-tree'
> -with --name-only).
> +For trees, it shows the names (equivalent to `git ls-tree`
> +with `--name-only`).
More conversion to backticks. Ok.
>
> For plain blobs, it shows the plain contents.
>
> -Some options that 'git log' command understands can be used to
> +Some options that `git log` command understands can be used to
Like what was discussed in the last round it makes sense to use `git
log` instead of `linkgit` here.
> control how the changes the commit introduces are shown.
>
> This manual page describes only the most frequently used options.
> @@ -34,8 +34,8 @@ This manual page describes only the most frequently
> used options.
>
> OPTIONS
> -------
> -<object>...::
> - The names of objects to show (defaults to 'HEAD').
> +`<object>...`::
> + The names of objects to show (defaults to `HEAD`).
synopsis-style argument markup and backticks. Ok.
> For a more complete list of ways to spell object names, see
> "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
>
> diff --git a/Documentation/pretty-formats.adoc
> b/Documentation/pretty-formats.adoc
> index 2121e8e1df..806c588658 100644
> --- a/Documentation/pretty-formats.adoc
> +++ b/Documentation/pretty-formats.adoc
> @@ -18,54 +18,72 @@ config option to either another format name, or a
> linkgit:git-config[1]). Here are the details of the
> built-in formats:
>
> -* `oneline`
> -
> - <hash> <title-line>
Okay. This now looks good in the HTML output.
> +`oneline`::
> ++
> +[synopsis]
> +--
> +<hash> <title-line>
> +--
Also good. The `[synopsis]` gives us verbatim typeface for code and
italics/emphasis for placeholders. Just like inline backticks.
> +
> This is designed to be as compact as possible.
>
> -* `short`
> -
> - commit <hash>
> - Author: <author>
These have tab indent followed by two spaces. I’m guessing this is
intentional.
The HTML rendering looks good.
> -
> - <title-line>
> -
> -* `medium`
> -
> - commit <hash>
> - Author: <author>
> - Date: <author-date>
> -
> - <title-line>
> +`short`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author><hash> <title-line>
>
> - <full-commit-message>
> + <title-line>
> +--
>
> -* `full`
> +`medium`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author>
> +Date: <author-date>
>
> - commit <hash>
> - Author: <author>
> - Commit: <committer>
> + <title-line>
>
> - <title-line>
> + <full-commit-message>
> +--
>
> - <full-commit-message>
> +`full`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author>
> +Commit: <committer>
>
> -* `fuller`
> + <title-line>
>
> - commit <hash>
> - Author: <author>
> - AuthorDate: <author-date>
> - Commit: <committer>
> - CommitDate: <committer-date>
> + <full-commit-message>
> +--
>
> - <title-line>
> +`fuller`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author>
> +AuthorDate: <author-date>
> +Commit: <committer>
> +CommitDate: <committer-date>
>
> - <full-commit-message>
> + <title-line>
>
> -* `reference`
> + <full-commit-message>
> +--
>
> - <abbrev-hash> (<title-line>, <short-author-date>)
> +`reference`::
> ++
> +[synopsis]
> +--
> +<abbrev-hash> (<title-line>, <short-author-date>)
> +--
Good. Things that are indented (like commit message) are correctly
indented here.
> +
> This format is used to refer to another commit in a commit message and
> is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++. By default,
Not a change here but while `--pretty...` has all the symbols it is
partly rendered, partly not.
> @@ -74,23 +92,24 @@ is explicitly specified. As with any `format:` with format
> placeholders, its output is not affected by other options like
> `--decorate` and `--walk-reflogs`.
>
> -* `email`
> -
> - From <hash> <date>
> - From: <author>
> - Date: <author-date>
> - Subject: [PATCH] <title-line>
> +`email`::
> ++
> +[synopsis]
> +--
> +From <hash> <date>
> +From: <author>
> +Date: <author-date>
> +Subject: [PATCH] <title-line>
>
> - <full-commit-message>
> +<full-commit-message>
> +--
Good.
>
> -* `mboxrd`
> -+
> +`mboxrd`::
> Like `email`, but lines in the commit message starting with "From "
> (preceded by zero or more ">") are quoted with ">" so they aren't
> confused as starting a new commit.
Good.
>
> -* `raw`
> -+
> +`raw`::
> The `raw` format shows the entire commit exactly as
> stored in the commit object. Notably, the hashes are
> displayed in full, regardless of whether `--abbrev` or
> @@ -101,8 +120,7 @@ commits are displayed, but not the way the diff is
> shown e.g. with
> `git log --raw`. To get full object names in a raw diff format,
> use `--no-abbrev`.
>
> -* `format:<format-string>`
> -+
> +`format:<format-string>`::
> The `format:<format-string>` format allows you to specify which
> information
> you want to show. It works a little bit like printf format,
> with the notable exception that you get a newline with `%n`
All good.
> @@ -120,13 +138,18 @@ The title was >>t4119: test autocomputing -p<n>
> for traditional diff input.<<
> The placeholders are:
>
> - Placeholders that expand to a single literal character:
> ++
> +--
> ++%n++:: newline
> ++%%++:: a raw ++%++
> ++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a
> byte with the hexadecimal digits' value (we will call this
> "literal formatting code" in the rest of this document).
> +--
>
> - Placeholders that affect formatting of later placeholders:
> ++
> +--
> ++%Cred++:: switch color to red
> ++%Cgreen++:: switch color to green
> ++%Cblue++:: switch color to blue
Good.
> @@ -181,8 +204,11 @@ The placeholders are:
> ++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++
> respectively, but padding both sides
> (i.e. the text is centered)
> +--
>
> - Placeholders that expand to information extracted from the commit:
> ++
> +--
> +%H+:: commit hash
> +%h+:: abbreviated commit hash
> +%T+:: tree hash
> @@ -233,20 +259,18 @@ colon and zero or more comma-separated options.
> Option values may contain
> literal formatting codes. These must be used for commas (`%x2C`) and
> closing
> parentheses (`%x29`), due to their role in the option syntax.
>
> -** `prefix=<value>`: Shown before the list of ref names. Defaults to
> "{nbsp}++(++".
> -** `suffix=<value>`: Shown after the list of ref names. Defaults to
> "+)+".
> -** `separator=<value>`: Shown between ref names. Defaults to
> "+,+{nbsp}".
These are rendered serviceably.
> -** `pointer=<value>`: Shown between HEAD and the branch it points to,
> if any.
> - Defaults to "{nbsp}++->++{nbsp}".
This one is just `->` but it’s a bit confusing:
" -> ".
(the spaces may be more narrow in the HTML?)
And the `-` has verbatim typeface while `>` does not.
I said the preceding ones were serviceable in the sense that they don’t
look great but you see what they are. This one is questionable.
> -** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
> +`prefix=<value>`;; Shown before the list of ref names. Defaults to
> "{nbsp}++(++".
> +`suffix=<value>`;; Shown after the list of ref names. Defaults to
> "+)+".
> +`separator=<value>`;; Shown between ref names. Defaults to
> "+,+{nbsp}".
> +`pointer=<value>`;; Shown between HEAD and the branch it points to, if
> any.
> + Defaults to "{nbsp}++->++{nbsp}".
> +`tag=<value>`;; Shown before tag names. Defaults to "`tag:`{nbsp}".
Here I feel some deja vu.
>
> +
> ---
> For example, to produce decorations with no wrapping
> or tag annotations, and spaces as separators:
> -
> ++
> ++%(decorate:prefix=,suffix=,tag=,separator= )++
> ---
Here is a a problem. The pluses in `++...++` are apparently markup. But
the line starts with `+%` here:
+ %(decorate:prefix=,suffix=,tag=,separator= )
>
> ++%(describe++`[:<option>,...]`++)++::
> human-readable name, like linkgit:git-describe[1]; empty string for
> @@ -254,15 +278,15 @@ undescribable commits. The `describe` string may
> be followed by a colon and
> zero or more comma-separated options. Descriptions can be
> inconsistent when
> tags are added or removed at the same time.
> +
> -** `tags[=<bool-value>]`: Instead of only considering annotated tags,
> +`tags[=<bool-value>]`;; Instead of only considering annotated tags,
> consider lightweight tags as well.
> -** `abbrev=<number>`: Instead of using the default number of
> hexadecimal digits
> +`abbrev=<number>`;; Instead of using the default number of hexadecimal
> digits
> (which will vary according to the number of objects in the
> repository with a
> default of 7) of the abbreviated object name, use <number> digits,
Need an edit here: s/<number>/_<number>_/
> or as many
> digits as needed to form a unique object name.
> -** `match=<pattern>`: Only consider tags matching the given
> +`match=<pattern>`;; Only consider tags matching the given
> `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
> -** `exclude=<pattern>`: Do not consider tags matching the given
> +`exclude=<pattern>`;; Do not consider tags matching the given
> `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
Good.
>
> +%S+:: ref name given on the command line by which the commit was
> reached
> @@ -311,7 +335,7 @@ linkgit:git-interpret-trailers[1]. The `trailers`
> string may be followed by
> a colon and zero or more comma-separated options. If any option is
> provided
> multiple times, the last occurrence wins.
> +
> -** `key=<key>`: only show trailers with specified <key>. Matching is
> done
> +`key=<key>`;; only show trailers with specified <key>. Matching is done
> case-insensitively and trailing colon is optional. If option is
> given multiple times trailer lines matching any of the keys are
> shown. This option automatically enables the `only` option so that
> @@ -319,21 +343,21 @@ multiple times, the last occurrence wins.
> desired it can be disabled with `only=false`. E.g.,
> +%(trailers:key=Reviewed-by)+ shows trailer lines with key
> `Reviewed-by`.
> -** `only[=<bool>]`: select whether non-trailer lines from the trailer
> +`only[=<bool>]`;; select whether non-trailer lines from the trailer
> block should be included.
> -** `separator=<sep>`: specify the separator inserted between trailer
> + `separator=<sep>`;; specify the separator inserted between trailer
> lines. Defaults to a line feed character. The string <sep> may
> contain
> the literal formatting codes described above. To use comma as
> separator one must use `%x2C` as it would otherwise be parsed as
> next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+
> - shows all trailer lines whose key is "Ticket" separated by a comma
> + shows all trailer lines whose key is `Ticket` separated by a comma
> and a space.
> -** `unfold[=<bool>]`: make it behave as if interpret-trailer's
> `--unfold`
> +`unfold[=<bool>]`;; make it behave as if interpret-trailer's `--unfold`
> option was given. E.g.,
> +%(trailers:only,unfold=true)+ unfolds and shows all trailer lines.
> -** `keyonly[=<bool>]`: only show the key part of the trailer.
> -** `valueonly[=<bool>]`: only show the value part of the trailer.
> -** `key_value_separator=<sep>`: specify the separator inserted between
> +`keyonly[=<bool>]`;; only show the key part of the trailer.
> +`valueonly[=<bool>]`;; only show the value part of the trailer.
> +`key_value_separator=<sep>`;; specify the separator inserted between
> the key and value of each trailer. Defaults to ": ". Otherwise it
> shares the same semantics as `separator=<sep>` above.
All of this looks good.
>
> @@ -360,9 +384,9 @@ placeholder expands to an empty string.
> If you add a `' '` (space) after +%+ of a placeholder, a space
> is inserted immediately before the expansion if and only if the
> placeholder expands to a non-empty string.
> +--
>
> -* `tformat:`
> -+
> +`tformat:`::
> The `tformat:` format works exactly like `format:`, except that it
> provides "terminator" semantics instead of "separator" semantics. In
> other words, each commit has the message terminator character (usually a
Good.
> --
> gitgitgadgetThere was a problem hiding this comment. Jean-Noël AVILA wrote on the Git mailing list (how to reply to this email): On Sunday, 1 February 2026 13:12:47 CET Kristoffer Haugsbakk wrote:
> > +
> > This format is used to refer to another commit in a commit message and
> > is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++. By default,
>
> Not a change here but while `--pretty...` has all the symbols it is
> partly rendered, partly not.
>
> > -** `prefix=<value>`: Shown before the list of ref names. Defaults to
> > "{nbsp}++(++".
> > -** `suffix=<value>`: Shown after the list of ref names. Defaults to
> > "+)+".
> > -** `separator=<value>`: Shown between ref names. Defaults to
> > "+,+{nbsp}".
>
> These are rendered serviceably.
>
> > -** `pointer=<value>`: Shown between HEAD and the branch it points to,
> > if any.
> > - Defaults to "{nbsp}++->++{nbsp}".
>
> This one is just `->` but it’s a bit confusing:
>
> " -> ".
>
> (the spaces may be more narrow in the HTML?)
>
> And the `-` has verbatim typeface while `>` does not.
>
> I said the preceding ones were serviceable in the sense that they don’t
> look great but you see what they are. This one is questionable.
>
> > -** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
> > +`prefix=<value>`;; Shown before the list of ref names. Defaults to
> > "{nbsp}++(++".
> > +`suffix=<value>`;; Shown after the list of ref names. Defaults to
> > "+)+".
> > +`separator=<value>`;; Shown between ref names. Defaults to
> > "+,+{nbsp}".
> > +`pointer=<value>`;; Shown between HEAD and the branch it points to, if
> > any.
> > + Defaults to "{nbsp}++->++{nbsp}".
> > +`tag=<value>`;; Shown before tag names. Defaults to "`tag:`{nbsp}".
>
> Here I feel some deja vu.
>
> > +
> >
> > ---
> >
> > For example, to produce decorations with no wrapping
> >
> > or tag annotations, and spaces as separators:
> > -
> > ++
> >
> > ++%(decorate:prefix=,suffix=,tag=,separator= )++
> >
> > ---
>
> Here is a a problem. The pluses in `++...++` are apparently markup. But
> the line starts with `+%` here:
>
> + %(decorate:prefix=,suffix=,tag=,separator= )
>
OK, I understand that you are using asciidoctor for compilation. This is a
difficult problem to sort out. For the translations, I'm working on an actual
parser:
https://github.com/jnavila/git-manpages-l10n/blob/master/asciidoctor-extensions.rb
When the parsing fails, the formatting rolls back to simple verbatim
formatting.
After polishing it a bit, this could make it into the git source, if the new
dependency is accepted.
In the mean time, all I can propose is to remove all formatting when
asciidoctor will not process it correctly and the output will be confusing.
|
||
| ifdef::backend-docbook[] | ||
| ifdef::doctype-manpage[] | ||
| [blockdef-open] | ||
| synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'" | ||
|
|
||
| [paradef-default] | ||
| synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'" | ||
| endif::doctype-manpage[] | ||
| endif::backend-docbook[] | ||
|
|
||
| ifdef::backend-xhtml11[] | ||
| [blockdef-open] | ||
| synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'" | ||
|
|
||
| [paradef-default] | ||
| synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'" | ||
| endif::backend-xhtml11[] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,8 +30,8 @@ TAB %(refname)`. | |
|
|
||
|
There was a problem hiding this comment. "Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email): 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 |
||
| `--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). | ||
|
|
||
| `--shell`:: | ||
| `--perl`:: | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
| 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 | ||
|
|
@@ -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=<repository>`:: | ||
| `--reference-if-able=<repository>`:: | ||
| 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 | ||
| `--dissociate` option. | ||
|
|
||
| `--dissociate`:: | ||
|
|
@@ -140,27 +141,28 @@ objects from the source repository into a pack in the cloned repository. | |
| to the standard error stream. | ||
|
|
||
| `--progress`:: | ||
| Report progress status on the standard error stream | ||
| by default when attached to a terminal, unless `--quiet` | ||
| 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_ | ||
| character. The server's handling of server options, including | ||
| unknown ones, is server-specific. | ||
|
There was a problem hiding this comment. "Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email): 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>
>
> Use backticks where appropriate for command-line options
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
> Documentation/git-clone.adoc | 22 +++++++++++-----------
> 1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc
> index 57cdfb7620..7a0e147384 100644
> --- a/Documentation/git-clone.adoc
> +++ b/Documentation/git-clone.adoc
> @@ -152,7 +152,7 @@ objects from the source repository into a pack in
> the cloned repository.
> unknown ones, is server-specific.
> When multiple `--server-option=<option>` are given, they are all
> sent to the other side in the order listed on the command line.
> - When no ++--server-option=++__<option>__ is given from the command
> + When no `--server-option=<option>` is given from the command
Just using backticks now that `synopsis` style handles placeholder
rendering. Makes sense.
> line, the values of configuration variable
> `remote.<name>.serverOption`
> are used instead.
>
> @@ -206,14 +206,14 @@ objects from the source repository into a pack in
> the cloned repository.
> that all these refs are overwritten by a `git remote update` in the
> target repository.
>
> -`-o` _<name>_::
> -`--origin` _<name>_::
> +`-o <name>`::
> +`--origin <name>`::
> Instead of using the remote name `origin` to keep track of the upstream
> repository, use _<name>_. Overrides `clone.defaultRemoteName` from the
> config.
Doesn’t need to be done now in this series, but the “stuck form” of
`--origin=<name>` is recommended by gitcli(7) for long optoins. This doc
uses a mix of unstuck form (no `=`) and stuck form.
>
> -`-b` _<name>_::
> -`--branch` _<name>_::
> +`-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
> @@ -230,8 +230,8 @@ objects from the source repository into a pack in
> the cloned repository.
> name.
> This option is incompatible with `--branch` and `--mirror`.
>
> -`-u` _<upload-pack>_::
> -`--upload-pack` _<upload-pack>_::
> +`-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.
> @@ -240,8 +240,8 @@ objects from the source repository into a pack in
> the cloned repository.
> Specify the directory from which templates will be used;
> (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
Looks good. Just same comments.
>
> -`-c` `<key>=<value>`::
> -`--config` `<key>=<value>`::
> +`-c <key>=<value>`::
> +`--config <key>=<value>`::
> Set a configuration variable in the newly-created repository;
> this takes effect immediately after the repository is
> initialized, but before the remote history is fetched or any
I was curious if you can use `--config=<key>=<value>` without tripping
up the option parser. And you can:
git clone --config=core.editor=something ...
> @@ -339,8 +339,8 @@ Specify the given ref storage format for the
> repository. The valid values are:
> +
> include::ref-storage-format.adoc[]
>
> -`-j` _<n>_::
> -`--jobs` _<n>_::
> +`-j <n>`::
> +`--jobs <n>`::
> The number of submodules fetched at the same time.
> Defaults to the `submodule.fetchJobs` option.
>
Good.
> --
> gitgitgadgetThere was a problem hiding this comment. Jean-Noël AVILA wrote on the Git mailing list (how to reply to this email): Thank you for taking time to scan through the changes.
I will reroll to fix all your comments.
On Sunday, 1 February 2026 13:04:13 CET Kristoffer Haugsbakk wrote:
> On Fri, Jan 23, 2026, at 22:15, Jean-Noël Avila via GitGitGadget wrote:
>
> Doesn’t need to be done now in this series, but the “stuck form” of
> `--origin=<name>` is recommended by gitcli(7) for long optoins. This doc
> uses a mix of unstuck form (no `=`) and stuck form.
>
Is this something that is automatically available, i.e can we already convert
and advise so to writers in all pages?
For me, these synopsis series are a chance to push forward a larger range of
reworks on formal formats such as this one.
> > +`--config <key>=<value>`::
> > Set a configuration variable in the newly-created repository;
> > this takes effect immediately after the repository is
> > initialized, but before the remote history is fetched or any
>
> I was curious if you can use `--config=<key>=<value>` without tripping
> up the option parser. And you can:
>
> git clone --config=core.editor=something ...
>
OK, will also rework.
There was a problem hiding this comment. "Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email): On Sun, Feb 1, 2026, at 14:14, Jean-Noël AVILA wrote:
>>[snip]
>>
>> Doesn’t need to be done now in this series, but the “stuck form” of
>> `--origin=<name>` is recommended by gitcli(7) for long optoins. This doc
>> uses a mix of unstuck form (no `=`) and stuck form.
>>
>
> Is this something that is automatically available, i.e can we already convert
> and advise so to writers in all pages?
> For me, these synopsis series are a chance to push forward a larger range of
> reworks on formal formats such as this one.
>
>[snip]
I am not aware of any static analysis tool or helper.
I think I learned about in this combination with that gitcli(7) as well
as Junio writing about the preferred way to write options.
Thanks
Kristoffer |
||
| When multiple `--server-option=<option>` are given, they are all | ||
| sent to the other side in the order listed on the command line. | ||
| When no `--server-option=<option>` is given from the command | ||
| line, the values of configuration variable `remote.<name>.serverOption` | ||
| are used instead. | ||
|
|
||
| `-n`:: | ||
| `--no-checkout`:: | ||
| Do not checkout `HEAD` after the clone is complete. | ||
|
|
||
| `--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. | ||
|
|
@@ -206,18 +208,17 @@ objects from the source repository into a pack in the cloned repository. | |
| that all these refs are overwritten by a `git remote update` in the | ||
| target repository. | ||
|
|
||
| `-o<name>`:: | ||
| `--origin=<name>`:: | ||
| Instead of using the remote name `origin` to keep track of the upstream | ||
| repository, use _<name>_. Overrides `clone.defaultRemoteName` from the | ||
| config. | ||
|
|
||
| `-b<name>`:: | ||
| `--branch=<name>`:: | ||
| 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. | ||
| `--branch` can also take tags and detaches the `HEAD` at that commit | ||
| in the resulting repository. | ||
|
|
||
|
|
@@ -230,18 +231,17 @@ objects from the source repository into a pack in the cloned repository. | |
| name. | ||
| This option is incompatible with `--branch` and `--mirror`. | ||
|
|
||
| `-u<upload-pack>`:: | ||
| `--upload-pack=<upload-pack>`:: | ||
| Specify a non-default path for the command run on the other end when the | ||
| repository to clone from is accessed via ssh. | ||
|
|
||
| `--template=<template-directory>`:: | ||
| Specify the directory from which templates will be used; | ||
| (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) | ||
|
|
||
| `-c<key>=<value>`:: | ||
| `--config=<key>=<value>`:: | ||
| Set a configuration variable in the newly-created repository; | ||
| this takes effect immediately after the repository is | ||
| initialized, but before the remote history is fetched or any | ||
|
|
@@ -257,7 +257,7 @@ Configuration variables known to not take effect are: | |
| `remote.<name>.mirror` and `remote.<name>.tagOpt`. Use the | ||
| corresponding `--mirror` and `--no-tags` options instead. | ||
|
|
||
| `--depth=<depth>`:: | ||
| Create a 'shallow' clone with a history truncated to the | ||
| specified number of commits. Implies `--single-branch` unless | ||
| `--no-single-branch` is given to fetch the histories near the | ||
|
|
@@ -339,8 +339,8 @@ Specify the given ref storage format for the repository. The valid values are: | |
| + | ||
| include::ref-storage-format.adoc[] | ||
|
|
||
| `-j<n>`:: | ||
| `--jobs=<n>`:: | ||
| The number of submodules fetched at the same time. | ||
| Defaults to the `submodule.fetchJobs` option. | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Jean-Noël AVILA wrote on the Git mailing list (how to reply to this email):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email):