Skip to content

doc: convert another batch of files to synopsis style #2117

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 5 commits into
base: master
Choose a base branch
from
+337 −321
Open

doc: convert another batch of files to synopsis style #2117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dca7f19
doc: convert git-bisect to synopsis style
jnavila May 16, 2026
1b4efce
doc: convert git-grep synopsis and options to new style
jnavila May 16, 2026
4ab60a9
doc: convert git-am synopsis and options to new style
jnavila May 16, 2026
437e3f9
doc: convert git-apply synopsis and options to new style
jnavila May 16, 2026
dbe4d20
doc: convert git-imap-send synopsis and options to new style
jnavila May 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 @@ -84,6 +84,9 @@ ifdef::doctype-manpage[]
[blockdef-open]
Copy link
Copy Markdown

@gitgitgadget gitgitgadget Bot May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> Convert Documentation/git-bisect.adoc to the modern synopsis style.
>
> - Replace [verse] with [synopsis] in the SYNOPSIS block

This was expected.

> - Remove single quotes around command names in the synopsis
> - Use backticks for inline commands, options, refs, and special values
> - Apply [synopsis] attribute to in-body command-form code blocks

This is very much unexpected.  I think everybody thought [synopsis]
was invented to be used for the SYNOPSIS section at the beginning of
each manual page, and ...

>  SYNOPSIS
>  --------
> -[verse]
> -'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> -		   [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> ...
> -'git bisect' help
> +[synopsis]
> +git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> +		 [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> ...
> +git bisect help

... a change like this is very much expected and understandable, but
new appearances of [synonsis] in places like:

> +[synopsis]
>  ------------------------------------------------
>  $ git bisect reset <commit>
>  ------------------------------------------------

and

> +[synopsis]
>  ------------------------------------------------
>  git bisect old [<rev>]
>  ------------------------------------------------

were a bit surprising and confusing.  They are not exactly command
syntax definitions (which is the SYNOPSIS section is about), but
examples of usage.  The one with '$' command line prompt feels
particularly confusing, as the prompt is not something that the
end-user gives, unlike what we write in the synopsis section.

Other than that, this is quite exciting.

Copy link
Copy Markdown

@gitgitgadget gitgitgadget Bot May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Junio C Hamano <gitster@pobox.com> writes:

>> +[synopsis]
>>  ------------------------------------------------
>>  $ git bisect reset <commit>
>>  ------------------------------------------------
>
> and
>
>> +[synopsis]
>>  ------------------------------------------------
>>  git bisect old [<rev>]
>>  ------------------------------------------------
>
> were a bit surprising and confusing.  They are not exactly command
> syntax definitions (which is the SYNOPSIS section is about), but
> examples of usage.  The one with '$' command line prompt feels
> particularly confusing, as the prompt is not something that the
> end-user gives, unlike what we write in the synopsis section.
>
> Other than that, this is quite exciting.

Well, my local test with asciidoctor did not barf, but it seems that
the documentation pipeline run in GitHub Actions CI is unhappy.

https://github.com/git/git/actions/runs/26008649802/job/76444895183#step:4:4846

I do not know what the differences among the three environments
(counting your development environment---only one of which fails)
are offhand.

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

[blockdef-listing]
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[]
Expand All @@ -93,6 +96,9 @@ 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'"

[blockdef-listing]
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[]
6 changes: 3 additions & 3 deletions Documentation/config/am.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
am.keepcr::
`am.keepcr`::
If true, linkgit:git-am[1] will call linkgit:git-mailsplit[1]
for patches in mbox format with parameter `--keep-cr`. In this
case linkgit:git-mailsplit[1] will
not remove `\r` from lines ending with `\r\n`. Can be overridden
by giving `--no-keep-cr` from the command line.

am.threeWay::
`am.threeWay`::
By default, linkgit:git-am[1] will fail if the patch does not
apply cleanly. When set to true, this setting tells
linkgit:git-am[1] to fall back on 3-way merge if the patch
records the identity of blobs it is supposed to apply to and we
have those blobs available locally (equivalent to giving the
`--3way` option from the command line). Defaults to `false`.

am.messageId::
`am.messageId`::
Add a `Message-ID` trailer based on the email header to the
commit when using linkgit:git-am[1] (see
linkgit:git-interpret-trailers[1]). See also the `--message-id`
Expand Down
17 changes: 11 additions & 6 deletions Documentation/config/apply.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
apply.ignoreWhitespace::
When set to 'change', tells 'git apply' to ignore changes in
`apply.ignoreWhitespace`::
When set to `change`, tells `git apply` to ignore changes in
whitespace, in the same way as the `--ignore-space-change`
option.
When set to one of: no, none, never, false, it tells 'git apply' to
When set to one of: `no`, `none`, `never`, `false`, it tells `git apply` to
respect all whitespace differences.
ifndef::git-apply[]
See linkgit:git-apply[1].
endif::git-apply[]

apply.whitespace::
Tells 'git apply' how to handle whitespace, in the same way
as the `--whitespace` option. See linkgit:git-apply[1].
`apply.whitespace`::
Tells `git apply` how to handle whitespace, in the same way
as the `--whitespace` option.
ifndef::git-apply[]
See linkgit:git-apply[1].
endif::git-apply[]
36 changes: 18 additions & 18 deletions Documentation/config/grep.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
grep.lineNumber::
If set to true, enable `-n` option by default.
`grep.lineNumber`::
If set to `true`, enable `-n` option by default.

grep.column::
If set to true, enable the `--column` option by default.
`grep.column`::
If set to `true`, enable the `--column` option by default.

grep.patternType::
Set the default matching behavior. Using a value of 'basic', 'extended',
'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
`grep.patternType`::
Set the default matching behavior. Using a value of `basic`, `extended`,
`fixed`, or `perl` will enable the `--basic-regexp`, `--extended-regexp`,
`--fixed-strings`, or `--perl-regexp` option accordingly, while the
value 'default' will use the `grep.extendedRegexp` option to choose
between 'basic' and 'extended'.
value `default` will use the `grep.extendedRegexp` option to choose
between `basic` and `extended`.

grep.extendedRegexp::
If set to true, enable `--extended-regexp` option by default. This
`grep.extendedRegexp`::
If set to `true`, enable `--extended-regexp` option by default. This
option is ignored when the `grep.patternType` option is set to a value
other than 'default'.
other than `default`.

grep.threads::
`grep.threads`::
Number of grep worker threads to use. If unset (or set to 0), Git will
use as many threads as the number of logical cores available.

grep.fullName::
If set to true, enable `--full-name` option by default.
`grep.fullName`::
If set to `true`, enable `--full-name` option by default.

grep.fallbackToNoIndex::
If set to true, fall back to `git grep --no-index` if `git grep`
is executed outside of a git repository. Defaults to false.
`grep.fallbackToNoIndex`::
If set to `true`, fall back to `git grep --no-index` if `git grep`
is executed outside of a git repository. Defaults to `false`.
30 changes: 15 additions & 15 deletions Documentation/config/imap.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,44 @@
imap.folder::
`imap.folder`::
The folder to drop the mails into, which is typically the Drafts
folder. For example: `INBOX.Drafts`, `INBOX/Drafts` or
`[Gmail]/Drafts`. The IMAP folder to interact with MUST be specified;
the value of this configuration variable is used as the fallback
default value when the `--folder` option is not given.

imap.tunnel::
`imap.tunnel`::
Command used to set up a tunnel to the IMAP server through which
commands will be piped instead of using a direct network connection
to the server. Required when imap.host is not set.
to the server. Required when `imap.host` is not set.

imap.host::
`imap.host`::
A URL identifying the server. Use an `imap://` prefix for non-secure
connections and an `imaps://` prefix for secure connections.
Ignored when imap.tunnel is set, but required otherwise.
Ignored when `imap.tunnel` is set, but required otherwise.

imap.user::
`imap.user`::
The username to use when logging in to the server.

imap.pass::
`imap.pass`::
The password to use when logging in to the server.

imap.port::
`imap.port`::
An integer port number to connect to on the server.
Defaults to 143 for imap:// hosts and 993 for imaps:// hosts.
Ignored when imap.tunnel is set.
Defaults to 143 for `imap://` hosts and 993 for `imaps://` hosts.
Ignored when `imap.tunnel` is set.

imap.sslverify::
`imap.sslverify`::
A boolean to enable/disable verification of the server certificate
used by the SSL/TLS connection. Default is `true`. Ignored when
imap.tunnel is set.
`imap.tunnel` is set.

imap.preformattedHTML::
`imap.preformattedHTML`::
A boolean to enable/disable the use of html encoding when sending
a patch. An html encoded patch will be bracketed with <pre>
a patch. An html encoded patch will be bracketed with `<pre>`
and have a content type of text/html. Ironically, enabling this
option causes Thunderbird to send the patch as a plain/text,
format=fixed email. Default is `false`.

imap.authMethod::
`imap.authMethod`::
Specify the authentication method for authenticating with the IMAP server.
If Git was built with the NO_CURL option, or if your curl version is older
than 7.34.0, or if you're running git-imap-send with the `--no-curl`
Expand Down
2 changes: 1 addition & 1 deletion Documentation/format-patch-caveats.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,6 @@ repositories. This goes to show that this behavior does not only impact
email workflows.

Given these limitations, one might be tempted to use a general-purpose
utility like patch(1) instead. However, patch(1) will not only look for
utility like `patch`(1) instead. However, `patch`(1) will not only look for
unindented diffs (like linkgit:git-am[1]) but will try to apply indented
diffs as well.
4 changes: 2 additions & 2 deletions Documentation/format-patch-end-of-commit-message.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
Any line that is of the form:

* three-dashes and end-of-line, or
* a line that begins with "diff -", or
* a line that begins with "Index: "
* a line that begins with `diff -`, or
* a line that begins with `Index: `

is taken as the beginning of a patch, and the commit log message
is terminated before the first occurrence of such a line.
Loading
Loading