@matheusbsbs / matheus-bagliano / commits / a34d1d53a6

doc: convert git-show to synopsis style

* add synopsis block definition in asciidoc.conf.in * convert commands to synopsis style * use _<placeholder>_ for arguments * minor formatting fixes Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jean-Noël Avila committed Feb 6, 2026 at 04:12 UTC a34d1d53a6c54b284b4c75c0dc7e5887f3952708
3 files changed +111 -80
Documentation/asciidoc.conf.in
+6
@@ -81,12 +81,18 @@ endif::backend-xhtml11[]
81
82 ifdef::backend-docbook[]
83 ifdef::doctype-manpage[]
84 +[blockdef-open]
85 +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'"
86 +
87 [paradef-default]
88 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'"
89 endif::doctype-manpage[]
90 endif::backend-docbook[]
91
92 ifdef::backend-xhtml11[]
93 +[blockdef-open]
94 +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'"
95 +
96 [paradef-default]
97 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'"
98 endif::backend-xhtml11[]
Documentation/git-show.adoc
+8 -8
@@ -8,8 +8,8 @@ git-show - Show various types of objects
8
9 SYNOPSIS
10 --------
11 -[verse]
12 -'git show' [<options>] [<object>...]
11 +[synopsis]
12 +git show [<options>] [<object>...]
13
14 DESCRIPTION
15 -----------
@@ -17,16 +17,16 @@ Shows one or more objects (blobs, trees, tags and commits).
17
18 For commits it shows the log message and textual diff. It also
19 presents the merge commit in a special format as produced by
20 -'git diff-tree --cc'.
20 +`git diff-tree --cc`.
21
22 For tags, it shows the tag message and the referenced objects.
23
24 -For trees, it shows the names (equivalent to 'git ls-tree'
25 -with --name-only).
24 +For trees, it shows the names (equivalent to `git ls-tree`
25 +with `--name-only`).
26
27 For plain blobs, it shows the plain contents.
28
29 -Some options that 'git log' command understands can be used to
29 +Some options that `git log` command understands can be used to
30 control how the changes the commit introduces are shown.
31
32 This manual page describes only the most frequently used options.
@@ -34,8 +34,8 @@ This manual page describes only the most frequently used options.
34
35 OPTIONS
36 -------
37 -<object>...::
38 - The names of objects to show (defaults to 'HEAD').
37 +`<object>...`::
38 + The names of objects to show (defaults to `HEAD`).
39 For a more complete list of ways to spell object names, see
40 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
41
Documentation/pretty-formats.adoc
+97 -72
@@ -18,54 +18,72 @@ config option to either another format name, or a
18 linkgit:git-config[1]). Here are the details of the
19 built-in formats:
20
21 -* `oneline`
22 -
23 - <hash> <title-line>
21 +`oneline`::
22 ++
23 +[synopsis]
24 +--
25 +<hash> <title-line>
26 +--
27 +
28 This is designed to be as compact as possible.
29
27 -* `short`
28 -
29 - commit <hash>
30 - Author: <author>
31 -
32 - <title-line>
33 -
34 -* `medium`
35 -
36 - commit <hash>
37 - Author: <author>
38 - Date: <author-date>
39 -
40 - <title-line>
30 +`short`::
31 ++
32 +[synopsis]
33 +--
34 +commit <hash>
35 +Author: <author>
36
42 - <full-commit-message>
37 + <title-line>
38 +--
39
44 -* `full`
40 +`medium`::
41 ++
42 +[synopsis]
43 +--
44 +commit <hash>
45 +Author: <author>
46 +Date: <author-date>
47
46 - commit <hash>
47 - Author: <author>
48 - Commit: <committer>
48 + <title-line>
49
50 - <title-line>
50 + <full-commit-message>
51 +--
52
52 - <full-commit-message>
53 +`full`::
54 ++
55 +[synopsis]
56 +--
57 +commit <hash>
58 +Author: <author>
59 +Commit: <committer>
60
54 -* `fuller`
61 + <title-line>
62
56 - commit <hash>
57 - Author: <author>
58 - AuthorDate: <author-date>
59 - Commit: <committer>
60 - CommitDate: <committer-date>
63 + <full-commit-message>
64 +--
65
62 - <title-line>
66 +`fuller`::
67 ++
68 +[synopsis]
69 +--
70 +commit <hash>
71 +Author: <author>
72 +AuthorDate: <author-date>
73 +Commit: <committer>
74 +CommitDate: <committer-date>
75
64 - <full-commit-message>
76 + <title-line>
77
66 -* `reference`
78 + <full-commit-message>
79 +--
80
68 - <abbrev-hash> (<title-line>, <short-author-date>)
81 +`reference`::
82 ++
83 +[synopsis]
84 +--
85 +<abbrev-hash> (<title-line>, <short-author-date>)
86 +--
87 +
88 This format is used to refer to another commit in a commit message and
89 is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++. By default,
@@ -74,23 +92,24 @@ is explicitly specified. As with any `format:` with format
92 placeholders, its output is not affected by other options like
93 `--decorate` and `--walk-reflogs`.
94
77 -* `email`
78 -
79 - From <hash> <date>
80 - From: <author>
81 - Date: <author-date>
82 - Subject: [PATCH] <title-line>
95 +`email`::
96 ++
97 +[synopsis]
98 +--
99 +From <hash> <date>
100 +From: <author>
101 +Date: <author-date>
102 +Subject: [PATCH] <title-line>
103
84 - <full-commit-message>
104 +<full-commit-message>
105 +--
106
86 -* `mboxrd`
87 -+
107 +`mboxrd`::
108 Like `email`, but lines in the commit message starting with "From "
109 (preceded by zero or more ">") are quoted with ">" so they aren't
110 confused as starting a new commit.
111
92 -* `raw`
93 -+
112 +`raw`::
113 The `raw` format shows the entire commit exactly as
114 stored in the commit object. Notably, the hashes are
115 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
120 `git log --raw`. To get full object names in a raw diff format,
121 use `--no-abbrev`.
122
104 -* `format:<format-string>`
105 -+
123 +`format:<format-string>`::
124 The `format:<format-string>` format allows you to specify which information
125 you want to show. It works a little bit like printf format,
126 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.<<
138 The placeholders are:
139
140 - Placeholders that expand to a single literal character:
141 ++
142 +--
143 ++%n++:: newline
144 ++%%++:: a raw ++%++
145 ++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a
146 byte with the hexadecimal digits' value (we will call this
147 "literal formatting code" in the rest of this document).
148 +--
149
150 - Placeholders that affect formatting of later placeholders:
151 ++
152 +--
153 ++%Cred++:: switch color to red
154 ++%Cgreen++:: switch color to green
155 ++%Cblue++:: switch color to blue
@@ -181,8 +204,11 @@ The placeholders are:
204 ++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++
205 respectively, but padding both sides
206 (i.e. the text is centered)
207 +--
208
209 - Placeholders that expand to information extracted from the commit:
210 ++
211 +--
212 +%H+:: commit hash
213 +%h+:: abbreviated commit hash
214 +%T+:: tree hash
@@ -233,20 +259,19 @@ colon and zero or more comma-separated options. Option values may contain
259 literal formatting codes. These must be used for commas (`%x2C`) and closing
260 parentheses (`%x29`), due to their role in the option syntax.
261
236 -** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}++(++".
237 -** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+".
238 -** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}".
239 -** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
240 - Defaults to "{nbsp}++->++{nbsp}".
241 -** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
262 +`prefix=<value>`;; Shown before the list of ref names. Defaults to "{nbsp}++(++".
263 +`suffix=<value>`;; Shown after the list of ref names. Defaults to "+)+".
264 +`separator=<value>`;; Shown between ref names. Defaults to "+,+{nbsp}".
265 +`pointer=<value>`;; Shown between HEAD and the branch it points to, if any.
266 + Defaults to "{nbsp}->{nbsp}".
267 +`tag=<value>`;; Shown before tag names. Defaults to "`tag:`{nbsp}".
268
269 +
244 ---
270 For example, to produce decorations with no wrapping
271 or tag annotations, and spaces as separators:
247 -
248 -++%(decorate:prefix=,suffix=,tag=,separator= )++
249 ---
272 +---------------------
273 + %(decorate:prefix=,suffix=,tag=,separator= )
274 +---------------------
275
276 ++%(describe++`[:<option>,...]`++)++::
277 human-readable name, like linkgit:git-describe[1]; empty string for
@@ -254,15 +279,15 @@ undescribable commits. The `describe` string may be followed by a colon and
279 zero or more comma-separated options. Descriptions can be inconsistent when
280 tags are added or removed at the same time.
281 +
257 -** `tags[=<bool-value>]`: Instead of only considering annotated tags,
282 +`tags[=<bool-value>]`;; Instead of only considering annotated tags,
283 consider lightweight tags as well.
259 -** `abbrev=<number>`: Instead of using the default number of hexadecimal digits
284 +`abbrev=<number>`;; Instead of using the default number of hexadecimal digits
285 (which will vary according to the number of objects in the repository with a
261 - default of 7) of the abbreviated object name, use <number> digits, or as many
286 + default of 7) of the abbreviated object name, use _<number>_ digits, or as many
287 digits as needed to form a unique object name.
263 -** `match=<pattern>`: Only consider tags matching the given
288 +`match=<pattern>`;; Only consider tags matching the given
289 `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
265 -** `exclude=<pattern>`: Do not consider tags matching the given
290 +`exclude=<pattern>`;; Do not consider tags matching the given
291 `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
292
293 +%S+:: ref name given on the command line by which the commit was reached
@@ -311,7 +336,7 @@ linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by
336 a colon and zero or more comma-separated options. If any option is provided
337 multiple times, the last occurrence wins.
338 +
314 -** `key=<key>`: only show trailers with specified <key>. Matching is done
339 +`key=<key>`;; only show trailers with specified <key>. Matching is done
340 case-insensitively and trailing colon is optional. If option is
341 given multiple times trailer lines matching any of the keys are
342 shown. This option automatically enables the `only` option so that
@@ -319,21 +344,21 @@ multiple times, the last occurrence wins.
344 desired it can be disabled with `only=false`. E.g.,
345 +%(trailers:key=Reviewed-by)+ shows trailer lines with key
346 `Reviewed-by`.
322 -** `only[=<bool>]`: select whether non-trailer lines from the trailer
347 +`only[=<bool>]`;; select whether non-trailer lines from the trailer
348 block should be included.
324 -** `separator=<sep>`: specify the separator inserted between trailer
349 + `separator=<sep>`;; specify the separator inserted between trailer
350 lines. Defaults to a line feed character. The string <sep> may contain
351 the literal formatting codes described above. To use comma as
352 separator one must use `%x2C` as it would otherwise be parsed as
353 next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+
329 - shows all trailer lines whose key is "Ticket" separated by a comma
354 + shows all trailer lines whose key is `Ticket` separated by a comma
355 and a space.
331 -** `unfold[=<bool>]`: make it behave as if interpret-trailer's `--unfold`
356 +`unfold[=<bool>]`;; make it behave as if interpret-trailer's `--unfold`
357 option was given. E.g.,
358 +%(trailers:only,unfold=true)+ unfolds and shows all trailer lines.
334 -** `keyonly[=<bool>]`: only show the key part of the trailer.
335 -** `valueonly[=<bool>]`: only show the value part of the trailer.
336 -** `key_value_separator=<sep>`: specify the separator inserted between
359 +`keyonly[=<bool>]`;; only show the key part of the trailer.
360 +`valueonly[=<bool>]`;; only show the value part of the trailer.
361 +`key_value_separator=<sep>`;; specify the separator inserted between
362 the key and value of each trailer. Defaults to ": ". Otherwise it
363 shares the same semantics as `separator=<sep>` above.
364
@@ -360,9 +385,9 @@ placeholder expands to an empty string.
385 If you add a `' '` (space) after +%+ of a placeholder, a space
386 is inserted immediately before the expansion if and only if the
387 placeholder expands to a non-empty string.
388 +--
389
364 -* `tformat:`
365 -+
390 +`tformat:`::
391 The `tformat:` format works exactly like `format:`, except that it
392 provides "terminator" semantics instead of "separator" semantics. In
393 other words, each commit has the message terminator character (usually a