From a34d1d53a6c54b284b4c75c0dc7e5887f3952708 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jean-No=C3=ABl=20Avila?= Date: Fri, 6 Feb 2026 04:12:26 +0000 Subject: [PATCH] doc: convert git-show to synopsis style MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * add synopsis block definition in asciidoc.conf.in * convert commands to synopsis style * use __ for arguments * minor formatting fixes Reviewed-by: Kristoffer Haugsbakk Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- Documentation/asciidoc.conf.in | 6 ++ Documentation/git-show.adoc | 16 +-- Documentation/pretty-formats.adoc | 169 +++++++++++++++++------------- 3 files changed, 111 insertions(+), 80 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 @@ -81,12 +81,18 @@ endif::backend-xhtml11[] ifdef::backend-docbook[] ifdef::doctype-manpage[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::doctype-manpage[] endif::backend-docbook[] ifdef::backend-xhtml11[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::backend-xhtml11[] 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' [] [...] +[synopsis] +git show [] [...] 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`. 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. @@ -34,8 +34,8 @@ This manual page describes only the most frequently used options. OPTIONS ------- -...:: - The names of objects to show (defaults to 'HEAD'). +`...`:: + 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]. diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc index 2121e8e1df..5405e57a60 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` - - +`oneline`:: ++ +[synopsis] +-- + +-- + This is designed to be as compact as possible. -* `short` - - commit - Author: - - - -* `medium` - - commit - Author: - Date: - - +`short`:: ++ +[synopsis] +-- +commit +Author: - + +-- -* `full` +`medium`:: ++ +[synopsis] +-- +commit +Author: +Date: - commit - Author: - Commit: + - + +-- - +`full`:: ++ +[synopsis] +-- +commit +Author: +Commit: -* `fuller` + - commit - Author: - AuthorDate: - Commit: - CommitDate: + +-- - +`fuller`:: ++ +[synopsis] +-- +commit +Author: +AuthorDate: +Commit: +CommitDate: - + -* `reference` + +-- - (, ) +`reference`:: ++ +[synopsis] +-- + (, ) +-- + 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, @@ -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 - From: - Date: - Subject: [PATCH] +`email`:: ++ +[synopsis] +-- +From +From: +Date: +Subject: [PATCH] - + +-- -* `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:`:: The `format:` 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 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 @@ -181,8 +204,11 @@ The placeholders are: ++%><|(++__++)++:: similar to ++%<(++__++)++, ++%<|(++__++)++ 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,19 @@ 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=`: Shown before the list of ref names. Defaults to "{nbsp}++(++". -** `suffix=`: Shown after the list of ref names. Defaults to "+)+". -** `separator=`: Shown between ref names. Defaults to "+,+{nbsp}". -** `pointer=`: Shown between HEAD and the branch it points to, if any. - Defaults to "{nbsp}++->++{nbsp}". -** `tag=`: Shown before tag names. Defaults to "`tag:`{nbsp}". +`prefix=`;; Shown before the list of ref names. Defaults to "{nbsp}++(++". +`suffix=`;; Shown after the list of ref names. Defaults to "+)+". +`separator=`;; Shown between ref names. Defaults to "+,+{nbsp}". +`pointer=`;; Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}->{nbsp}". +`tag=`;; 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= )++ --- +--------------------- + %(decorate:prefix=,suffix=,tag=,separator= ) +--------------------- ++%(describe++`[: