{"thread":{"id":"65436","subject":"[PATCH 0/4] Doc difftool","startedAt":"2026-04-04T17:12:50Z","lastAt":"2026-04-04T17:12:55Z","messageCount":5,"participants":["Jean-Noël Avila via GitGitGadget"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"540903","messageId":"pull.2077.git.1775322767.gitgitgadget@gmail.com","threadId":"65436","inReplyTo":null,"subject":"[PATCH 0/4] Doc difftool","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-04-04T17:12:43Z","receivedAt":"2026-04-04T17:12:50Z","isPatch":true,"body":"This is another set of changes to convert the manual pages to synopsis\nstyle.\n\nNothing noteworthy to add, pretty straight-forward.\n\nJean-Noël Avila (4):\n  doc: convert git-difftool manual page to synopsis style\n  doc: convert git-range-diff manual page to synopsis style\n  doc: convert git-shortlog manual page to synopsis style\n  doc: convert git-describe manual page to synopsis style\n\n Documentation/config/difftool.adoc  | 24 ++++----\n Documentation/config/mergetool.adoc |  8 +--\n Documentation/git-describe.adoc     | 96 ++++++++++++++---------------\n Documentation/git-difftool.adoc     | 80 ++++++++++++------------\n Documentation/git-range-diff.adoc   | 50 +++++++--------\n Documentation/git-shortlog.adoc     | 60 +++++++++---------\n 6 files changed, 159 insertions(+), 159 deletions(-)\n\n\nbase-commit: 270e10ad6dda3379ea0da7efd11e4fbf2cd7a325\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2077%2Fjnavila%2Fdoc_difftool-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2077/jnavila/doc_difftool-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2077\n-- \ngitgitgadget\n"},{"id":"540904","messageId":"f9d931db328024fa7a437fd80580dce6cea673d8.1775322767.git.gitgitgadget@gmail.com","threadId":"65436","inReplyTo":"pull.2077.git.1775322767.gitgitgadget@gmail.com","subject":"[PATCH 1/4] doc: convert git-difftool manual page to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-04-04T17:12:44Z","receivedAt":"2026-04-04T17:12:51Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n     * convert commands to synopsis style\n     * use _<placeholder>_ for arguments\n     * fix conditional text to sentence limits\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/difftool.adoc  | 24 ++++-----\n Documentation/config/mergetool.adoc |  8 +--\n Documentation/git-difftool.adoc     | 80 ++++++++++++++---------------\n 3 files changed, 56 insertions(+), 56 deletions(-)\n\ndiff --git a/Documentation/config/difftool.adoc b/Documentation/config/difftool.adoc\nindex 4f7d40ce24..1b8d483813 100644\n--- a/Documentation/config/difftool.adoc\n+++ b/Documentation/config/difftool.adoc\n@@ -1,43 +1,43 @@\n-diff.tool::\n+`diff.tool`::\n \tControls which diff tool is used by linkgit:git-difftool[1].\n \tThis variable overrides the value configured in `merge.tool`.\n \tThe list below shows the valid built-in values.\n \tAny other value is treated as a custom diff tool and requires\n-\tthat a corresponding difftool.<tool>.cmd variable is defined.\n+\tthat a corresponding `difftool.<tool>.cmd` variable is defined.\n \n-diff.guitool::\n+`diff.guitool`::\n \tControls which diff tool is used by linkgit:git-difftool[1] when\n-\tthe -g/--gui flag is specified. This variable overrides the value\n+\tthe `-g`/`--gui` flag is specified. This variable overrides the value\n \tconfigured in `merge.guitool`. The list below shows the valid\n \tbuilt-in values. Any other value is treated as a custom diff tool\n-\tand requires that a corresponding difftool.<guitool>.cmd variable\n+\tand requires that a corresponding `difftool.<guitool>.cmd` variable\n \tis defined.\n \n include::{build_dir}/mergetools-diff.adoc[]\n \n-difftool.<tool>.cmd::\n+`difftool.<tool>.cmd`::\n \tSpecify the command to invoke the specified diff tool.\n \tThe specified command is evaluated in shell with the following\n-\tvariables available:  'LOCAL' is set to the name of the temporary\n-\tfile containing the contents of the diff pre-image and 'REMOTE'\n+\tvariables available: `LOCAL` is set to the name of the temporary\n+\tfile containing the contents of the diff pre-image and `REMOTE`\n \tis set to the name of the temporary file containing the contents\n \tof the diff post-image.\n +\n See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.\n \n-difftool.<tool>.path::\n+`difftool.<tool>.path`::\n \tOverride the path for the given tool.  This is useful in case\n \tyour tool is not in the PATH.\n \n-difftool.trustExitCode::\n+`difftool.trustExitCode`::\n \tExit difftool if the invoked diff tool returns a non-zero exit status.\n +\n See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.\n \n-difftool.prompt::\n+`difftool.prompt`::\n \tPrompt before each invocation of the diff tool.\n \n-difftool.guiDefault::\n+`difftool.guiDefault`::\n \tSet `true` to use the `diff.guitool` by default (equivalent to specifying\n \tthe `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool`\n \tdepending on the presence of a `DISPLAY` environment variable value. The\ndiff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc\nindex 7064f5a462..7afdcad92b 100644\n--- a/Documentation/config/mergetool.adoc\n+++ b/Documentation/config/mergetool.adoc\n@@ -52,13 +52,13 @@\n \tif `merge.tool` is configured as _<variant>_), Git will consult\n \t`mergetool.<variant>.layout` to determine the tool's layout. If the\n \tvariant-specific configuration is not available, `vimdiff` ' s is used as\n-\tfallback.  If that too is not available, a default layout with 4 windows\n-\twill be used.  To configure the layout, see the 'BACKEND SPECIFIC HINTS'\n+\tfallback. If that too is not available, a default layout with 4 windows\n+\twill be used.\n ifdef::git-mergetool[]\n-\tsection.\n+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section.\n endif::[]\n ifndef::git-mergetool[]\n-\tsection in linkgit:git-mergetool[1].\n+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section in linkgit:git-mergetool[1].\n endif::[]\n \n `mergetool.hideResolved`::\ndiff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc\nindex 064bc68347..dd7cacf95e 100644\n--- a/Documentation/git-difftool.adoc\n+++ b/Documentation/git-difftool.adoc\n@@ -7,64 +7,64 @@ git-difftool - Show changes using common diff tools\n \n SYNOPSIS\n --------\n-[verse]\n-'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]\n+[synopsis]\n+git difftool [<options>] [<commit> [<commit>]] [--] [<path>...]\n \n DESCRIPTION\n -----------\n-'git difftool' is a Git command that allows you to compare and edit files\n-between revisions using common diff tools.  'git difftool' is a frontend\n-to 'git diff' and accepts the same options and arguments. See\n+`git difftool` is a Git command that allows you to compare and edit files\n+between revisions using common diff tools. `git difftool` is a frontend\n+to `git diff` and accepts the same options and arguments. See\n linkgit:git-diff[1].\n \n OPTIONS\n -------\n--d::\n---dir-diff::\n+`-d`::\n+`--dir-diff`::\n \tCopy the modified files to a temporary location and perform\n \ta directory diff on them. This mode never prompts before\n \tlaunching the diff tool.\n \n--y::\n---no-prompt::\n+`-y`::\n+`--no-prompt`::\n \tDo not prompt before launching a diff tool.\n \n---prompt::\n+`--prompt`::\n \tPrompt before each invocation of the diff tool.\n \tThis is the default behaviour; the option is provided to\n \toverride any configuration settings.\n \n---rotate-to=<file>::\n-\tStart showing the diff for the given path,\n+`--rotate-to=<file>`::\n+\tStart showing the diff for _<file>_,\n \tthe paths before it will move to the end and output.\n \n---skip-to=<file>::\n-\tStart showing the diff for the given path, skipping all\n+`--skip-to=<file>`::\n+\tStart showing the diff for _<file>_, skipping all\n \tthe paths before it.\n \n--t <tool>::\n---tool=<tool>::\n-\tUse the diff tool specified by <tool>.  Valid values include\n+`-t <tool>`::\n+`--tool=<tool>`::\n+\tUse the diff tool specified by _<tool>_. Valid values include\n \temerge, kompare, meld, and vimdiff. Run `git difftool --tool-help`\n-\tfor the list of valid <tool> settings.\n+\tfor the list of valid _<tool>_ settings.\n +\n-If a diff tool is not specified, 'git difftool'\n+If a diff tool is not specified, `git difftool`\n will use the configuration variable `diff.tool`.  If the\n-configuration variable `diff.tool` is not set, 'git difftool'\n+configuration variable `diff.tool` is not set, `git difftool`\n will pick a suitable default.\n +\n You can explicitly provide a full path to the tool by setting the\n configuration variable `difftool.<tool>.path`. For example, you\n can configure the absolute path to kdiff3 by setting\n-`difftool.kdiff3.path`. Otherwise, 'git difftool' assumes the\n+`difftool.kdiff3.path`. Otherwise, `git difftool` assumes the\n tool is available in PATH.\n +\n Instead of running one of the known diff tools,\n-'git difftool' can be customized to run an alternative program\n+`git difftool` can be customized to run an alternative program\n by specifying the command line to invoke in a configuration\n variable `difftool.<tool>.cmd`.\n +\n-When 'git difftool' is invoked with this tool (either through the\n+When `git difftool` is invoked with this tool (either through the\n `-t` or `--tool` option or the `diff.tool` configuration variable)\n the configured command line will be invoked with the following\n variables available: `$LOCAL` is set to the name of the temporary\n@@ -74,30 +74,30 @@ of the diff post-image.  `$MERGED` is the name of the file which is\n being compared. `$BASE` is provided for compatibility\n with custom merge tool commands and has the same value as `$MERGED`.\n \n---tool-help::\n+`--tool-help`::\n \tPrint a list of diff tools that may be used with `--tool`.\n \n---symlinks::\n---no-symlinks::\n-\t'git difftool''s default behavior is to create symlinks to the\n+`--symlinks`::\n+`--no-symlinks`::\n+\t`git difftool`'s default behavior is to create symlinks to the\n \tworking tree when run in `--dir-diff` mode and the right-hand\n \tside of the comparison yields the same content as the file in\n \tthe working tree.\n +\n-Specifying `--no-symlinks` instructs 'git difftool' to create copies\n+Specifying `--no-symlinks` instructs `git difftool` to create copies\n instead.  `--no-symlinks` is the default on Windows.\n \n--x <command>::\n---extcmd=<command>::\n+`-x <command>`::\n+`--extcmd=<command>`::\n \tSpecify a custom command for viewing diffs.\n-\t'git-difftool' ignores the configured defaults and runs\n+\t`git-difftool` ignores the configured defaults and runs\n \t`<command> $LOCAL $REMOTE` when this option is specified.\n \tAdditionally, `$BASE` is set in the environment.\n \n--g::\n---gui::\n---no-gui::\n-\tWhen 'git-difftool' is invoked with the `-g` or `--gui` option\n+`-g`::\n+`--gui`::\n+`--no-gui`::\n+\tWhen `git-difftool` is invoked with the `-g` or `--gui` option\n \tthe default diff tool will be read from the configured\n \t`diff.guitool` variable instead of `diff.tool`. This may be\n \tselected automatically using the configuration variable\n@@ -106,20 +106,20 @@ instead.  `--no-symlinks` is the default on Windows.\n \tfallback in the order of `merge.guitool`, `diff.tool`,\n \t`merge.tool` until a tool is found.\n \n---trust-exit-code::\n---no-trust-exit-code::\n+`--trust-exit-code`::\n+`--no-trust-exit-code`::\n \tErrors reported by the diff tool are ignored by default.\n-\tUse `--trust-exit-code` to make 'git-difftool' exit when an\n+\tUse `--trust-exit-code` to make `git-difftool` exit when an\n \tinvoked diff tool returns a non-zero exit code.\n +\n-'git-difftool' will forward the exit code of the invoked tool when\n+`git-difftool` will forward the exit code of the invoked tool when\n `--trust-exit-code` is used.\n \n See linkgit:git-diff[1] for the full list of supported options.\n \n CONFIGURATION\n -------------\n-'git difftool' falls back to 'git mergetool' config variables when the\n+`git difftool` falls back to `git mergetool` config variables when the\n difftool equivalents have not been defined.\n \n include::includes/cmd-config-section-rest.adoc[]\n-- \ngitgitgadget\n\n"},{"id":"540905","messageId":"4e14058f96e7ab49741fd77a5549b8730d046e1e.1775322767.git.gitgitgadget@gmail.com","threadId":"65436","inReplyTo":"pull.2077.git.1775322767.gitgitgadget@gmail.com","subject":"[PATCH 2/4] doc: convert git-range-diff manual page to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-04-04T17:12:45Z","receivedAt":"2026-04-04T17:12:53Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n     * convert commands and options to synopsis style\n     * use _<placeholder>_ for arguments\n     * small style fixes\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-range-diff.adoc | 50 +++++++++++++++----------------\n 1 file changed, 25 insertions(+), 25 deletions(-)\n\ndiff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc\nindex b5e85d37f1..8805570845 100644\n--- a/Documentation/git-range-diff.adoc\n+++ b/Documentation/git-range-diff.adoc\n@@ -7,8 +7,8 @@ git-range-diff - Compare two commit ranges (e.g. two versions of a branch)\n \n SYNOPSIS\n --------\n-[verse]\n-'git range-diff' [--color=[<when>]] [--no-color] [<diff-options>]\n+[synopsis]\n+git range-diff [--color=[<when>]] [--no-color] [<diff-options>]\n \t[--no-dual-color] [--creation-factor=<factor>]\n \t[--left-only | --right-only] [--diff-merges=<format>]\n \t[--remerge-diff]\n@@ -21,14 +21,14 @@ DESCRIPTION\n This command shows the differences between two versions of a patch\n series, or more generally, two commit ranges (ignoring merge commits).\n \n-In the presence of `<path>` arguments, these commit ranges are limited\n+In the presence of _<path>_ arguments, these commit ranges are limited\n accordingly.\n \n To that end, it first finds pairs of commits from both commit ranges\n that correspond with each other. Two commits are said to correspond when\n the diff between their patches (i.e. the author information, the commit\n message and the commit diff) is reasonably small compared to the\n-patches' size. See ``Algorithm`` below for details.\n+patches' size. See 'Algorithm' below for details.\n \n Finally, the list of matching commits is shown in the order of the\n second commit range, with unmatched commits being inserted just after\n@@ -37,7 +37,7 @@ all of their ancestors have been shown.\n There are three ways to specify the commit ranges:\n \n - `<range1> <range2>`: Either commit range can be of the form\n-  `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See `SPECIFYING RANGES`\n+  `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See 'SPECIFYING RANGES'\n   in linkgit:gitrevisions[7] for more details.\n \n - `<rev1>...<rev2>`. This is equivalent to\n@@ -48,7 +48,7 @@ There are three ways to specify the commit ranges:\n \n OPTIONS\n -------\n---no-dual-color::\n+`--no-dual-color`::\n \tWhen the commit diffs differ, `git range-diff` recreates the\n \toriginal diffs' coloring, and adds outer -/+ diff markers with\n \tthe *background* being red/green to make it easier to see e.g.\n@@ -56,33 +56,33 @@ OPTIONS\n +\n Additionally, the commit diff lines that are only present in the first commit\n range are shown \"dimmed\" (this can be overridden using the `color.diff.<slot>`\n-config setting where `<slot>` is one of `contextDimmed`, `oldDimmed` and\n+config setting where _<slot>_ is one of `contextDimmed`, `oldDimmed` and\n `newDimmed`), and the commit diff lines that are only present in the second\n commit range are shown in bold (which can be overridden using the config\n-settings `color.diff.<slot>` with `<slot>` being one of `contextBold`,\n+settings `color.diff.<slot>` with _<slot>_ being one of `contextBold`,\n `oldBold` or `newBold`).\n +\n This is known to `range-diff` as \"dual coloring\". Use `--no-dual-color`\n to revert to color all lines according to the outer diff markers\n (and completely ignore the inner diff when it comes to color).\n \n---creation-factor=<percent>::\n-\tSet the creation/deletion cost fudge factor to `<percent>`.\n+`--creation-factor=<percent>`::\n+\tSet the creation/deletion cost fudge factor to _<percent>_.\n \tDefaults to 60. Try a larger value if `git range-diff` erroneously\n \tconsiders a large change a total rewrite (deletion of one commit\n \tand addition of another), and a smaller one in the reverse case.\n-\tSee the ``Algorithm`` section below for an explanation of why this is\n+\tSee the 'Algorithm' section below for an explanation of why this is\n \tneeded.\n \n---left-only::\n+`--left-only`::\n \tSuppress commits that are missing from the first specified range\n-\t(or the \"left range\" when using the `<rev1>...<rev2>` format).\n+\t(or the \"left range\" when using the `<rev1>...<rev2>` form).\n \n---right-only::\n+`--right-only`::\n \tSuppress commits that are missing from the second specified range\n-\t(or the \"right range\" when using the `<rev1>...<rev2>` format).\n+\t(or the \"right range\" when using the `<rev1>...<rev2>` form).\n \n---diff-merges=<format>::\n+`--diff-merges=<format>`::\n \tInstead of ignoring merge commits, generate diffs for them using the\n \tcorresponding `--diff-merges=<format>` option of linkgit:git-log[1],\n \tand include them in the comparison.\n@@ -93,30 +93,30 @@ have produced. In other words, if a merge commit is the result of a\n non-conflicting `git merge`, the `remerge` mode will represent it with an empty\n diff.\n \n---remerge-diff::\n+`--remerge-diff`::\n \tConvenience option, equivalent to `--diff-merges=remerge`.\n \n---notes[=<ref>]::\n---no-notes::\n+`--notes[=<ref>]`::\n+`--no-notes`::\n \tThis flag is passed to the `git log` program\n \t(see linkgit:git-log[1]) that generates the patches.\n \n-<range1> <range2>::\n+`<range1> <range2>`::\n \tCompare the commits specified by the two ranges, where\n-\t`<range1>` is considered an older version of `<range2>`.\n+\t_<range1>_ is considered an older version of _<range2>_.\n \n-<rev1>...<rev2>::\n+`<rev1>...<rev2>`::\n \tEquivalent to passing `<rev2>..<rev1>` and `<rev1>..<rev2>`.\n \n-<base> <rev1> <rev2>::\n+`<base> <rev1> <rev2>`::\n \tEquivalent to passing `<base>..<rev1>` and `<base>..<rev2>`.\n-\tNote that `<base>` does not need to be the exact branch point\n+\tNote that _<base>_ does not need to be the exact branch point\n \tof the branches. Example: after rebasing a branch `my-topic`,\n \t`git range-diff my-topic@{u} my-topic@{1} my-topic` would\n \tshow the differences introduced by the rebase.\n \n `git range-diff` also accepts the regular diff options (see\n-linkgit:git-diff[1]), most notably the `--color=[<when>]` and\n+linkgit:git-diff[1]), most notably the `--color[=<when>]` and\n `--no-color` options. These options are used when generating the \"diff\n between patches\", i.e. to compare the author, commit message and diff of\n corresponding old/new commits. There is currently no means to tweak most of the\n-- \ngitgitgadget\n\n"},{"id":"540906","messageId":"5c20164270ab0971b7f4e429d4ec5cffbde16c55.1775322767.git.gitgitgadget@gmail.com","threadId":"65436","inReplyTo":"pull.2077.git.1775322767.gitgitgadget@gmail.com","subject":"[PATCH 3/4] doc: convert git-shortlog manual page to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-04-04T17:12:46Z","receivedAt":"2026-04-04T17:12:54Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n     * convert commands and options to synopsis style\n     * use _<placeholder>_ for arguments\n     * small style fixes\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-shortlog.adoc | 60 ++++++++++++++++-----------------\n 1 file changed, 30 insertions(+), 30 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc\nindex a11b57c1cd..e067d39b38 100644\n--- a/Documentation/git-shortlog.adoc\n+++ b/Documentation/git-shortlog.adoc\n@@ -3,63 +3,63 @@ git-shortlog(1)\n \n NAME\n ----\n-git-shortlog - Summarize 'git log' output\n+git-shortlog - Summarize `git log` output\n \n SYNOPSIS\n --------\n-[verse]\n-'git shortlog' [<options>] [<revision-range>] [[--] <path>...]\n-git log --pretty=short | 'git shortlog' [<options>]\n+[synopsis]\n+git shortlog [<options>] [<revision-range>] [[--] <path>...]\n+git log --pretty=short | git shortlog [<options>]\n \n DESCRIPTION\n -----------\n-Summarizes 'git log' output in a format suitable for inclusion\n+Summarizes `git log` output in a format suitable for inclusion\n in release announcements. Each commit will be grouped by author and title.\n \n Additionally, \"[PATCH]\" will be stripped from the commit description.\n \n If no revisions are passed on the command line and either standard input\n-is not a terminal or there is no current branch, 'git shortlog' will\n+is not a terminal or there is no current branch, `git shortlog` will\n output a summary of the log read from standard input, without\n reference to the current repository.\n \n OPTIONS\n -------\n \n--n::\n---numbered::\n+`-n`::\n+`--numbered`::\n \tSort output according to the number of commits per author instead\n \tof author alphabetic order.\n \n--s::\n---summary::\n+`-s`::\n+`--summary`::\n \tSuppress commit description and provide a commit count summary only.\n \n--e::\n---email::\n+`-e`::\n+`--email`::\n \tShow the email address of each author.\n \n---format[=<format>]::\n+`--format[=<format>]`::\n \tInstead of the commit subject, use some other information to\n-\tdescribe each commit.  '<format>' can be any string accepted\n-\tby the `--format` option of 'git log', such as '* [%h] %s'.\n-\t(See the \"PRETTY FORMATS\" section of linkgit:git-log[1].)\n+\tdescribe each commit. _<format>_ can be any string accepted\n+\tby the `--format` option of `git log`, such as '* [%h] %s'.\n+\t(See the 'PRETTY FORMATS' section of linkgit:git-log[1].)\n +\n Each pretty-printed commit will be rewrapped before it is shown.\n \n---date=<format>::\n+`--date=<format>`::\n \tShow dates formatted according to the given date string. (See\n-\tthe `--date` option in the \"Commit Formatting\" section of\n+\tthe `--date` option in the 'Commit Formatting' section of\n \tlinkgit:git-log[1]). Useful with `--group=format:<format>`.\n \n---group=<type>::\n-\tGroup commits based on `<type>`. If no `--group` option is\n-\tspecified, the default is `author`. `<type>` is one of:\n+`--group=<type>`::\n+\tGroup commits based on _<type>_. If no `--group` option is\n+\tspecified, the default is `author`. _<type>_ is one of:\n +\n --\n  - `author`, commits are grouped by author\n  - `committer`, commits are grouped by committer (the same as `-c`)\n- - `trailer:<field>`, the `<field>` is interpreted as a case-insensitive\n+ - `trailer:<field>`, the _<field>_ is interpreted as a case-insensitive\n    commit message trailer (see linkgit:git-interpret-trailers[1]). For\n    example, if your project uses `Reviewed-by` trailers, you might want\n    to see who has been reviewing with\n@@ -76,7 +76,7 @@ unless the `--email` option is specified. If the value cannot be parsed\n as an identity, it will be taken literally and completely.\n \n  - `format:<format>`, any string accepted by the `--format` option of\n-   'git log'. (See the \"PRETTY FORMATS\" section of\n+   `git log`. (See the 'PRETTY FORMATS' section of\n    linkgit:git-log[1].)\n --\n +\n@@ -85,11 +85,11 @@ value (but again, only once per unique value in that commit). For\n example, `git shortlog --group=author --group=trailer:co-authored-by`\n counts both authors and co-authors.\n \n--c::\n---committer::\n+`-c`::\n+`--committer`::\n \tThis is an alias for `--group=committer`.\n \n--w[<width>[,<indent1>[,<indent2>]]]::\n+`-w[<width>[,<indent1>[,<indent2>]]]`::\n \tLinewrap the output by wrapping each line at `width`.  The first\n \tline of each entry is indented by `indent1` spaces, and the second\n \tand subsequent lines are indented by `indent2` spaces. `width`,\n@@ -98,16 +98,16 @@ counts both authors and co-authors.\n If width is `0` (zero) then indent the lines of the output without wrapping\n them.\n \n-<revision-range>::\n+`<revision-range>`::\n \tShow only commits in the specified revision range.  When no\n-\t<revision-range> is specified, it defaults to `HEAD` (i.e. the\n+\t_<revision-range>_ is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit).  `origin..HEAD`\n \tspecifies all the commits reachable from the current commit\n \t(i.e. `HEAD`), but not from `origin`. For a complete list of\n-\tways to spell <revision-range>, see the \"Specifying Ranges\"\n+\tways to spell _<revision-range>_, see the 'Specifying Ranges'\n \tsection of linkgit:gitrevisions[7].\n \n-[--] <path>...::\n+`[--] <path>...`::\n \tConsider only commits that are enough to explain how the files\n \tthat match the specified paths came to be.\n +\n-- \ngitgitgadget\n\n"},{"id":"540907","messageId":"5de7aa41e652e5b75479f31926802e937cbc01f4.1775322767.git.gitgitgadget@gmail.com","threadId":"65436","inReplyTo":"pull.2077.git.1775322767.gitgitgadget@gmail.com","subject":"[PATCH 4/4] doc: convert git-describe manual page to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-04-04T17:12:47Z","receivedAt":"2026-04-04T17:12:55Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n     * convert commands and options to synopsis style\n     * use _<placeholder>_ for arguments\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-describe.adoc | 96 ++++++++++++++++-----------------\n 1 file changed, 48 insertions(+), 48 deletions(-)\n\ndiff --git a/Documentation/git-describe.adoc b/Documentation/git-describe.adoc\nindex 08ff715709..b2cb1e47e4 100644\n--- a/Documentation/git-describe.adoc\n+++ b/Documentation/git-describe.adoc\n@@ -7,10 +7,10 @@ git-describe - Give an object a human readable name based on an available ref\n \n SYNOPSIS\n --------\n-[verse]\n-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\n-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\n-'git describe' <blob>\n+[synopsis]\n+git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]\n+git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]\n+git describe <blob>\n \n DESCRIPTION\n -----------\n@@ -22,70 +22,70 @@ abbreviated object name of the most recent commit. The result\n is a \"human-readable\" object name which can also be used to\n identify the commit to other git commands.\n \n-By default (without --all or --tags) `git describe` only shows\n+By default (without `--all` or `--tags`) `git describe` only shows\n annotated tags.  For more information about creating annotated tags\n-see the -a and -s options to linkgit:git-tag[1].\n+see the `-a` and `-s` options to linkgit:git-tag[1].\n \n If the given object refers to a blob, it will be described\n as `<commit-ish>:<path>`, such that the blob can be found\n-at `<path>` in the `<commit-ish>`, which itself describes the\n+at _<path>_ in the _<commit-ish>_, which itself describes the\n first commit in which this blob occurs in a reverse revision walk\n-from HEAD.\n+from `HEAD`.\n \n OPTIONS\n -------\n-<commit-ish>...::\n-\tCommit-ish object names to describe.  Defaults to HEAD if omitted.\n+`<commit-ish>...`::\n+\tCommit-ish object names to describe. Defaults to `HEAD` if omitted.\n \n---dirty[=<mark>]::\n---broken[=<mark>]::\n+`--dirty[=<mark>]`::\n+`--broken[=<mark>]`::\n \tDescribe the state of the working tree.  When the working\n-\ttree matches HEAD, the output is the same as \"git describe\n-\tHEAD\".  If the working tree has local modification \"-dirty\"\n+\ttree matches `HEAD`, the output is the same as `git describe HEAD`.\n+\tIf the working tree has local modification, `-dirty`\n \tis appended to it.  If a repository is corrupt and Git\n \tcannot determine if there is local modification, Git will\n-\terror out, unless `--broken' is given, which appends\n-\tthe suffix \"-broken\" instead.\n+\terror out, unless `--broken` is given, which appends\n+\tthe suffix `-broken` instead.\n \n---all::\n+`--all`::\n \tInstead of using only the annotated tags, use any ref\n \tfound in `refs/` namespace.  This option enables matching\n \tany known branch, remote-tracking branch, or lightweight tag.\n \n---tags::\n+`--tags`::\n \tInstead of using only the annotated tags, use any tag\n \tfound in `refs/tags` namespace.  This option enables matching\n \ta lightweight (non-annotated) tag.\n \n---contains::\n+`--contains`::\n \tInstead of finding the tag that predates the commit, find\n \tthe tag that comes after the commit, and thus contains it.\n-\tAutomatically implies --tags.\n+\tAutomatically implies `--tags`.\n \n---abbrev=<n>::\n+`--abbrev=<n>`::\n \tInstead of using the default number of hexadecimal digits (which\n \twill vary according to the number of objects in the repository with\n-\ta default of 7) of the abbreviated object name, use <n> digits, or\n-\tas many digits as needed to form a unique object name. An <n> of 0\n+\ta default of 7) of the abbreviated object name, use _<n>_ digits, or\n+\tas many digits as needed to form a unique object name. An _<n>_ of 0\n \twill suppress long format, only showing the closest tag.\n \n---candidates=<n>::\n+`--candidates=<n>`::\n \tInstead of considering only the 10 most recent tags as\n \tcandidates to describe the input commit-ish consider\n-\tup to <n> candidates.  Increasing <n> above 10 will take\n+\tup to _<n>_ candidates.  Increasing _<n>_ above 10 will take\n \tslightly longer but may produce a more accurate result.\n-\tAn <n> of 0 will cause only exact matches to be output.\n+\tAn _<n>_ of 0 will cause only exact matches to be output.\n \n---exact-match::\n+`--exact-match`::\n \tOnly output exact matches (a tag directly references the\n-\tsupplied commit).  This is a synonym for --candidates=0.\n+\tsupplied commit).  This is a synonym for `--candidates=0`.\n \n---debug::\n+`--debug`::\n \tVerbosely display information about the searching strategy\n \tbeing employed to standard error.  The tag name will still\n \tbe printed to standard out.\n \n---long::\n+`--long`::\n \tAlways output the long format (the tag, the number of commits\n \tand the abbreviated commit name) even when it matches a tag.\n \tThis is useful when you want to see parts of the commit object name\n@@ -94,8 +94,8 @@ OPTIONS\n \tdescribe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2\n \tthat points at object deadbee....).\n \n---match <pattern>::\n-\tOnly consider tags matching the given `glob(7)` pattern,\n+`--match <pattern>`::\n+\tOnly consider tags matching the given `glob`(7) pattern,\n \texcluding the \"refs/tags/\" prefix. If used with `--all`, it also\n \tconsiders local branches and remote-tracking references matching the\n \tpattern, excluding respectively \"refs/heads/\" and \"refs/remotes/\"\n@@ -104,22 +104,22 @@ OPTIONS\n \tmatching any of the patterns will be considered.  Use `--no-match` to\n \tclear and reset the list of patterns.\n \n---exclude <pattern>::\n-\tDo not consider tags matching the given `glob(7)` pattern, excluding\n+`--exclude <pattern>`::\n+\tDo not consider tags matching the given `glob`(7) pattern, excluding\n \tthe \"refs/tags/\" prefix. If used with `--all`, it also does not consider\n \tlocal branches and remote-tracking references matching the pattern,\n-\texcluding respectively \"refs/heads/\" and \"refs/remotes/\" prefix;\n+\texcluding respectively \"`refs/heads/`\" and \"`refs/remotes/`\" prefix;\n \treferences of other types are never considered. If given multiple times,\n \ta list of patterns will be accumulated and tags matching any of the\n-\tpatterns will be excluded. When combined with --match a tag will be\n-\tconsidered when it matches at least one --match pattern and does not\n-\tmatch any of the --exclude patterns. Use `--no-exclude` to clear and\n+\tpatterns will be excluded. When combined with `--match` a tag will be\n+\tconsidered when it matches at least one `--match` pattern and does not\n+\tmatch any of the `--exclude` patterns. Use `--no-exclude` to clear and\n \treset the list of patterns.\n \n---always::\n+`--always`::\n \tShow uniquely abbreviated commit object as fallback.\n \n---first-parent::\n+`--first-parent`::\n \tFollow only the first parent commit upon seeing a merge commit.\n \tThis is useful when you wish to not match tags on branches merged\n \tin the history of the target commit.\n@@ -139,8 +139,8 @@ an abbreviated object name for the commit itself (\"2414721\")\n at the end.\n \n The number of additional commits is the number\n-of commits which would be displayed by \"git log v1.0.4..parent\".\n-The hash suffix is \"-g\" + an unambiguous abbreviation for the tip commit\n+of commits which would be displayed by `git log v1.0.4..parent`.\n+The hash suffix is \"`-g`\" + an unambiguous abbreviation for the tip commit\n of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The\n length of the abbreviation scales as the repository grows, using the\n approximate number of objects in the repository and a bit of math\n@@ -149,12 +149,12 @@ The \"g\" prefix stands for \"git\" and is used to allow describing the version of\n a software depending on the SCM the software is managed with. This is useful\n in an environment where people may use different SCMs.\n \n-Doing a 'git describe' on a tag-name will just show the tag name:\n+Doing a `git describe` on a tag-name will just show the tag name:\n \n \t[torvalds@g5 git]$ git describe v1.0.4\n \tv1.0.4\n \n-With --all, the command can use branch heads as references, so\n+With `--all`, the command can use branch heads as references, so\n the output shows the reference path as well:\n \n \t[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2\n@@ -163,7 +163,7 @@ the output shows the reference path as well:\n \t[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^\n \theads/lt/describe-7-g975b\n \n-With --abbrev set to 0, the command can be used to find the\n+With `--abbrev` set to 0, the command can be used to find the\n closest tagname without any suffix:\n \n \t[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2\n@@ -179,13 +179,13 @@ be sufficient to disambiguate these commits.\n SEARCH STRATEGY\n ---------------\n \n-For each commit-ish supplied, 'git describe' will first look for\n+For each commit-ish supplied, `git describe` will first look for\n a tag which tags exactly that commit.  Annotated tags will always\n be preferred over lightweight tags, and tags with newer dates will\n always be preferred over tags with older dates.  If an exact match\n is found, its name will be output and searching will stop.\n \n-If an exact match was not found, 'git describe' will walk back\n+If an exact match was not found, `git describe` will walk back\n through the commit history to locate an ancestor commit which\n has been tagged.  The ancestor's tag will be output along with an\n abbreviation of the input commit-ish's SHA-1. If `--first-parent` was\n@@ -203,7 +203,7 @@ BUGS\n \n Tree objects as well as tag objects not pointing at commits, cannot be described.\n When describing blobs, the lightweight tags pointing at blobs are ignored,\n-but the blob is still described as <commit-ish>:<path> despite the lightweight\n+but the blob is still described as `<commit-ish>:<path>` despite the lightweight\n tag being favorable.\n \n GIT\n-- \ngitgitgadget\n"}]}