Skip to content

doc: some more synopsis conversions and fixes #2036

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jnavila wants to merge 4 commits into
base: master
Choose a base branch
from
+321 −290
Open

doc: some more synopsis conversions and fixes #2036

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
05e68e2
convert git-submodule doc to synopsis style
jnavila Dec 27, 2025
3a5b642
doc: finalize git-clone documentation conversion to synopsis style
jnavila Jan 22, 2026
bcd6fcd
doc: fix some style issues in git-clone and for-each-ref-options
jnavila Jan 22, 2026
d078e1d
doc: convert git-show to synopsis style
jnavila Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Documentation/asciidoc.conf.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,12 +81,18 @@ endif::backend-xhtml11[]

Copy link

@gitgitgadget gitgitgadget bot Jan 25, 2026

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

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>
>
>  * add synopsis block definition in asciidoc.conf.in

This is for e.g. ``<hash> <title-line>`` it looks like. Is the intent to
use italics on placeholders like `<hash>`?

>  * convert commands to synopsis style
>  * use _<placeholder>_ for arguments
>  * minor formatting fixes
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  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
> index ff9ea0a294..31b883a72c 100644
> --- 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>...]

Looks good.

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

Good.

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

Again replacing (') with (`). Looks good.

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

Same here.

It could be nice to s/`git log` command/linkgit:git-log[1]/ either on
this commit or in a separate one.

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

Looks correct in the HTML output.

>  	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..5b73f03433 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>
> +`oneline`::
> ++
> +[synopsis]
> +--
> +`<hash> <title-line>`
> +--

HTML looks wrong in git-show(1) and others that include it. Something
like this:

    oneline
        __<hash>__ __<title-line>__

This doesn’t happen when I run asciidoc(1) or asciidoctor(1) directly.

>  +
>  This is designed to be as compact as possible.
>
> -* `short`
> -
> -	  commit <hash>
> -	  Author: <author>
> -
> -	      <title-line>
> -
> -* `medium`
> -
> -	  commit <hash>
> -	  Author: <author>
> -	  Date:   <author-date>
> -
> -	      <title-line>
> +`short`::
> ++
> +[synopsis]
> +--
> +commit <hash>
> +Author: <author>
>
> -	      <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>)
> +--

(For these pretty formats) The diff got confused I think but the
conversion looks correct.


>  +
>  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 changed in this patch but this doesn’t render correctly for me. It’s
not inline verbatim/code all the way through. But it is correct if I
remove the `\`.

I don’t know why `++` was used either.

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

By the way. It renders with nice italic for placeholders. Again back to
the presumed point of these `[synopsis]` blocks.

>
> -* `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.
>
> -* `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`
> @@ -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:
> ++
> +--

The HTML structure here is correct.

>  ++%Cred++:: switch color to red
>  ++%Cgreen++:: switch color to green
>  ++%Cblue++:: switch color to blue
> @@ -181,8 +204,11 @@ The placeholders are:
>  ++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++
>  			 erespectively, 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,36 +259,34 @@ 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.

This looks correct just looking quickly over.

>
> -** `prefix=<value>`: Shown before the list of ref names.  Defaults to
> "{nbsp}++(++".

All of these use the "(" style which doesn’t look good in my
opinion. But I’m guessing it has to do with some of them using spaces in
them and `"` being used as a boundary.

> -** `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}".
> +`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}".
>
>  +
> ---
>  For example, to produce decorations with no wrapping
>  or tag annotations, and spaces as separators:
> -
> ++
>  ++%(decorate:prefix=,suffix=,tag=,separator= )++
> ---
>
> -++%(describe++`[:<option>,...]`++)++::
> +++%(`describe++``[:<option>,...]`++)++::

This renders with backticks in HTML:

    %(describe++`[:<option>,...]`)++

>  human-readable name, like linkgit:git-describe[1]; empty string for
>  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,
> 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.
>
>  +%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

Might as well s/"Ticket"/`Ticket`/ ?

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

The rest looks okay.

Copy link

@gitgitgadget gitgitgadget bot Jan 25, 2026

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

On Sunday, 25 January 2026 20:27:38 CET Kristoffer Haugsbakk wrote:
> 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>
> > 
> >  * add synopsis block definition in asciidoc.conf.in
> 
> This is for e.g. ``<hash> <title-line>`` it looks like. Is the intent to
> use italics on placeholders like `<hash>`?

Yes, it is. It turns out that asciidoc.py treats differently, paragraph styles 
and block styles. Until now, we only used paragraph style for synopsis.

> >  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
> 
> Same here.
> 
> It could be nice to s/`git log` command/linkgit:git-log[1]/ either on
> this commit or in a separate one.

The problem is that pretty-formats.adoc is also included in git-log.adoc and I 
don't think it makes sense to self-cross-reference. If we want to generalize, 
it would need some conditional inclusion/replacement. 

> >> 
> >  built-in formats:
> > -* `oneline`
> > -
> > -	  <hash> <title-line>
> > +`oneline`::
> > ++
> > +[synopsis]
> > +--
> > +`<hash> <title-line>`
> > +--
> 
> HTML looks wrong in git-show(1) and others that include it. Something
> like this:
> 
>     oneline
>         __<hash>__ __<title-line>__
> 

The first edit was `<hash> <title-line>` but the rendering odd with the 
following items which where more spaced. So, I changed to synopsis block but 
forgot the back-ticks.

Will reroll.

> This doesn’t happen when I run asciidoc(1) or asciidoctor(1) directly.
> 

<snip>
> 
> (For these pretty formats) The diff got confused I think but the
> conversion looks correct.
> 

It looks better but not perfect. It is difficult to render correctly when the 
usual grammatical signs are in fact keywords. See below for better 
explanation.

> >  +
> >  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 changed in this patch but this doesn’t render correctly for me. It’s
> not inline verbatim/code all the way through. But it is correct if I
> remove the `\`.
> 
> I don’t know why `++` was used either.

That's where the synopsis style fails. If we use backticks for this span, the 
parenthesis are interpreted as grammar signs, whereas here, we intend to pass 
the whole span as verbatim.


For asciidoc.py, using the verbatim form '++' ensures that the whole span is 
treated as such. On my computer (asciidoc.py version 10.2.1), this renders as 
correctly. 

For asciidoctor unfortunately, the synopsis processing is performed very late 
in the generation, after all parsing has been done. So, the '++' verbatim is 
processed the same way as backticked contents. I haven't found a better 
alternative. The output is this wrongly processed span here.

This is the least breaking way I found. It means that for asciidoc.py, we can 
bypass the synopsis style with '++' formatting.

If I remove the backslash in this, the span inside the single quotes is 
converted to italics by both engines.

Can you describe your setup?



> 
> This looks correct just looking quickly over.
> 
> > -** `prefix=<value>`: Shown before the list of ref names.  Defaults to
> > "{nbsp}++(++".
> 
> All of these use the "(" style which doesn’t look good in my
> opinion. But I’m guessing it has to do with some of them using spaces in
> them and `"` being used as a boundary.

Same here as above. I get the correct rendering for asciidoc.py. For 
asciidoctor, this is rendered as normal text. Not correct but not completely 
bogus.

> > 
> > -++%(describe++`[:<option>,...]`++)++::
> 
> > +++%(`describe++``[:<option>,...]`++)++::
> This renders with backticks in HTML:
> 
>     %(describe++`[:<option>,...]`)++
> 

Ah, thanks for spotting. I mixed again synopsis and plain verbatim.
Will reroll.



> > 
> >     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
> 
> Might as well s/"Ticket"/`Ticket`/ ?

Difficult to say. This is not a keyword per se. Changing is ok for me.

> The rest looks okay.

ifdef::backend-docbook[]
ifdef::doctype-manpage[]
[blockdef-open]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"

[paradef-default]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
endif::doctype-manpage[]
endif::backend-docbook[]

ifdef::backend-xhtml11[]
[blockdef-open]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"

[paradef-default]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
endif::backend-xhtml11[]
4 changes: 2 additions & 2 deletions Documentation/for-each-ref-options.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

`--shell`::
`--perl`::
Expand Down
52 changes: 26 additions & 26 deletions Documentation/git-clone.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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>`::
If the reference _<repository>_ is on the local machine,
automatically setup `.git/objects/info/alternates` to
obtain objects from the reference _<repository>_. Using
Expand All @@ -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.

`--dissociate`::
Expand All @@ -140,27 +141,28 @@ 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`
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_
character. The server's handling of server options, including
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
line, the values of configuration variable `remote.<name>.serverOption`
are used instead.

`-n`::
`--no-checkout`::
No checkout of `HEAD` is performed after the clone is complete.
Do not checkout `HEAD` after the clone is complete.

`--`[`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.
Expand Down Expand Up @@ -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>_::
`-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>_::
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.
`-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.

Expand All @@ -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>_::
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.
`-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>`::
`-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
Expand Down Expand Up @@ -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.

Expand Down
16 changes: 8 additions & 8 deletions Documentation/git-show.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,34 @@ git-show - Show various types of objects

SYNOPSIS
--------
[verse]
'git show' [<options>] [<object>...]
[synopsis]
git show [<options>] [<object>...]

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

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

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
control how the changes the commit introduces are shown.

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`).
For a more complete list of ways to spell object names, see
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].

Expand Down
Loading
Loading