{"thread":{"id":"65651","subject":"[PATCH 0/5] doc: convert another batch of files to synopsis style","startedAt":"2026-05-17T20:26:59Z","lastAt":"2026-05-25T10:28:39Z","messageCount":17,"participants":["Jean-Noël Avila via GitGitGadget","Junio C Hamano","Jean-Noël AVILA"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"543486","messageId":"pull.2117.git.1779049615.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":null,"subject":"[PATCH 0/5] doc: convert another batch of files to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-17T20:26:50Z","receivedAt":"2026-05-17T20:26:59Z","isPatch":true,"body":"This time, 4 new conversions:\n\n * git-grep\n * git-am\n * git-apply\n * git-imap-send\n\nThis batch was an opportunity to test AI-helped conversion.\n\nJean-Noël Avila (5):\n doc: convert git-bisect to synopsis style\n doc: convert git-grep synopsis and options to new style\n doc: convert git-am synopsis and options to new style\n doc: convert git-apply synopsis and options to new style\n doc: convert git-imap-send synopsis and options to new style\n\n Documentation/asciidoc.conf.in | 6 +\n Documentation/config/am.adoc | 6 +-\n Documentation/config/apply.adoc | 17 +-\n Documentation/config/grep.adoc | 36 ++--\n Documentation/config/imap.adoc | 30 +--\n Documentation/format-patch-caveats.adoc | 2 +-\n .../format-patch-end-of-commit-message.adoc | 4 +-\n Documentation/git-am.adoc | 132 ++++++------\n Documentation/git-apply.adoc | 125 +++++------\n Documentation/git-bisect.adoc | 80 +++----\n Documentation/git-grep.adoc | 196 +++++++++---------\n Documentation/git-imap-send.adoc | 24 +--\n 12 files changed, 337 insertions(+), 321 deletions(-)\n\n\nbase-commit: 59ff4886a579f4bc91e976fe18590b9ae02c7a08\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2117%2Fjnavila%2Fbisect-synopsis-style-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2117/jnavila/bisect-synopsis-style-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2117\n-- \ngitgitgadget\n"},{"id":"543487","messageId":"dca7f192f1e5cdfb57682feace0a4b3a10204376.1779049615.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.git.1779049615.gitgitgadget@gmail.com","subject":"[PATCH 1/5] doc: convert git-bisect to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-17T20:26:51Z","receivedAt":"2026-05-17T20:27:00Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert Documentation/git-bisect.adoc to the modern synopsis style.\n\n- Replace [verse] with [synopsis] in the SYNOPSIS block\n- Remove single quotes around command names in the synopsis\n- Use backticks for inline commands, options, refs, and special values\n- Apply [synopsis] attribute to in-body command-form code blocks\n- Format OPTIONS entries with backtick-quoted terms and direct\n- Add synopsis-style formatting to listing blocks\n- Format man page references as `command`(N)\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/asciidoc.conf.in | 6 +++\n Documentation/git-bisect.adoc | 80 ++++++++++++++++++----------------\n 2 files changed, 48 insertions(+), 38 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex 31b883a72c..93c63b284a 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -84,6 +84,9 @@ ifdef::doctype-manpage[]\n [blockdef-open]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n \n+[blockdef-listing]\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+\n [paradef-default]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::doctype-manpage[]\n@@ -93,6 +96,9 @@ ifdef::backend-xhtml11[]\n [blockdef-open]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n \n+[blockdef-listing]\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+\n [paradef-default]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::backend-xhtml11[]\ndiff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc\nindex b0078dda0e..9a3b7b3cdb 100644\n--- a/Documentation/git-bisect.adoc\n+++ b/Documentation/git-bisect.adoc\n@@ -8,20 +8,20 @@ git-bisect - Use binary search to find the commit that introduced a bug\n \n SYNOPSIS\n --------\n-[verse]\n-'git bisect' start [--term-(bad|new)= --term-(good|old)=]\n-\t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n-'git bisect' (bad|new|) []\n-'git bisect' (good|old|) [...]\n-'git bisect' terms [--term-(good|old) | --term-(bad|new)]\n-'git bisect' skip [(|)...]\n-'git bisect' next\n-'git bisect' reset []\n-'git bisect' (visualize|view)\n-'git bisect' replay \n-'git bisect' log\n-'git bisect' run [...]\n-'git bisect' help\n+[synopsis]\n+git bisect start [--term-(bad|new)= --term-(good|old)=]\n+\t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n+git bisect (bad|new|) []\n+git bisect (good|old|) [...]\n+git bisect terms [--term-(good|old) | --term-(bad|new)]\n+git bisect skip [(|)...]\n+git bisect next\n+git bisect reset []\n+git bisect (visualize|view)\n+git bisect replay \n+git bisect log\n+git bisect run [...]\n+git bisect help\n \n DESCRIPTION\n -----------\n@@ -94,7 +94,7 @@ Bisect reset\n ~~~~~~~~~~~~\n \n After a bisect session, to clean up the bisection state and return to\n-the original HEAD, issue the following command:\n+the original `HEAD`, issue the following command:\n \n ------------------------------------------------\n $ git bisect reset\n@@ -107,6 +107,7 @@ that, as it cleans up the old bisection state.)\n With an optional argument, you can return to a different commit\n instead:\n \n+[synopsis]\n ------------------------------------------------\n $ git bisect reset \n ------------------------------------------------\n@@ -143,12 +144,14 @@ To use \"old\" and \"new\" instead of \"good\" and bad, you must run `git\n bisect start` without commits as argument and then run the following\n commands to add the commits:\n \n+[synopsis]\n ------------------------------------------------\n git bisect old []\n ------------------------------------------------\n \n to indicate that a commit was before the sought change, or\n \n+[synopsis]\n ------------------------------------------------\n git bisect new [...]\n ------------------------------------------------\n@@ -157,6 +160,7 @@ to indicate that it was after.\n \n To get a reminder of the currently used terms, use\n \n+[synopsis]\n ------------------------------------------------\n git bisect terms\n ------------------------------------------------\n@@ -171,6 +175,7 @@ If you would like to use your own terms instead of \"bad\"/\"good\" or\n subcommands like `reset`, `start`, ...) by starting the\n bisection using\n \n+[synopsis]\n ------------------------------------------------\n git bisect start --term-old --term-new \n ------------------------------------------------\n@@ -194,7 +199,7 @@ of `git bisect good` and `git bisect bad` to mark commits.\n Bisect visualize/view\n ~~~~~~~~~~~~~~~~~~~~~\n \n-To see the currently remaining suspects in 'gitk', issue the following\n+To see the currently remaining suspects in `gitk`, issue the following\n command during the bisection process (the subcommand `view` can be used\n as an alternative to `visualize`):\n \n@@ -203,12 +208,13 @@ $ git bisect visualize\n ------------\n \n Git detects a graphical environment through various environment variables:\n-`DISPLAY`, which is set in X Window System environments on Unix systems.\n-`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions.\n-`MSYSTEM`, which is set under Msys2 and Git for Windows.\n-`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions.\n \n-If none of these environment variables is set, 'git log' is used instead.\n+`DISPLAY`:: which is set in X Window System environments on Unix systems.\n+`SESSIONNAME`:: which is set under Cygwin in interactive desktop sessions.\n+`MSYSTEM`:: which is set under Msys2 and Git for Windows.\n+`SECURITYSESSIONID`:: which may be set on macOS in interactive desktop sessions.\n+\n+If none of these environment variables is set, `git log` is used instead.\n You can also give command-line options such as `-p` and `--stat`.\n \n ------------\n@@ -342,8 +348,8 @@ code between 1 and 127 (inclusive), except 125, if the current source\n code is bad/new.\n \n Any other exit code will abort the bisect process. It should be noted\n-that a program that terminates via `exit(-1)` leaves $? = 255, (see the\n-exit(3) manual page), as the value is chopped with `& 0377`.\n+that a program that terminates via `exit(-1)` leaves `$?` = 255, (see the\n+`exit`(3) manual page), as the value is chopped with `& 0377`.\n \n The special exit code 125 should be used when the current source code\n cannot be tested. If the script exits with this code, the current\n@@ -355,12 +361,12 @@ details do not matter, as they are normal errors in the script, as far as\n `bisect run` is concerned).\n \n You may often find that during a bisect session you want to have\n-temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a\n+temporary modifications (e.g. `s/#define DEBUG 0/#define DEBUG 1/` in a\n header file, or \"revision that does not have this commit needs this\n patch applied to work around another problem this bisection is not\n interested in\") applied to the revision being tested.\n \n-To cope with such a situation, after the inner 'git bisect' finds the\n+To cope with such a situation, after the inner `git bisect` finds the\n next revision to test, the script can apply the patch\n before compiling, run the real test, and afterwards decide if the\n revision (possibly with the needed patch) passed the test and then\n@@ -370,20 +376,18 @@ determine the eventual outcome of the bisect session.\n \n OPTIONS\n -------\n---no-checkout::\n-+\n-Do not checkout the new working tree at each iteration of the bisection\n-process. Instead just update the reference named `BISECT_HEAD` to make\n-it point to the commit that should be tested.\n+`--no-checkout`::\n+\tDo not checkout the new working tree at each iteration of the bisection\n+\tprocess. Instead just update the reference named `BISECT_HEAD` to make\n+\tit point to the commit that should be tested.\n +\n This option may be useful when the test you would perform in each step\n does not require a checked out tree.\n +\n If the repository is bare, `--no-checkout` is assumed.\n \n---first-parent::\n-+\n-Follow only the first parent commit upon seeing a merge commit.\n+`--first-parent`::\n+\tFollow only the first parent commit upon seeing a merge commit.\n +\n In detecting regressions introduced through the merging of a branch, the merge\n commit will be identified as introduction of the bug and its ancestors will be\n@@ -395,7 +399,7 @@ branch contained broken or non-buildable commits, but the merge itself was OK.\n EXAMPLES\n --------\n \n-* Automatically bisect a broken build between v1.2 and HEAD:\n+* Automatically bisect a broken build between v1.2 and `HEAD`:\n +\n ------------\n $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good\n@@ -403,7 +407,7 @@ $ git bisect run make # \"make\" builds the app\n $ git bisect reset # quit the bisect session\n ------------\n \n-* Automatically bisect a test failure between origin and HEAD:\n+* Automatically bisect a test failure between origin and `HEAD`:\n +\n ------------\n $ git bisect start HEAD origin -- # HEAD is bad, origin is good\n@@ -430,7 +434,7 @@ and `exit 1` otherwise.\n +\n It is safer if both `test.sh` and `check_test_case.sh` are\n outside the repository to prevent interactions between the bisect,\n-make and test processes and the scripts.\n+`make` and test processes and the scripts.\n \n * Automatically bisect with temporary modifications (hot-fix):\n +\n@@ -491,9 +495,9 @@ $ git bisect run sh -c '\n $ git bisect reset # quit the bisect session\n ------------\n +\n-In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that\n+In this case, when `git bisect run` finishes, `bisect/bad` will refer to a commit that\n has at least one parent whose reachable graph is fully traversable in the sense\n-required by 'git pack objects'.\n+required by `git pack-objects`.\n \n * Look for a fix instead of a regression in the code\n +\n-- \ngitgitgadget\n\n"},{"id":"543488","messageId":"1b4efce1b2df2fb4958c442de290cb10cb2c2a4f.1779049615.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.git.1779049615.gitgitgadget@gmail.com","subject":"[PATCH 2/5] doc: convert git-grep synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-17T20:26:52Z","receivedAt":"2026-05-17T20:27:01Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-grep.adoc from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Change 'git grep' to git grep (no single quotes)\n- Backtick-quote all OPTIONS terms\n- Convert inline man page refs: grep(1) -> `grep`(1)\n- Convert inline command refs: 'git diff' -> `git diff`\n- Convert prose placeholders: -> __\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/grep.adoc | 36 +++---\n Documentation/git-grep.adoc | 196 ++++++++++++++++-----------------\n 2 files changed, 116 insertions(+), 116 deletions(-)\n\ndiff --git a/Documentation/config/grep.adoc b/Documentation/config/grep.adoc\nindex 10041f27b0..83d4b76dd3 100644\n--- a/Documentation/config/grep.adoc\n+++ b/Documentation/config/grep.adoc\n@@ -1,28 +1,28 @@\n-grep.lineNumber::\n-\tIf set to true, enable `-n` option by default.\n+`grep.lineNumber`::\n+\tIf set to `true`, enable `-n` option by default.\n \n-grep.column::\n-\tIf set to true, enable the `--column` option by default.\n+`grep.column`::\n+\tIf set to `true`, enable the `--column` option by default.\n \n-grep.patternType::\n-\tSet the default matching behavior. Using a value of 'basic', 'extended',\n-\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n+`grep.patternType`::\n+\tSet the default matching behavior. Using a value of `basic`, `extended`,\n+\t`fixed`, or `perl` will enable the `--basic-regexp`, `--extended-regexp`,\n \t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n-\tvalue 'default' will use the `grep.extendedRegexp` option to choose\n-\tbetween 'basic' and 'extended'.\n+\tvalue `default` will use the `grep.extendedRegexp` option to choose\n+\tbetween `basic` and `extended`.\n \n-grep.extendedRegexp::\n-\tIf set to true, enable `--extended-regexp` option by default. This\n+`grep.extendedRegexp`::\n+\tIf set to `true`, enable `--extended-regexp` option by default. This\n \toption is ignored when the `grep.patternType` option is set to a value\n-\tother than 'default'.\n+\tother than `default`.\n \n-grep.threads::\n+`grep.threads`::\n \tNumber of grep worker threads to use. If unset (or set to 0), Git will\n \tuse as many threads as the number of logical cores available.\n \n-grep.fullName::\n-\tIf set to true, enable `--full-name` option by default.\n+`grep.fullName`::\n+\tIf set to `true`, enable `--full-name` option by default.\n \n-grep.fallbackToNoIndex::\n-\tIf set to true, fall back to `git grep --no-index` if `git grep`\n-\tis executed outside of a git repository. Defaults to false.\n+`grep.fallbackToNoIndex`::\n+\tIf set to `true`, fall back to `git grep --no-index` if `git grep`\n+\tis executed outside of a git repository. Defaults to `false`.\ndiff --git a/Documentation/git-grep.adoc b/Documentation/git-grep.adoc\nindex a548585d4c..19b3ade16d 100644\n--- a/Documentation/git-grep.adoc\n+++ b/Documentation/git-grep.adoc\n@@ -8,8 +8,8 @@ git-grep - Print lines matching a pattern\n \n SYNOPSIS\n --------\n-[verse]\n-'git grep' [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]\n+[synopsis]\n+git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]\n \t [-v | --invert-match] [-h|-H] [--full-name]\n \t [-E | --extended-regexp] [-G | --basic-regexp]\n \t [-P | --perl-regexp]\n@@ -41,139 +41,139 @@ characters. An empty string as search expression matches all lines.\n \n OPTIONS\n -------\n---cached::\n+`--cached`::\n \tInstead of searching tracked files in the working tree, search\n \tblobs registered in the index file.\n \n---untracked::\n+`--untracked`::\n \tIn addition to searching in the tracked files in the working\n \ttree, search also in untracked files.\n \n---no-index::\n+`--no-index`::\n \tSearch files in the current directory that is not managed by Git,\n \tor by ignoring that the current directory is managed by Git. This\n-\tis rather similar to running the regular `grep(1)` utility with its\n+\tis rather similar to running the regular `grep`(1) utility with its\n \t`-r` option specified, but with some additional benefits, such as\n-\tusing pathspec patterns to limit paths; see the 'pathspec' entry\n+\tusing pathspec patterns to limit paths; see the `pathspec` entry\n \tin linkgit:gitglossary[7] for more information.\n +\n This option cannot be used together with `--cached` or `--untracked`.\n See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below.\n \n---no-exclude-standard::\n+`--no-exclude-standard`::\n \tAlso search in ignored files by not honoring the `.gitignore`\n \tmechanism. Only useful with `--untracked`.\n \n---exclude-standard::\n+`--exclude-standard`::\n \tDo not pay attention to ignored files specified via the `.gitignore`\n \tmechanism. Only useful when searching files in the current directory\n \twith `--no-index`.\n \n---recurse-submodules::\n+`--recurse-submodules`::\n \tRecursively search in each submodule that is active and\n \tchecked out in the repository. When used in combination with the\n \t__ option the prefix of all submodule output will be the name of\n \tthe parent project's __ object. This option cannot be used together\n \twith `--untracked`, and it has no effect if `--no-index` is specified.\n \n--a::\n---text::\n+`-a`::\n+`--text`::\n \tProcess binary files as if they were text.\n \n---textconv::\n+`--textconv`::\n \tHonor textconv filter settings.\n \n---no-textconv::\n+`--no-textconv`::\n \tDo not honor textconv filter settings.\n \tThis is the default.\n \n--i::\n---ignore-case::\n+`-i`::\n+`--ignore-case`::\n \tIgnore case differences between the patterns and the\n \tfiles.\n \n--I::\n+`-I`::\n \tDon't match the pattern in binary files.\n \n---max-depth ::\n-\tFor each given on command line, descend at most \n+`--max-depth `::\n+\tFor each __ given on command line, descend at most __\n \tlevels of directories. A value of -1 means no limit.\n-\tThis option is ignored if contains active wildcards.\n+\tThis option is ignored if __ contains active wildcards.\n \tIn other words if \"a*\" matches a directory named \"a*\",\n-\t\"*\" is matched literally so --max-depth is still effective.\n+\t\"*\" is matched literally so `--max-depth` is still effective.\n \n--r::\n---recursive::\n+`-r`::\n+`--recursive`::\n \tSame as `--max-depth=-1`; this is the default.\n \n---no-recursive::\n+`--no-recursive`::\n \tSame as `--max-depth=0`.\n \n--w::\n---word-regexp::\n+`-w`::\n+`--word-regexp`::\n \tMatch the pattern only at word boundary (either begin at the\n \tbeginning of a line, or preceded by a non-word character; end at\n \tthe end of a line or followed by a non-word character).\n \n--v::\n---invert-match::\n+`-v`::\n+`--invert-match`::\n \tSelect non-matching lines.\n \n--h::\n--H::\n+`-h`::\n+`-H`::\n \tBy default, the command shows the filename for each\n \tmatch. `-h` option is used to suppress this output.\n \t`-H` is there for completeness and does not do anything\n \texcept it overrides `-h` given earlier on the command\n \tline.\n \n---full-name::\n+`--full-name`::\n \tWhen run from a subdirectory, the command usually\n \toutputs paths relative to the current directory. This\n \toption forces paths to be output relative to the project\n \ttop directory.\n \n--E::\n---extended-regexp::\n--G::\n---basic-regexp::\n+`-E`::\n+`--extended-regexp`::\n+`-G`::\n+`--basic-regexp`::\n \tUse POSIX extended/basic regexp for patterns. Default\n \tis to use basic regexp.\n \n--P::\n---perl-regexp::\n+`-P`::\n+`--perl-regexp`::\n \tUse Perl-compatible regular expressions for patterns.\n +\n Support for these types of regular expressions is an optional\n compile-time dependency. If Git wasn't compiled with support for them\n providing this option will cause it to die.\n \n--F::\n---fixed-strings::\n+`-F`::\n+`--fixed-strings`::\n \tUse fixed strings for patterns (don't interpret pattern\n \tas a regex).\n \n--n::\n---line-number::\n+`-n`::\n+`--line-number`::\n \tPrefix the line number to matching lines.\n \n---column::\n+`--column`::\n \tPrefix the 1-indexed byte-offset of the first match from the start of the\n \tmatching line.\n \n--l::\n---files-with-matches::\n---name-only::\n--L::\n---files-without-match::\n+`-l`::\n+`--files-with-matches`::\n+`--name-only`::\n+`-L`::\n+`--files-without-match`::\n \tInstead of showing every matched line, show only the\n \tnames of files that contain (or do not contain) matches.\n-\tFor better compatibility with 'git diff', `--name-only` is a\n+\tFor better compatibility with `git diff`, `--name-only` is a\n \tsynonym for `--files-with-matches`.\n \n--O[]::\n---open-files-in-pager[=]::\n-\tOpen the matching files in the pager (not the output of 'grep').\n+`-O[]`::\n+`--open-files-in-pager[=]`::\n+\tOpen the matching files in the pager (not the output of `grep`).\n \tIf the pager happens to be \"less\" or \"vi\", and the user\n \tspecified only one pattern, the first file is positioned at\n \tthe first match automatically. The `pager` argument is\n@@ -181,65 +181,65 @@ providing this option will cause it to die.\n \twithout a space. If `pager` is unspecified, the default pager\n \twill be used (see `core.pager` in linkgit:git-config[1]).\n \n--z::\n---null::\n+`-z`::\n+`--null`::\n \tUse \\0 as the delimiter for pathnames in the output, and print\n \tthem verbatim. Without this option, pathnames with \"unusual\"\n \tcharacters are quoted as explained for the configuration\n \tvariable `core.quotePath` (see linkgit:git-config[1]).\n \n--o::\n---only-matching::\n+`-o`::\n+`--only-matching`::\n \tPrint only the matched (non-empty) parts of a matching line, with each such\n \tpart on a separate output line.\n \n--c::\n---count::\n+`-c`::\n+`--count`::\n \tInstead of showing every matched line, show the number of\n \tlines that match.\n \n---color[=]::\n+`--color[=]`::\n \tShow colored matches.\n-\tThe value must be always (the default), never, or auto.\n+\tThe value must be `always` (the default), `never`, or `auto`.\n \n---no-color::\n+`--no-color`::\n \tTurn off match highlighting, even when the configuration file\n \tgives the default to color output.\n \tSame as `--color=never`.\n \n---break::\n+`--break`::\n \tPrint an empty line between matches from different files.\n \n---heading::\n+`--heading`::\n \tShow the filename above the matches in that file instead of\n \tat the start of each shown line.\n \n--p::\n---show-function::\n+`-p`::\n+`--show-function`::\n \tShow the preceding line that contains the function name of\n \tthe match, unless the matching line is a function name itself.\n \tThe name is determined in the same way as `git diff` works out\n \tpatch hunk headers (see 'Defining a custom hunk-header' in\n \tlinkgit:gitattributes[5]).\n \n--::\n--C ::\n---context ::\n-\tShow leading and trailing lines, and place a line\n+`-`::\n+`-C `::\n+`--context `::\n+\tShow __ leading and trailing lines, and place a line\n \tcontaining `--` between contiguous groups of matches.\n \n--A ::\n---after-context ::\n-\tShow trailing lines, and place a line containing\n+`-A `::\n+`--after-context `::\n+\tShow __ trailing lines, and place a line containing\n \t`--` between contiguous groups of matches.\n \n--B ::\n---before-context ::\n-\tShow leading lines, and place a line containing\n+`-B `::\n+`--before-context `::\n+\tShow __ leading lines, and place a line containing\n \t`--` between contiguous groups of matches.\n \n--W::\n---function-context::\n+`-W`::\n+`--function-context`::\n \tShow the surrounding text from the previous line containing a\n \tfunction name up to the one before the next function name,\n \teffectively showing the whole function in which the match was\n@@ -247,22 +247,22 @@ providing this option will cause it to die.\n \t`git diff` works out patch hunk headers (see 'Defining a\n \tcustom hunk-header' in linkgit:gitattributes[5]).\n \n--m ::\n---max-count ::\n+`-m `::\n+`--max-count `::\n \tLimit the amount of matches per file. When using the `-v` or\n \t`--invert-match` option, the search stops after the specified\n \tnumber of non-matches. A value of -1 will return unlimited\n \tresults (the default). A value of 0 will exit immediately with\n \ta non-zero status.\n \n---threads ::\n-\tNumber of `grep` worker threads to use. See 'NOTES ON THREADS'\n+`--threads `::\n+\tNumber of `grep` worker threads to use. See `NOTES ON THREADS`\n \tand `grep.threads` in 'CONFIGURATION' for more information.\n \n--f ::\n-\tRead patterns from , one per line.\n+`-f `::\n+\tRead patterns from __, one per line.\n +\n-Passing the pattern via allows for providing a search pattern\n+Passing the pattern via __ allows for providing a search pattern\n containing a \\0.\n +\n Not all pattern types support patterns containing \\0. Git will error\n@@ -279,44 +279,44 @@ In future versions we may learn to support patterns containing \\0 for\n more search backends, until then we'll die when the pattern type in\n question doesn't support them.\n \n--e::\n+`-e`::\n \tThe next parameter is the pattern. This option has to be\n \tused for patterns starting with `-` and should be used in\n \tscripts passing user input to grep. Multiple patterns are\n-\tcombined by 'or'.\n+\tcombined by `or`.\n \n---and::\n---or::\n---not::\n-( ... )::\n+`--and`::\n+`--or`::\n+`--not`::\n+`( ... )`::\n \tSpecify how multiple patterns are combined using Boolean\n \texpressions. `--or` is the default operator. `--and` has\n \thigher precedence than `--or`. `-e` has to be used for all\n \tpatterns.\n \n---all-match::\n+`--all-match`::\n \tWhen giving multiple pattern expressions combined with `--or`,\n \tthis flag is specified to limit the match to files that\n \thave lines to match all of them.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tDo not output matched lines; instead, exit with status 0 when\n \tthere is a match and with non-zero status when there isn't.\n \n-...::\n+`...`::\n \tInstead of searching tracked files in the working tree, search\n \tblobs in the given trees.\n \n-\\--::\n+`--`::\n \tSignals the end of options; the rest of the parameters\n-\tare limiters.\n+\tare __ limiters.\n \n-...::\n+`...`::\n \tIf given, limit the search to paths matching at least one pattern.\n-\tBoth leading paths match and glob(7) patterns are supported.\n+\tBoth leading paths match and `glob`(7) patterns are supported.\n +\n-For more details about the syntax, see the 'pathspec' entry\n+For more details about the __ syntax, see the `pathspec` entry\n in linkgit:gitglossary[7].\n \n EXAMPLES\n-- \ngitgitgadget\n\n"},{"id":"543489","messageId":"4ab60a95f4847bcfee82292ff4ac47424e5aa147.1779049615.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.git.1779049615.gitgitgadget@gmail.com","subject":"[PATCH 3/5] doc: convert git-am synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-17T20:26:53Z","receivedAt":"2026-05-17T20:27:04Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-am from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Backtick-quote all OPTIONS terms\n- Convert inline man page refs\n- Convert inline command refs\n- Convert prose placeholders:\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/am.adoc | 6 +-\n Documentation/format-patch-caveats.adoc | 2 +-\n .../format-patch-end-of-commit-message.adoc | 4 +-\n Documentation/git-am.adoc | 132 +++++++++---------\n 4 files changed, 72 insertions(+), 72 deletions(-)\n\ndiff --git a/Documentation/config/am.adoc b/Documentation/config/am.adoc\nindex e9561e12d7..250e6b5047 100644\n--- a/Documentation/config/am.adoc\n+++ b/Documentation/config/am.adoc\n@@ -1,11 +1,11 @@\n-am.keepcr::\n+`am.keepcr`::\n \tIf true, linkgit:git-am[1] will call linkgit:git-mailsplit[1]\n \tfor patches in mbox format with parameter `--keep-cr`. In this\n \tcase linkgit:git-mailsplit[1] will\n \tnot remove `\\r` from lines ending with `\\r\\n`. Can be overridden\n \tby giving `--no-keep-cr` from the command line.\n \n-am.threeWay::\n+`am.threeWay`::\n \tBy default, linkgit:git-am[1] will fail if the patch does not\n \tapply cleanly. When set to true, this setting tells\n \tlinkgit:git-am[1] to fall back on 3-way merge if the patch\n@@ -13,7 +13,7 @@ am.threeWay::\n \thave those blobs available locally (equivalent to giving the\n \t`--3way` option from the command line). Defaults to `false`.\n \n-am.messageId::\n+`am.messageId`::\n \tAdd a `Message-ID` trailer based on the email header to the\n \tcommit when using linkgit:git-am[1] (see\n \tlinkgit:git-interpret-trailers[1]). See also the `--message-id`\ndiff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc\nindex 807a65b885..133e4757e7 100644\n--- a/Documentation/format-patch-caveats.adoc\n+++ b/Documentation/format-patch-caveats.adoc\n@@ -28,6 +28,6 @@ repositories. This goes to show that this behavior does not only impact\n email workflows.\n \n Given these limitations, one might be tempted to use a general-purpose\n-utility like patch(1) instead. However, patch(1) will not only look for\n+utility like `patch`(1) instead. However, `patch`(1) will not only look for\n unindented diffs (like linkgit:git-am[1]) but will try to apply indented\n diffs as well.\ndiff --git a/Documentation/format-patch-end-of-commit-message.adoc b/Documentation/format-patch-end-of-commit-message.adoc\nindex ec1ef79f5e..a1a624d2ac 100644\n--- a/Documentation/format-patch-end-of-commit-message.adoc\n+++ b/Documentation/format-patch-end-of-commit-message.adoc\n@@ -1,8 +1,8 @@\n Any line that is of the form:\n \n * three-dashes and end-of-line, or\n-* a line that begins with \"diff -\", or\n-* a line that begins with \"Index: \"\n+* a line that begins with `diff -`, or\n+* a line that begins with `Index: `\n \n is taken as the beginning of a patch, and the commit log message\n is terminated before the first occurrence of such a line.\ndiff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc\nindex ac65852918..28adf4cf65 100644\n--- a/Documentation/git-am.adoc\n+++ b/Documentation/git-am.adoc\n@@ -8,17 +8,17 @@ git-am - Apply a series of patches from a mailbox\n \n SYNOPSIS\n --------\n-[verse]\n-'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]\n+[synopsis]\n+git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]\n \t [--[no-]3way] [--interactive] [--committer-date-is-author-date]\n \t [--ignore-date] [--ignore-space-change | --ignore-whitespace]\n \t [--whitespace=] [-C] [-p] [--directory=]\n \t [--exclude=] [--include=] [--reject] [-q | --quiet]\n-\t [--[no-]scissors] [-S[]] [--patch-format=]\n+\t [--[no-]scissors] [-S[]] [--patch-format=]\n \t [--quoted-cr=]\n \t [--empty=(stop|drop|keep)]\n \t [( | )...]\n-'git am' (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)\n+git am (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)\n \n DESCRIPTION\n -----------\n@@ -30,45 +30,45 @@ history without merges.\n \n OPTIONS\n -------\n-(|)...::\n+`(|)...`::\n \tThe list of mailbox files to read patches from. If you do not\n \tsupply this argument, the command reads from the standard input.\n \tIf you supply directories, they will be treated as Maildirs.\n \n--s::\n---signoff::\n+`-s`::\n+`--signoff`::\n \tAdd a `Signed-off-by` trailer to the commit message (see\n \tlinkgit:git-interpret-trailers[1]), using the committer identity\n \tof yourself. See the signoff option in linkgit:git-commit[1]\n \tfor more information.\n \n--k::\n---keep::\n+`-k`::\n+`--keep`::\n \tPass `-k` flag to linkgit:git-mailinfo[1].\n \n---keep-non-patch::\n+`--keep-non-patch`::\n \tPass `-b` flag to linkgit:git-mailinfo[1].\n \n---keep-cr::\n---no-keep-cr::\n+`--keep-cr`::\n+`--no-keep-cr`::\n \tWith `--keep-cr`, call linkgit:git-mailsplit[1]\n \twith the same option, to prevent it from stripping CR at the end of\n \tlines. `am.keepcr` configuration variable can be used to specify the\n \tdefault behaviour. `--no-keep-cr` is useful to override `am.keepcr`.\n \n--c::\n---scissors::\n+`-c`::\n+`--scissors`::\n \tRemove everything in body before a scissors line (see\n \tlinkgit:git-mailinfo[1]). Can be activated by default using\n \tthe `mailinfo.scissors` configuration variable.\n \n---no-scissors::\n+`--no-scissors`::\n \tIgnore scissors lines (see linkgit:git-mailinfo[1]).\n \n---quoted-cr=::\n+`--quoted-cr=`::\n \tThis flag will be passed down to linkgit:git-mailinfo[1].\n \n---empty=(drop|keep|stop)::\n+`--empty=(drop|keep|stop)`::\n \tHow to handle an e-mail message lacking a patch:\n +\n --\n@@ -82,23 +82,23 @@ OPTIONS\n \tsession. This is the default behavior.\n --\n \n--m::\n---message-id::\n+`-m`::\n+`--message-id`::\n \tPass the `-m` flag to linkgit:git-mailinfo[1],\n \tso that the `Message-ID` header is added to the commit message.\n \tThe `am.messageid` configuration variable can be used to specify\n \tthe default behaviour.\n \n---no-message-id::\n+`--no-message-id`::\n \tDo not add the Message-ID header to the commit message.\n \t`--no-message-id` is useful to override `am.messageid`.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tBe quiet. Only print error messages.\n \n--u::\n---utf8::\n+`-u`::\n+`--utf8`::\n \tPass `-u` flag to linkgit:git-mailinfo[1].\n \tThe proposed commit log message taken from the e-mail\n \tis re-coded into UTF-8 encoding (configuration variable\n@@ -108,57 +108,57 @@ OPTIONS\n This was optional in prior versions of git, but now it is the\n default. You can use `--no-utf8` to override this.\n \n---no-utf8::\n+`--no-utf8`::\n \tPass `-n` flag to linkgit:git-mailinfo[1].\n \n--3::\n---3way::\n---no-3way::\n+`-3`::\n+`--3way`::\n+`--no-3way`::\n \tWhen the patch does not apply cleanly, fall back on\n \t3-way merge if the patch records the identity of blobs\n \tit is supposed to apply to and we have those blobs\n \tavailable locally. `--no-3way` can be used to override\n-\tam.threeWay configuration variable. For more information,\n-\tsee am.threeWay in linkgit:git-config[1].\n+\t`am.threeWay` configuration variable. For more information,\n+\tsee `am.threeWay` in linkgit:git-config[1].\n \n include::rerere-options.adoc[]\n \n---ignore-space-change::\n---ignore-whitespace::\n---whitespace=::\n--C::\n--p::\n---directory=::\n---exclude=::\n---include=::\n---reject::\n+`--ignore-space-change`::\n+`--ignore-whitespace`::\n+`--whitespace=`::\n+`-C`::\n+`-p`::\n+`--directory=`::\n+`--exclude=`::\n+`--include=`::\n+`--reject`::\n \tThese flags are passed to the linkgit:git-apply[1] program that\n \tapplies the patch.\n +\n-Valid for the `--whitespace` option are:\n+Valid __ for the `--whitespace` option are:\n `nowarn`, `warn`, `fix`, `error`, and `error-all`.\n \n---patch-format::\n+`--patch-format`::\n \tBy default the command will try to detect the patch format\n \tautomatically. This option allows the user to bypass the automatic\n \tdetection and specify the patch format that the patch(es) should be\n \tinterpreted as. Valid formats are mbox, mboxrd,\n \tstgit, stgit-series, and hg.\n \n--i::\n---interactive::\n+`-i`::\n+`--interactive`::\n \tRun interactively.\n \n---verify::\n--n::\n---no-verify::\n+`--verify`::\n+`-n`::\n+`--no-verify`::\n \tRun the `pre-applypatch` and `applypatch-msg` hooks. This is the\n \tdefault. Skip these hooks with `-n` or `--no-verify`. See also\n \tlinkgit:githooks[5].\n +\n Note that `post-applypatch` cannot be skipped.\n \n---committer-date-is-author-date::\n+`--committer-date-is-author-date`::\n \tBy default the command records the date from the e-mail\n \tmessage as the commit author date, and uses the time of\n \tcommit creation as the committer date. This allows the\n@@ -172,29 +172,29 @@ committer date when applying commits on top of a base which commit is\n older (in terms of the commit date) than the oldest patch you are\n applying.\n \n---ignore-date::\n+`--ignore-date`::\n \tBy default the command records the date from the e-mail\n \tmessage as the commit author date, and uses the time of\n \tcommit creation as the committer date. This allows the\n \tuser to lie about the author date by using the same\n \tvalue as the committer date.\n \n---skip::\n+`--skip`::\n \tSkip the current patch. This is only meaningful when\n \trestarting an aborted patch.\n \n--S[]::\n---gpg-sign[=]::\n---no-gpg-sign::\n-\tGPG-sign commits. The `keyid` argument is optional and\n+`-S[]`::\n+`--gpg-sign[=]`::\n+`--no-gpg-sign`::\n+\tGPG-sign commits. The __ is optional and\n \tdefaults to the committer identity; if specified, it must be\n \tstuck to the option without a space. `--no-gpg-sign` is useful to\n \tcountermand both `commit.gpgSign` configuration variable, and\n \tearlier `--gpg-sign`.\n \n---continue::\n--r::\n---resolved::\n+`--continue`::\n+`-r`::\n+`--resolved`::\n \tAfter a patch failure (e.g. attempting to apply\n \tconflicting patch), the user has applied it by hand and\n \tthe index file stores the result of the application.\n@@ -202,36 +202,36 @@ applying.\n \textracted from the e-mail message and the current index\n \tfile, and continue.\n \n---resolvemsg=::\n-\tWhen a patch failure occurs, will be printed\n+`--resolvemsg=`::\n+\tWhen a patch failure occurs, __ will be printed\n \tto the screen before exiting. This overrides the\n \tstandard message informing you to use `--continue`\n \tor `--skip` to handle the failure. This is solely\n \tfor internal use between linkgit:git-rebase[1] and\n \tlinkgit:git-am[1].\n \n---abort::\n+`--abort`::\n \tRestore the original branch and abort the patching operation.\n \tRevert the contents of files involved in the am operation to their\n \tpre-am state.\n \n---quit::\n-\tAbort the patching operation but keep HEAD and the index\n+`--quit`::\n+\tAbort the patching operation but keep `HEAD` and the index\n \tuntouched.\n \n---retry::\n+`--retry`::\n \tTry to apply the last conflicting patch again. This is generally\n \tonly useful for passing extra options to the retry attempt\n \t(e.g., `--3way`), since otherwise you'll just see the same\n \tfailure again.\n \n---show-current-patch[=(diff|raw)]::\n+`--show-current-patch[=(diff|raw)]`::\n \tShow the message at which linkgit:git-am[1] has stopped due to\n \tconflicts. If `raw` is specified, show the raw contents of\n \tthe e-mail message; if `diff`, show the diff portion only.\n \tDefaults to `raw`.\n \n---allow-empty::\n+`--allow-empty`::\n \tAfter a patch failure on an input e-mail message lacking a patch,\n \tcreate an empty commit with the contents of the e-mail message\n \tas its log message.\n@@ -278,11 +278,11 @@ operation is finished, so if you decide to start over from scratch,\n run `git am --abort` before running the command with mailbox\n names.\n \n-Before any patches are applied, ORIG_HEAD is set to the tip of the\n+Before any patches are applied, `ORIG_HEAD` is set to the tip of the\n current branch. This is useful if you have problems with multiple\n commits, like running linkgit:git-am[1] on the wrong branch or an error\n in the commits that is more easily fixed by changing the mailbox (e.g.\n-errors in the \"From:\" lines).\n+errors in the `From:` lines).\n \n [[caveats]]\n CAVEATS\n-- \ngitgitgadget\n\n"},{"id":"543490","messageId":"437e3f99c7c042a30e9c06503c3ffd2dd532b6d4.1779049615.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.git.1779049615.gitgitgadget@gmail.com","subject":"[PATCH 4/5] doc: convert git-apply synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-17T20:26:54Z","receivedAt":"2026-05-17T20:27:06Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-apply from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Backtick-quote all OPTIONS terms and config keys in config/apply.adoc\n- Convert single-quoted inline commands ('git apply', 'diff', etc.)\n- Wrap standalone placeholders in underscores (, , )\n- Backtick-quote `*.rej` and GNU `patch` tool references\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/apply.adoc | 17 +++--\n Documentation/git-apply.adoc | 125 ++++++++++++++++----------------\n 2 files changed, 74 insertions(+), 68 deletions(-)\n\ndiff --git a/Documentation/config/apply.adoc b/Documentation/config/apply.adoc\nindex f9908e210a..36fcea6291 100644\n--- a/Documentation/config/apply.adoc\n+++ b/Documentation/config/apply.adoc\n@@ -1,11 +1,16 @@\n-apply.ignoreWhitespace::\n-\tWhen set to 'change', tells 'git apply' to ignore changes in\n+`apply.ignoreWhitespace`::\n+\tWhen set to `change`, tells `git apply` to ignore changes in\n \twhitespace, in the same way as the `--ignore-space-change`\n \toption.\n-\tWhen set to one of: no, none, never, false, it tells 'git apply' to\n+\tWhen set to one of: `no`, `none`, `never`, `false`, it tells `git apply` to\n \trespect all whitespace differences.\n+ifndef::git-apply[]\n \tSee linkgit:git-apply[1].\n+endif::git-apply[]\n \n-apply.whitespace::\n-\tTells 'git apply' how to handle whitespace, in the same way\n-\tas the `--whitespace` option. See linkgit:git-apply[1].\n+`apply.whitespace`::\n+\tTells `git apply` how to handle whitespace, in the same way\n+\tas the `--whitespace` option.\n+ifndef::git-apply[]\n+\tSee linkgit:git-apply[1].\n+endif::git-apply[]\ndiff --git a/Documentation/git-apply.adoc b/Documentation/git-apply.adoc\nindex 6c71ee69da..3f22dac1ce 100644\n--- a/Documentation/git-apply.adoc\n+++ b/Documentation/git-apply.adoc\n@@ -8,8 +8,8 @@ git-apply - Apply a patch to files and/or to the index\n \n SYNOPSIS\n --------\n-[verse]\n-'git apply' [--stat] [--numstat] [--summary] [--check]\n+[synopsis]\n+git apply [--stat] [--numstat] [--summary] [--check]\n \t [--index | --intent-to-add] [--3way] [--ours | --theirs | --union]\n \t [--apply] [--no-add] [--build-fake-ancestor=] [-R | --reverse]\n \t [--allow-binary-replacement | --binary] [--reject] [-z]\n@@ -35,33 +35,33 @@ linkgit:git-format-patch[1] and/or received by email.\n \n OPTIONS\n -------\n-...::\n-\tThe files to read the patch from. '-' can be used to read\n+`...`::\n+\tThe files to read the patch from. `-` can be used to read\n \tfrom the standard input.\n \n---stat::\n+`--stat`::\n \tInstead of applying the patch, output diffstat for the\n \tinput. Turns off \"apply\".\n \n---numstat::\n+`--numstat`::\n \tSimilar to `--stat`, but shows the number of added and\n \tdeleted lines in decimal notation and the pathname without\n \tabbreviation, to make it more machine friendly. For\n \tbinary files, outputs two `-` instead of saying\n \t`0 0`. Turns off \"apply\".\n \n---summary::\n+`--summary`::\n \tInstead of applying the patch, output a condensed\n \tsummary of information obtained from git diff extended\n \theaders, such as creations, renames, and mode changes.\n \tTurns off \"apply\".\n \n---check::\n+`--check`::\n \tInstead of applying the patch, see if the patch is\n \tapplicable to the current working tree and/or the index\n \tfile and detects errors. Turns off \"apply\".\n \n---index::\n+`--index`::\n \tApply the patch to both the index and the working tree (or\n \tmerely check that it would apply cleanly to both if `--check` is\n \tin effect). Note that `--index` expects index entries and\n@@ -70,13 +70,13 @@ OPTIONS\n \traise an error if they are not, even if the patch would apply\n \tcleanly to both the index and the working tree in isolation.\n \n---cached::\n+`--cached`::\n \tApply the patch to just the index, without touching the working\n \ttree. If `--check` is in effect, merely check that it would\n \tapply cleanly to the index entry.\n \n--N::\n---intent-to-add::\n+`-N`::\n+`--intent-to-add`::\n \tWhen applying the patch only to the working tree, mark new\n \tfiles to be added to the index later (see `--intent-to-add`\n \toption in linkgit:git-add[1]). This option is ignored if\n@@ -84,8 +84,8 @@ OPTIONS\n \trepository. Note that `--index` could be implied by other options\n \tsuch as `--3way`.\n \n--3::\n---3way::\n+`-3`::\n+`--3way`::\n \tAttempt 3-way merge if the patch records the identity of blobs it is supposed\n \tto apply to and we have those blobs available locally, possibly leaving the\n \tconflict markers in the files in the working tree for the user to\n@@ -94,14 +94,14 @@ OPTIONS\n \tWhen used with the `--cached` option, any conflicts are left at higher stages\n \tin the cache.\n \n---ours::\n---theirs::\n---union::\n+`--ours`::\n+`--theirs`::\n+`--union`::\n \tInstead of leaving conflicts in the file, resolve conflicts favouring\n-\tour (or their or both) side of the lines. Requires --3way.\n+\tour (or their or both) side of the lines. Requires `--3way`.\n \n---build-fake-ancestor=::\n-\tNewer 'git diff' output has embedded 'index information'\n+`--build-fake-ancestor=`::\n+\tNewer `git diff` output has embedded 'index information'\n \tfor each blob to help identify the original version that\n \tthe patch applies to. When this flag is given, and if\n \tthe original versions of the blobs are available locally,\n@@ -110,18 +110,18 @@ OPTIONS\n When a pure mode change is encountered (which has no index information),\n the information is read from the current index instead.\n \n--R::\n---reverse::\n+`-R`::\n+`--reverse`::\n \tApply the patch in reverse.\n \n---reject::\n-\tFor atomicity, 'git apply' by default fails the whole patch and\n+`--reject`::\n+\tFor atomicity, `git apply` by default fails the whole patch and\n \tdoes not touch the working tree when some of the hunks\n \tdo not apply. This option makes it apply\n \tthe parts of the patch that are applicable, and leave the\n-\trejected hunks in corresponding *.rej files.\n+\trejected hunks in corresponding `*.rej` files.\n \n--z::\n+`-z`::\n \tWhen `--numstat` has been given, do not munge pathnames,\n \tbut use a NUL-terminated machine-readable format.\n +\n@@ -129,20 +129,20 @@ Without this option, pathnames with \"unusual\" characters are quoted as\n explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n--p::\n-\tRemove leading path components (separated by slashes) from\n+`-p`::\n+\tRemove __ leading path components (separated by slashes) from\n \ttraditional diff paths. E.g., with `-p2`, a patch against\n \t`a/dir/file` will be applied directly to `file`. The default is\n \t1.\n \n--C::\n-\tEnsure at least lines of surrounding context match before\n+`-C`::\n+\tEnsure at least __ lines of surrounding context match before\n \tand after each change. When fewer lines of surrounding\n \tcontext exist they all must match. By default no context is\n \tever ignored.\n \n---unidiff-zero::\n-\tBy default, 'git apply' expects that the patch being\n+`--unidiff-zero`::\n+\tBy default, `git apply` expects that the patch being\n \tapplied is a unified diff with at least one line of context.\n \tThis provides good safety measures, but breaks down when\n \tapplying a diff generated with `--unified=0`. To bypass these\n@@ -151,34 +151,34 @@ linkgit:git-config[1]).\n Note, for the reasons stated above, the usage of context-free patches is\n discouraged.\n \n---apply::\n+`--apply`::\n \tIf you use any of the options marked \"Turns off\n-\t'apply'\" above, 'git apply' reads and outputs the\n+\t'apply'\" above, `git apply` reads and outputs the\n \trequested information without actually applying the\n \tpatch. Give this flag after those flags to also apply\n \tthe patch.\n \n---no-add::\n+`--no-add`::\n \tWhen applying a patch, ignore additions made by the\n \tpatch. This can be used to extract the common part between\n-\ttwo files by first running 'diff' on them and applying\n+\ttwo files by first running `diff` on them and applying\n \tthe result with this option, which would apply the\n \tdeletion part but not the addition part.\n \n---allow-binary-replacement::\n---binary::\n+`--allow-binary-replacement`::\n+`--binary`::\n \tHistorically we did not allow binary patch application\n \twithout an explicit permission from the user, and this\n \tflag was the way to do so. Currently, we always allow binary\n \tpatch application, so this is a no-op.\n \n---exclude=::\n-\tDon't apply changes to files matching the given path pattern. This can\n+`--exclude=`::\n+\tDon't apply changes to files matching __. This can\n \tbe useful when importing patchsets, where you want to exclude certain\n \tfiles or directories.\n \n---include=::\n-\tApply changes to files matching the given path pattern. This can\n+`--include=`::\n+\tApply changes to files matching the __. This can\n \tbe useful when importing patchsets, where you want to include certain\n \tfiles or directories.\n +\n@@ -188,15 +188,15 @@ patch to each path is used. A patch to a path that does not match any\n include/exclude pattern is used by default if there is no include pattern\n on the command line, and ignored if there is any include pattern.\n \n---ignore-space-change::\n---ignore-whitespace::\n+`--ignore-space-change`::\n+`--ignore-whitespace`::\n \tWhen applying a patch, ignore changes in whitespace in context\n \tlines if necessary.\n \tContext lines will preserve their whitespace, and they will not\n \tundergo whitespace fixing regardless of the value of the\n \t`--whitespace` option. New lines will still be fixed, though.\n \n---whitespace=::\n+`--whitespace=`::\n \tWhen applying a patch, detect a new or modified line that has\n \twhitespace errors. What are considered whitespace errors is\n \tcontrolled by `core.whitespace` configuration. By default,\n@@ -209,7 +209,7 @@ By default, the command outputs warning messages but applies the patch.\n When `git-apply` is used for statistics and not applying a\n patch, it defaults to `nowarn`.\n +\n-You can use different `` values to control this\n+You can use different __ values to control this\n behavior:\n +\n * `nowarn` turns off the trailing whitespace warning.\n@@ -223,48 +223,48 @@ behavior:\n to apply the patch.\n * `error-all` is similar to `error` but shows all errors.\n \n---inaccurate-eof::\n-\tUnder certain circumstances, some versions of 'diff' do not correctly\n+`--inaccurate-eof`::\n+\tUnder certain circumstances, some versions of `diff` do not correctly\n \tdetect a missing new-line at the end of the file. As a result, patches\n-\tcreated by such 'diff' programs do not record incomplete lines\n+\tcreated by such `diff` programs do not record incomplete lines\n \tcorrectly. This option adds support for applying such patches by\n \tworking around this bug.\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tReport progress to stderr. By default, only a message about the\n \tcurrent patch being applied will be printed. This option will cause\n \tadditional information to be reported.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tSuppress stderr output. Messages about patch status and progress\n \twill not be printed.\n \n---recount::\n+`--recount`::\n \tDo not trust the line counts in the hunk headers, but infer them\n \tby inspecting the patch (e.g. after editing the patch without\n \tadjusting the hunk headers appropriately).\n \n---directory=::\n-\tPrepend to all filenames. If a \"-p\" argument was also passed,\n+`--directory=`::\n+\tPrepend __ to all filenames. If a `-p` argument was also passed,\n \tit is applied before prepending the new root.\n +\n For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh`\n can be applied to the file in the working tree `modules/git-gui/git-gui.sh` by\n running `git apply --directory=modules/git-gui`.\n \n---unsafe-paths::\n+`--unsafe-paths`::\n \tBy default, a patch that affects outside the working area\n \t(either a Git controlled working tree, or the current working\n-\tdirectory when \"git apply\" is used as a replacement of GNU\n-\tpatch) is rejected as a mistake (or a mischief).\n+\tdirectory when `git apply` is used as a replacement of GNU\n+\t`patch`) is rejected as a mistake (or a mischief).\n +\n-When `git apply` is used as a \"better GNU patch\", the user can pass\n+When `git apply` is used as a \"better GNU `patch`\", the user can pass\n the `--unsafe-paths` option to override this safety check. This option\n has no effect when `--index` or `--cached` is in use.\n \n---allow-empty::\n+`--allow-empty`::\n \tDon't return an error for patches containing no diff. This includes\n \tempty patches and patches with commit text only.\n \n@@ -273,11 +273,12 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.adoc[]\n \n+:git-apply: 1\n include::config/apply.adoc[]\n \n SUBMODULES\n ----------\n-If the patch contains any changes to submodules then 'git apply'\n+If the patch contains any changes to submodules then `git apply`\n treats these changes as follows.\n \n If `--index` is specified (explicitly or implicitly), then the submodule\n-- \ngitgitgadget\n\n"},{"id":"543491","messageId":"dbe4d20b4ba1af6b9c874522787634bc4e0baa19.1779049615.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.git.1779049615.gitgitgadget@gmail.com","subject":"[PATCH 5/5] doc: convert git-imap-send synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-17T20:26:55Z","receivedAt":"2026-05-17T20:27:08Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-imap-send from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Backtick-quote all OPTIONS terms\n- Backtick-quote all config keys in config/imap.adoc\n- Backtick-quote bare config key references in prose\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/imap.adoc | 30 +++++++++++++++---------------\n Documentation/git-imap-send.adoc | 24 ++++++++++++------------\n 2 files changed, 27 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc\nindex 4682a6bd03..cb8f5e2700 100644\n--- a/Documentation/config/imap.adoc\n+++ b/Documentation/config/imap.adoc\n@@ -1,44 +1,44 @@\n-imap.folder::\n+`imap.folder`::\n \tThe folder to drop the mails into, which is typically the Drafts\n \tfolder. For example: `INBOX.Drafts`, `INBOX/Drafts` or\n \t`[Gmail]/Drafts`. The IMAP folder to interact with MUST be specified;\n \tthe value of this configuration variable is used as the fallback\n \tdefault value when the `--folder` option is not given.\n \n-imap.tunnel::\n+`imap.tunnel`::\n \tCommand used to set up a tunnel to the IMAP server through which\n \tcommands will be piped instead of using a direct network connection\n-\tto the server. Required when imap.host is not set.\n+\tto the server. Required when `imap.host` is not set.\n \n-imap.host::\n+`imap.host`::\n \tA URL identifying the server. Use an `imap://` prefix for non-secure\n \tconnections and an `imaps://` prefix for secure connections.\n-\tIgnored when imap.tunnel is set, but required otherwise.\n+\tIgnored when `imap.tunnel` is set, but required otherwise.\n \n-imap.user::\n+`imap.user`::\n \tThe username to use when logging in to the server.\n \n-imap.pass::\n+`imap.pass`::\n \tThe password to use when logging in to the server.\n \n-imap.port::\n+`imap.port`::\n \tAn integer port number to connect to on the server.\n-\tDefaults to 143 for imap:// hosts and 993 for imaps:// hosts.\n-\tIgnored when imap.tunnel is set.\n+\tDefaults to 143 for `imap://` hosts and 993 for `imaps://` hosts.\n+\tIgnored when `imap.tunnel` is set.\n \n-imap.sslverify::\n+`imap.sslverify`::\n \tA boolean to enable/disable verification of the server certificate\n \tused by the SSL/TLS connection. Default is `true`. Ignored when\n-\timap.tunnel is set.\n+\t`imap.tunnel` is set.\n \n-imap.preformattedHTML::\n+`imap.preformattedHTML`::\n \tA boolean to enable/disable the use of html encoding when sending\n-\ta patch. An html encoded patch will be bracketed with 
\n+\ta patch.  An html encoded patch will be bracketed with `
`\n \tand have a content type of text/html.  Ironically, enabling this\n \toption causes Thunderbird to send the patch as a plain/text,\n \tformat=fixed email.  Default is `false`.\n \n-imap.authMethod::\n+`imap.authMethod`::\n \tSpecify the authentication method for authenticating with the IMAP server.\n \tIf Git was built with the NO_CURL option, or if your curl version is older\n \tthan 7.34.0, or if you're running git-imap-send with the `--no-curl`\ndiff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc\nindex 278e5ccd36..538b91afc0 100644\n--- a/Documentation/git-imap-send.adoc\n+++ b/Documentation/git-imap-send.adoc\n@@ -8,9 +8,9 @@ git-imap-send - Send a collection of patches from stdin to an IMAP folder\n \n SYNOPSIS\n --------\n-[verse]\n-'git imap-send' [-v] [-q] [--[no-]curl] [(--folder|-f) ]\n-'git imap-send' --list\n+[synopsis]\n+git imap-send [-v] [-q] [--[no-]curl] [(--folder|-f) ]\n+git imap-send --list\n \n \n DESCRIPTION\n@@ -32,30 +32,30 @@ $ git format-patch --signoff --stdout --attach origin | git imap-send\n OPTIONS\n -------\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tBe verbose.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tBe quiet.\n \n--f ::\n---folder=::\n+`-f `::\n+`--folder=`::\n \tSpecify the folder in which the emails have to saved.\n \tFor example: `--folder=[Gmail]/Drafts` or `-f INBOX/Drafts`.\n \n---curl::\n+`--curl`::\n \tUse libcurl to communicate with the IMAP server, unless tunneling\n \tinto it.  Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND\n \toption set.\n \n---no-curl::\n+`--no-curl`::\n \tTalk to the IMAP server using git's own IMAP routines instead of\n \tusing libcurl.  Ignored if Git was built with the NO_OPENSSL option\n \tset.\n \n---list::\n+`--list`::\n \tRun the IMAP LIST command to output a list of all the folders present.\n \n CONFIGURATION\n-- \ngitgitgadget\n"},{"id":"543494","messageId":"xmqq4ik5d0le.fsf@gitster.g","threadId":"65651","inReplyTo":"dca7f192f1e5cdfb57682feace0a4b3a10204376.1779049615.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] doc: convert git-bisect to synopsis style","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-18T00:26:37Z","receivedAt":"2026-05-18T00:26:40Z","isPatch":true,"body":"\"Jean-Noël Avila via GitGitGadget\"  writes:\n\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n>\n> Convert Documentation/git-bisect.adoc to the modern synopsis style.\n>\n> - Replace [verse] with [synopsis] in the SYNOPSIS block\n\nThis was expected.\n\n> - Remove single quotes around command names in the synopsis\n> - Use backticks for inline commands, options, refs, and special values\n> - Apply [synopsis] attribute to in-body command-form code blocks\n\nThis is very much unexpected.  I think everybody thought [synopsis]\nwas invented to be used for the SYNOPSIS section at the beginning of\neach manual page, and ...\n\n>  SYNOPSIS\n>  --------\n> -[verse]\n> -'git bisect' start [--term-(bad|new)= --term-(good|old)=]\n> -\t\t   [--no-checkout] [--first-parent] [ [...]] [--] [...]\n> ...\n> -'git bisect' help\n> +[synopsis]\n> +git bisect start [--term-(bad|new)= --term-(good|old)=]\n> +\t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n> ...\n> +git bisect help\n\n... a change like this is very much expected and understandable, but\nnew appearances of [synonsis] in places like:\n\n> +[synopsis]\n>  ------------------------------------------------\n>  $ git bisect reset \n>  ------------------------------------------------\n\nand\n\n> +[synopsis]\n>  ------------------------------------------------\n>  git bisect old []\n>  ------------------------------------------------\n\nwere a bit surprising and confusing.  They are not exactly command\nsyntax definitions (which is the SYNOPSIS section is about), but\nexamples of usage.  The one with '$' command line prompt feels\nparticularly confusing, as the prompt is not something that the\nend-user gives, unlike what we write in the synopsis section.\n\nOther than that, this is quite exciting.\n\n"},{"id":"543497","messageId":"87tss5wjpp.fsf@gitster.g","threadId":"65651","inReplyTo":"xmqq4ik5d0le.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: convert git-bisect to synopsis style","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-18T02:10:58Z","receivedAt":"2026-05-18T02:11:04Z","isPatch":true,"body":"Junio C Hamano  writes:\n\n>> +[synopsis]\n>>  ------------------------------------------------\n>>  $ git bisect reset \n>>  ------------------------------------------------\n>\n> and\n>\n>> +[synopsis]\n>>  ------------------------------------------------\n>>  git bisect old []\n>>  ------------------------------------------------\n>\n> were a bit surprising and confusing.  They are not exactly command\n> syntax definitions (which is the SYNOPSIS section is about), but\n> examples of usage.  The one with '$' command line prompt feels\n> particularly confusing, as the prompt is not something that the\n> end-user gives, unlike what we write in the synopsis section.\n>\n> Other than that, this is quite exciting.\n\nWell, my local test with asciidoctor did not barf, but it seems that\nthe documentation pipeline run in GitHub Actions CI is unhappy.\n\nhttps://github.com/git/git/actions/runs/26008649802/job/76444895183#step:4:4846\n\nI do not know what the differences among the three environments\n(counting your development environment---only one of which fails)\nare offhand.\n\n"},{"id":"543705","messageId":"5072065.GXAFRqVoOG@piment-oiseau","threadId":"65651","inReplyTo":"xmqq4ik5d0le.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: convert git-bisect to synopsis style","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2026-05-19T20:57:29Z","receivedAt":"2026-05-19T20:57:46Z","isPatch":true,"body":"On Monday, 18 May 2026 02:26:37 CEST Junio C Hamano wrote:\n> \"Jean-Noël Avila via GitGitGadget\"  writes:\n> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n> > \n> > Convert Documentation/git-bisect.adoc to the modern synopsis style.\n> > \n> > - Replace [verse] with [synopsis] in the SYNOPSIS block\n> \n> This was expected.\n> \n> > - Remove single quotes around command names in the synopsis\n> > - Use backticks for inline commands, options, refs, and special values\n> > - Apply [synopsis] attribute to in-body command-form code blocks\n> \n> This is very much unexpected.  I think everybody thought [synopsis]\n> was invented to be used for the SYNOPSIS section at the beginning of\n> each manual page, and ...\n\nIn fact, the synopsis style was already applied before outside the SYNOPSIS \nsections in diff-generate-patch.adoc when describing the output of the -p \noption.\n\n\nThis formatting reaches beyond the synopsis, but the rationale is simple. Each \ntime a listing contains some , what is actually described is a \nmodel, not an actual output. The  needs a special formatting to \nconvey its special meaning.\n\nThat may mean that the naming of \"synopsis style\" may not be adequate.\n\n> \n> >  SYNOPSIS\n> >  --------\n> > \n> > -[verse]\n> > -'git bisect' start [--term-(bad|new)= --term-(good|old)=]\n> > -\t\t   [--no-checkout] [--first-parent] [ [...]] \n[--] [...]\n> > ...\n> > -'git bisect' help\n> > +[synopsis]\n> > +git bisect start [--term-(bad|new)= --term-(good|old)=]\n> > +\t\t [--no-checkout] [--first-parent] [ [...]] [--] \n[...]\n> > ...\n> > +git bisect help\n> \n> ... a change like this is very much expected and understandable, but\n> \n> new appearances of [synonsis] in places like:\n> > +[synopsis]\n> > \n> >  ------------------------------------------------\n> >  $ git bisect reset \n> >  ------------------------------------------------\n> \n> and\n> \n> > +[synopsis]\n> > \n> >  ------------------------------------------------\n> >  git bisect old []\n> >  ------------------------------------------------\n> \n> were a bit surprising and confusing.  They are not exactly command\n> syntax definitions (which is the SYNOPSIS section is about), but\n> examples of usage. \n\nAre they? the \"[]\" block is typical of synopsis syntax, not something you \nwould actually type in.\n\n> The one with '$' command line prompt feels\n> particularly confusing, as the prompt is not something that the\n> end-user gives, unlike what we write in the synopsis section.\n> \n\nThe '$' is an error to me. Will fix.\n\n> Other than that, this is quite exciting.\n\n\n\n\n"},{"id":"543706","messageId":"3044460.e9J7NaK4W3@piment-oiseau","threadId":"65651","inReplyTo":"87tss5wjpp.fsf@gitster.g","subject":"Re: [PATCH 1/5] doc: convert git-bisect to synopsis style","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2026-05-19T21:03:50Z","receivedAt":"2026-05-19T21:03:54Z","isPatch":true,"body":"On Monday, 18 May 2026 04:10:58 CEST Junio C Hamano wrote:\n> Junio C Hamano  writes:\n> >> +[synopsis]\n> >> \n> >>  ------------------------------------------------\n> >>  $ git bisect reset \n> >>  ------------------------------------------------\n> > \n> > and\n> > \n> >> +[synopsis]\n> >> \n> >>  ------------------------------------------------\n> >>  git bisect old []\n> >>  ------------------------------------------------\n> > \n> > were a bit surprising and confusing.  They are not exactly command\n> > syntax definitions (which is the SYNOPSIS section is about), but\n> > examples of usage.  The one with '$' command line prompt feels\n> > particularly confusing, as the prompt is not something that the\n> > end-user gives, unlike what we write in the synopsis section.\n> > \n> > Other than that, this is quite exciting.\n> \n> Well, my local test with asciidoctor did not barf, but it seems that\n> the documentation pipeline run in GitHub Actions CI is unhappy.\n> \n> https://github.com/git/git/actions/runs/26008649802/job/\n76444895183#step:4:4846\n> \n> I do not know what the differences among the three environments\n> (counting your development environment---only one of which fails)\n> are offhand.\n\nThank you for pointing out that the test fails with Asciidoctor. On my debian \ntesting, both asciidoc.py and asciidoctor pass. I can try and revert to \nparagraph styling instead of block styling.\n\n\n\n"},{"id":"544052","messageId":"pull.2117.v2.git.1779704908.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.git.1779049615.gitgitgadget@gmail.com","subject":"[PATCH v2 0/6] doc: convert another batch of files to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-25T10:28:21Z","receivedAt":"2026-05-25T10:28:30Z","isPatch":true,"body":"This time, 5 new conversions:\n\n * git-bisect\n * git-grep\n * git-am\n * git-apply\n * git-imap-send\n\nThis batch was an opportunity to test AI-helped conversion.\n\nChanges since v1:\n\n * clarify the use of synopsis vs code block in git-bisect, which also\n   include using '$'\n\nJean-Noël Avila (6):\n  doc: convert git-bisect to synopsis style\n  doc: git bisect: clarify the usage of the synopsis vs actual command\n  doc: convert git-grep synopsis and options to new style\n  doc: convert git-am synopsis and options to new style\n  doc: convert git-apply synopsis and options to new style\n  doc: convert git-imap-send synopsis and options to new style\n\n Documentation/asciidoc.conf.in                |   6 +\n Documentation/config/am.adoc                  |   6 +-\n Documentation/config/apply.adoc               |  17 +-\n Documentation/config/grep.adoc                |  36 ++--\n Documentation/config/imap.adoc                |  30 +--\n Documentation/format-patch-caveats.adoc       |   2 +-\n .../format-patch-end-of-commit-message.adoc   |   4 +-\n Documentation/git-am.adoc                     | 132 ++++++------\n Documentation/git-apply.adoc                  | 125 +++++------\n Documentation/git-bisect.adoc                 | 109 +++++-----\n Documentation/git-grep.adoc                   | 196 +++++++++---------\n Documentation/git-imap-send.adoc              |  24 +--\n 12 files changed, 346 insertions(+), 341 deletions(-)\n\n\nbase-commit: 56a4f3c3a221adf1df9b39da69b8a6890f803157\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2117%2Fjnavila%2Fbisect-synopsis-style-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2117/jnavila/bisect-synopsis-style-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/2117\n\nRange-diff vs v1:\n\n 1:  dca7f192f1 ! 1:  7284281fe0 doc: convert git-bisect to synopsis style\n     @@ Documentation/git-bisect.adoc: that, as it cleans up the old bisection state.)\n       With an optional argument, you can return to a different commit\n       instead:\n       \n     +-------------------------------------------------\n      +[synopsis]\n     - ------------------------------------------------\n       $ git bisect reset \n     - ------------------------------------------------\n     +-------------------------------------------------\n     + \n     + For example, `git bisect reset bisect/bad` will check out the first\n     + bad revision, while `git bisect reset HEAD` will leave you on the\n      @@ Documentation/git-bisect.adoc: To use \"old\" and \"new\" instead of \"good\" and bad, you must run `git\n       bisect start` without commits as argument and then run the following\n       commands to add the commits:\n       \n     +-------------------------------------------------\n      +[synopsis]\n     - ------------------------------------------------\n       git bisect old []\n     - ------------------------------------------------\n     +-------------------------------------------------\n       \n       to indicate that a commit was before the sought change, or\n       \n     +-------------------------------------------------\n      +[synopsis]\n     - ------------------------------------------------\n       git bisect new [...]\n     - ------------------------------------------------\n     -@@ Documentation/git-bisect.adoc: to indicate that it was after.\n     +-------------------------------------------------\n     + \n     + to indicate that it was after.\n       \n       To get a reminder of the currently used terms, use\n       \n     +-------------------------------------------------\n      +[synopsis]\n     - ------------------------------------------------\n       git bisect terms\n     - ------------------------------------------------\n     +-------------------------------------------------\n     + \n     + You can get just the old term with `git bisect terms --term-old`\n     + or `git bisect terms --term-good`; `git bisect terms --term-new`\n      @@ Documentation/git-bisect.adoc: If you would like to use your own terms instead of \"bad\"/\"good\" or\n       subcommands like `reset`, `start`, ...) by starting the\n       bisection using\n       \n     +-------------------------------------------------\n      +[synopsis]\n     - ------------------------------------------------\n       git bisect start --term-old  --term-new \n     - ------------------------------------------------\n     +-------------------------------------------------\n     + \n     + For example, if you are looking for a commit that introduced a\n     + performance regression, you might use\n      @@ Documentation/git-bisect.adoc: of `git bisect good` and `git bisect bad` to mark commits.\n       Bisect visualize/view\n       ~~~~~~~~~~~~~~~~~~~~~\n -:  ---------- > 2:  4fb33dd440 doc: git bisect: clarify the usage of the synopsis vs actual command\n 2:  1b4efce1b2 = 3:  fceaf195e8 doc: convert git-grep synopsis and options to new style\n 3:  4ab60a95f4 = 4:  b9c2adfa1d doc: convert git-am synopsis and options to new style\n 4:  437e3f99c7 = 5:  60a420ea38 doc: convert git-apply synopsis and options to new style\n 5:  dbe4d20b4b = 6:  d88824bf09 doc: convert git-imap-send synopsis and options to new style\n\n-- \ngitgitgadget\n"},{"id":"544053","messageId":"7284281fe043c931781f0bf4964d1dac73e3ff92.1779704908.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.v2.git.1779704908.gitgitgadget@gmail.com","subject":"[PATCH v2 1/6] doc: convert git-bisect to synopsis style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-25T10:28:22Z","receivedAt":"2026-05-25T10:28:32Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert Documentation/git-bisect.adoc to the modern synopsis style.\n\n- Replace [verse] with [synopsis] in the SYNOPSIS block\n- Remove single quotes around command names in the synopsis\n- Use backticks for inline commands, options, refs, and special values\n- Apply [synopsis] attribute to in-body command-form code blocks\n- Format OPTIONS entries with backtick-quoted terms and direct\n- Add synopsis-style formatting to listing blocks\n- Format man page references as `command`(N)\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/asciidoc.conf.in |  6 +++\n Documentation/git-bisect.adoc  | 90 ++++++++++++++++------------------\n 2 files changed, 48 insertions(+), 48 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex 31b883a72c..93c63b284a 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -84,6 +84,9 @@ ifdef::doctype-manpage[]\n [blockdef-open]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n \n+[blockdef-listing]\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+\n [paradef-default]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::doctype-manpage[]\n@@ -93,6 +96,9 @@ ifdef::backend-xhtml11[]\n [blockdef-open]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n \n+[blockdef-listing]\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+\n [paradef-default]\n synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::backend-xhtml11[]\ndiff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc\nindex b0078dda0e..4765d3b969 100644\n--- a/Documentation/git-bisect.adoc\n+++ b/Documentation/git-bisect.adoc\n@@ -8,20 +8,20 @@ git-bisect - Use binary search to find the commit that introduced a bug\n \n SYNOPSIS\n --------\n-[verse]\n-'git bisect' start [--term-(bad|new)= --term-(good|old)=]\n-\t\t   [--no-checkout] [--first-parent] [ [...]] [--] [...]\n-'git bisect' (bad|new|) []\n-'git bisect' (good|old|) [...]\n-'git bisect' terms [--term-(good|old) | --term-(bad|new)]\n-'git bisect' skip [(|)...]\n-'git bisect' next\n-'git bisect' reset []\n-'git bisect' (visualize|view)\n-'git bisect' replay \n-'git bisect' log\n-'git bisect' run  [...]\n-'git bisect' help\n+[synopsis]\n+git bisect start [--term-(bad|new)= --term-(good|old)=]\n+\t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n+git bisect (bad|new|) []\n+git bisect (good|old|) [...]\n+git bisect terms [--term-(good|old) | --term-(bad|new)]\n+git bisect skip [(|)...]\n+git bisect next\n+git bisect reset []\n+git bisect (visualize|view)\n+git bisect replay \n+git bisect log\n+git bisect run  [...]\n+git bisect help\n \n DESCRIPTION\n -----------\n@@ -94,7 +94,7 @@ Bisect reset\n ~~~~~~~~~~~~\n \n After a bisect session, to clean up the bisection state and return to\n-the original HEAD, issue the following command:\n+the original `HEAD`, issue the following command:\n \n ------------------------------------------------\n $ git bisect reset\n@@ -107,9 +107,8 @@ that, as it cleans up the old bisection state.)\n With an optional argument, you can return to a different commit\n instead:\n \n-------------------------------------------------\n+[synopsis]\n $ git bisect reset \n-------------------------------------------------\n \n For example, `git bisect reset bisect/bad` will check out the first\n bad revision, while `git bisect reset HEAD` will leave you on the\n@@ -143,23 +142,20 @@ To use \"old\" and \"new\" instead of \"good\" and bad, you must run `git\n bisect start` without commits as argument and then run the following\n commands to add the commits:\n \n-------------------------------------------------\n+[synopsis]\n git bisect old []\n-------------------------------------------------\n \n to indicate that a commit was before the sought change, or\n \n-------------------------------------------------\n+[synopsis]\n git bisect new [...]\n-------------------------------------------------\n \n to indicate that it was after.\n \n To get a reminder of the currently used terms, use\n \n-------------------------------------------------\n+[synopsis]\n git bisect terms\n-------------------------------------------------\n \n You can get just the old term with `git bisect terms --term-old`\n or `git bisect terms --term-good`; `git bisect terms --term-new`\n@@ -171,9 +167,8 @@ If you would like to use your own terms instead of \"bad\"/\"good\" or\n subcommands like `reset`, `start`, ...) by starting the\n bisection using\n \n-------------------------------------------------\n+[synopsis]\n git bisect start --term-old  --term-new \n-------------------------------------------------\n \n For example, if you are looking for a commit that introduced a\n performance regression, you might use\n@@ -194,7 +189,7 @@ of `git bisect good` and `git bisect bad` to mark commits.\n Bisect visualize/view\n ~~~~~~~~~~~~~~~~~~~~~\n \n-To see the currently remaining suspects in 'gitk', issue the following\n+To see the currently remaining suspects in `gitk`, issue the following\n command during the bisection process (the subcommand `view` can be used\n as an alternative to `visualize`):\n \n@@ -203,12 +198,13 @@ $ git bisect visualize\n ------------\n \n Git detects a graphical environment through various environment variables:\n-`DISPLAY`, which is set in X Window System environments on Unix systems.\n-`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions.\n-`MSYSTEM`, which is set under Msys2 and Git for Windows.\n-`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions.\n \n-If none of these environment variables is set, 'git log' is used instead.\n+`DISPLAY`:: which is set in X Window System environments on Unix systems.\n+`SESSIONNAME`:: which is set under Cygwin in interactive desktop sessions.\n+`MSYSTEM`:: which is set under Msys2 and Git for Windows.\n+`SECURITYSESSIONID`:: which may be set on macOS in interactive desktop sessions.\n+\n+If none of these environment variables is set, `git log` is used instead.\n You can also give command-line options such as `-p` and `--stat`.\n \n ------------\n@@ -342,8 +338,8 @@ code between 1 and 127 (inclusive), except 125, if the current source\n code is bad/new.\n \n Any other exit code will abort the bisect process. It should be noted\n-that a program that terminates via `exit(-1)` leaves $? = 255, (see the\n-exit(3) manual page), as the value is chopped with `& 0377`.\n+that a program that terminates via `exit(-1)` leaves `$?` = 255, (see the\n+`exit`(3) manual page), as the value is chopped with `& 0377`.\n \n The special exit code 125 should be used when the current source code\n cannot be tested. If the script exits with this code, the current\n@@ -355,12 +351,12 @@ details do not matter, as they are normal errors in the script, as far as\n `bisect run` is concerned).\n \n You may often find that during a bisect session you want to have\n-temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a\n+temporary modifications (e.g. `s/#define DEBUG 0/#define DEBUG 1/` in a\n header file, or \"revision that does not have this commit needs this\n patch applied to work around another problem this bisection is not\n interested in\") applied to the revision being tested.\n \n-To cope with such a situation, after the inner 'git bisect' finds the\n+To cope with such a situation, after the inner `git bisect` finds the\n next revision to test, the script can apply the patch\n before compiling, run the real test, and afterwards decide if the\n revision (possibly with the needed patch) passed the test and then\n@@ -370,20 +366,18 @@ determine the eventual outcome of the bisect session.\n \n OPTIONS\n -------\n---no-checkout::\n-+\n-Do not checkout the new working tree at each iteration of the bisection\n-process. Instead just update the reference named `BISECT_HEAD` to make\n-it point to the commit that should be tested.\n+`--no-checkout`::\n+\tDo not checkout the new working tree at each iteration of the bisection\n+\tprocess. Instead just update the reference named `BISECT_HEAD` to make\n+\tit point to the commit that should be tested.\n +\n This option may be useful when the test you would perform in each step\n does not require a checked out tree.\n +\n If the repository is bare, `--no-checkout` is assumed.\n \n---first-parent::\n-+\n-Follow only the first parent commit upon seeing a merge commit.\n+`--first-parent`::\n+\tFollow only the first parent commit upon seeing a merge commit.\n +\n In detecting regressions introduced through the merging of a branch, the merge\n commit will be identified as introduction of the bug and its ancestors will be\n@@ -395,7 +389,7 @@ branch contained broken or non-buildable commits, but the merge itself was OK.\n EXAMPLES\n --------\n \n-* Automatically bisect a broken build between v1.2 and HEAD:\n+* Automatically bisect a broken build between v1.2 and `HEAD`:\n +\n ------------\n $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good\n@@ -403,7 +397,7 @@ $ git bisect run make                # \"make\" builds the app\n $ git bisect reset                   # quit the bisect session\n ------------\n \n-* Automatically bisect a test failure between origin and HEAD:\n+* Automatically bisect a test failure between origin and `HEAD`:\n +\n ------------\n $ git bisect start HEAD origin --    # HEAD is bad, origin is good\n@@ -430,7 +424,7 @@ and `exit 1` otherwise.\n +\n It is safer if both `test.sh` and `check_test_case.sh` are\n outside the repository to prevent interactions between the bisect,\n-make and test processes and the scripts.\n+`make` and test processes and the scripts.\n \n * Automatically bisect with temporary modifications (hot-fix):\n +\n@@ -491,9 +485,9 @@ $ git bisect run sh -c '\n $ git bisect reset                   # quit the bisect session\n ------------\n +\n-In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that\n+In this case, when `git bisect run` finishes, `bisect/bad` will refer to a commit that\n has at least one parent whose reachable graph is fully traversable in the sense\n-required by 'git pack objects'.\n+required by `git pack-objects`.\n \n * Look for a fix instead of a regression in the code\n +\n-- \ngitgitgadget\n\n"},{"id":"544054","messageId":"4fb33dd4407a51c5ece6fb467e98c4da1ffa6f0e.1779704908.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.v2.git.1779704908.gitgitgadget@gmail.com","subject":"[PATCH v2 2/6] doc: git bisect: clarify the usage of the synopsis vs actual command","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-25T10:28:23Z","receivedAt":"2026-05-25T10:28:33Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nThe difference between a synopsis and an actual command is that the synopsis\nis a more abstract representation of the command, which may include\nplaceholders for arguments and options. The actual command is the specific\ninstance of the command with all the arguments and options filled in.\n\nThe formatting of an actual command is a code block, with the command\nprefixed by a dollar sign ($) to indicate that it is a command to be run in\nthe terminal. It can also include comments with a hash sign (#) to explain\nthe command or provide additional information, just like in a regular\nterminal session.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-bisect.adoc | 19 +++++++++----------\n 1 file changed, 9 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc\nindex 4765d3b969..d2115b2990 100644\n--- a/Documentation/git-bisect.adoc\n+++ b/Documentation/git-bisect.adoc\n@@ -96,9 +96,8 @@ Bisect reset\n After a bisect session, to clean up the bisection state and return to\n the original `HEAD`, issue the following command:\n \n-------------------------------------------------\n-$ git bisect reset\n-------------------------------------------------\n+[synopsis]\n+git bisect reset\n \n By default, this will return your tree to the commit that was checked\n out before `git bisect start`.  (A new `git bisect start` will also do\n@@ -108,7 +107,8 @@ With an optional argument, you can return to a different commit\n instead:\n \n [synopsis]\n-$ git bisect reset \n+git bisect reset \n+\n \n For example, `git bisect reset bisect/bad` will check out the first\n bad revision, while `git bisect reset HEAD` will leave you on the\n@@ -174,13 +174,13 @@ For example, if you are looking for a commit that introduced a\n performance regression, you might use\n \n ------------------------------------------------\n-git bisect start --term-old fast --term-new slow\n+$ git bisect start --term-old fast --term-new slow\n ------------------------------------------------\n \n Or if you are looking for the commit that fixed a bug, you might use\n \n ------------------------------------------------\n-git bisect start --term-new fixed --term-old broken\n+$ git bisect start --term-new fixed --term-old broken\n ------------------------------------------------\n \n Then, use `git bisect ` and `git bisect ` instead\n@@ -328,11 +328,10 @@ Bisect run\n If you have a script that can tell if the current source code is good\n or bad, you can bisect by issuing the command:\n \n-------------\n-$ git bisect run my_script arguments\n-------------\n+[synopsis]\n+git bisect run  [...]\n \n-Note that the script (`my_script` in the above example) should exit\n+Note that __ run with __  should exit\n with code 0 if the current source code is good/old, and exit with a\n code between 1 and 127 (inclusive), except 125, if the current source\n code is bad/new.\n-- \ngitgitgadget\n\n"},{"id":"544055","messageId":"fceaf195e8d2ddcb593f1b9cfacd88e996c48b75.1779704908.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.v2.git.1779704908.gitgitgadget@gmail.com","subject":"[PATCH v2 3/6] doc: convert git-grep synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-25T10:28:24Z","receivedAt":"2026-05-25T10:28:34Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-grep.adoc from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Change 'git grep' to git grep (no single quotes)\n- Backtick-quote all OPTIONS terms\n- Convert inline man page refs: grep(1) -> `grep`(1)\n- Convert inline command refs: 'git diff' -> `git diff`\n- Convert prose placeholders:  -> __\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/grep.adoc |  36 +++---\n Documentation/git-grep.adoc    | 196 ++++++++++++++++-----------------\n 2 files changed, 116 insertions(+), 116 deletions(-)\n\ndiff --git a/Documentation/config/grep.adoc b/Documentation/config/grep.adoc\nindex 10041f27b0..83d4b76dd3 100644\n--- a/Documentation/config/grep.adoc\n+++ b/Documentation/config/grep.adoc\n@@ -1,28 +1,28 @@\n-grep.lineNumber::\n-\tIf set to true, enable `-n` option by default.\n+`grep.lineNumber`::\n+\tIf set to `true`, enable `-n` option by default.\n \n-grep.column::\n-\tIf set to true, enable the `--column` option by default.\n+`grep.column`::\n+\tIf set to `true`, enable the `--column` option by default.\n \n-grep.patternType::\n-\tSet the default matching behavior. Using a value of 'basic', 'extended',\n-\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n+`grep.patternType`::\n+\tSet the default matching behavior. Using a value of `basic`, `extended`,\n+\t`fixed`, or `perl` will enable the `--basic-regexp`, `--extended-regexp`,\n \t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n-\tvalue 'default' will use the `grep.extendedRegexp` option to choose\n-\tbetween 'basic' and 'extended'.\n+\tvalue `default` will use the `grep.extendedRegexp` option to choose\n+\tbetween `basic` and `extended`.\n \n-grep.extendedRegexp::\n-\tIf set to true, enable `--extended-regexp` option by default. This\n+`grep.extendedRegexp`::\n+\tIf set to `true`, enable `--extended-regexp` option by default. This\n \toption is ignored when the `grep.patternType` option is set to a value\n-\tother than 'default'.\n+\tother than `default`.\n \n-grep.threads::\n+`grep.threads`::\n \tNumber of grep worker threads to use. If unset (or set to 0), Git will\n \tuse as many threads as the number of logical cores available.\n \n-grep.fullName::\n-\tIf set to true, enable `--full-name` option by default.\n+`grep.fullName`::\n+\tIf set to `true`, enable `--full-name` option by default.\n \n-grep.fallbackToNoIndex::\n-\tIf set to true, fall back to `git grep --no-index` if `git grep`\n-\tis executed outside of a git repository.  Defaults to false.\n+`grep.fallbackToNoIndex`::\n+\tIf set to `true`, fall back to `git grep --no-index` if `git grep`\n+\tis executed outside of a git repository.  Defaults to `false`.\ndiff --git a/Documentation/git-grep.adoc b/Documentation/git-grep.adoc\nindex a548585d4c..19b3ade16d 100644\n--- a/Documentation/git-grep.adoc\n+++ b/Documentation/git-grep.adoc\n@@ -8,8 +8,8 @@ git-grep - Print lines matching a pattern\n \n SYNOPSIS\n --------\n-[verse]\n-'git grep' [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]\n+[synopsis]\n+git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]\n \t   [-v | --invert-match] [-h|-H] [--full-name]\n \t   [-E | --extended-regexp] [-G | --basic-regexp]\n \t   [-P | --perl-regexp]\n@@ -41,139 +41,139 @@ characters.  An empty string as search expression matches all lines.\n \n OPTIONS\n -------\n---cached::\n+`--cached`::\n \tInstead of searching tracked files in the working tree, search\n \tblobs registered in the index file.\n \n---untracked::\n+`--untracked`::\n \tIn addition to searching in the tracked files in the working\n \ttree, search also in untracked files.\n \n---no-index::\n+`--no-index`::\n \tSearch files in the current directory that is not managed by Git,\n \tor by ignoring that the current directory is managed by Git.  This\n-\tis rather similar to running the regular `grep(1)` utility with its\n+\tis rather similar to running the regular `grep`(1) utility with its\n \t`-r` option specified, but with some additional benefits, such as\n-\tusing pathspec patterns to limit paths;  see the 'pathspec' entry\n+\tusing pathspec patterns to limit paths;  see the `pathspec` entry\n \tin linkgit:gitglossary[7] for more information.\n +\n This option cannot be used together with `--cached` or `--untracked`.\n See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below.\n \n---no-exclude-standard::\n+`--no-exclude-standard`::\n \tAlso search in ignored files by not honoring the `.gitignore`\n \tmechanism. Only useful with `--untracked`.\n \n---exclude-standard::\n+`--exclude-standard`::\n \tDo not pay attention to ignored files specified via the `.gitignore`\n \tmechanism.  Only useful when searching files in the current directory\n \twith `--no-index`.\n \n---recurse-submodules::\n+`--recurse-submodules`::\n \tRecursively search in each submodule that is active and\n \tchecked out in the repository.  When used in combination with the\n \t__ option the prefix of all submodule output will be the name of\n \tthe parent project's __ object.  This option cannot be used together\n \twith `--untracked`, and it has no effect if `--no-index` is specified.\n \n--a::\n---text::\n+`-a`::\n+`--text`::\n \tProcess binary files as if they were text.\n \n---textconv::\n+`--textconv`::\n \tHonor textconv filter settings.\n \n---no-textconv::\n+`--no-textconv`::\n \tDo not honor textconv filter settings.\n \tThis is the default.\n \n--i::\n---ignore-case::\n+`-i`::\n+`--ignore-case`::\n \tIgnore case differences between the patterns and the\n \tfiles.\n \n--I::\n+`-I`::\n \tDon't match the pattern in binary files.\n \n---max-depth ::\n-\tFor each  given on command line, descend at most \n+`--max-depth `::\n+\tFor each __ given on command line, descend at most __\n \tlevels of directories. A value of -1 means no limit.\n-\tThis option is ignored if  contains active wildcards.\n+\tThis option is ignored if __ contains active wildcards.\n \tIn other words if \"a*\" matches a directory named \"a*\",\n-\t\"*\" is matched literally so --max-depth is still effective.\n+\t\"*\" is matched literally so `--max-depth` is still effective.\n \n--r::\n---recursive::\n+`-r`::\n+`--recursive`::\n \tSame as `--max-depth=-1`; this is the default.\n \n---no-recursive::\n+`--no-recursive`::\n \tSame as `--max-depth=0`.\n \n--w::\n---word-regexp::\n+`-w`::\n+`--word-regexp`::\n \tMatch the pattern only at word boundary (either begin at the\n \tbeginning of a line, or preceded by a non-word character; end at\n \tthe end of a line or followed by a non-word character).\n \n--v::\n---invert-match::\n+`-v`::\n+`--invert-match`::\n \tSelect non-matching lines.\n \n--h::\n--H::\n+`-h`::\n+`-H`::\n \tBy default, the command shows the filename for each\n \tmatch.  `-h` option is used to suppress this output.\n \t`-H` is there for completeness and does not do anything\n \texcept it overrides `-h` given earlier on the command\n \tline.\n \n---full-name::\n+`--full-name`::\n \tWhen run from a subdirectory, the command usually\n \toutputs paths relative to the current directory.  This\n \toption forces paths to be output relative to the project\n \ttop directory.\n \n--E::\n---extended-regexp::\n--G::\n---basic-regexp::\n+`-E`::\n+`--extended-regexp`::\n+`-G`::\n+`--basic-regexp`::\n \tUse POSIX extended/basic regexp for patterns.  Default\n \tis to use basic regexp.\n \n--P::\n---perl-regexp::\n+`-P`::\n+`--perl-regexp`::\n \tUse Perl-compatible regular expressions for patterns.\n +\n Support for these types of regular expressions is an optional\n compile-time dependency. If Git wasn't compiled with support for them\n providing this option will cause it to die.\n \n--F::\n---fixed-strings::\n+`-F`::\n+`--fixed-strings`::\n \tUse fixed strings for patterns (don't interpret pattern\n \tas a regex).\n \n--n::\n---line-number::\n+`-n`::\n+`--line-number`::\n \tPrefix the line number to matching lines.\n \n---column::\n+`--column`::\n \tPrefix the 1-indexed byte-offset of the first match from the start of the\n \tmatching line.\n \n--l::\n---files-with-matches::\n---name-only::\n--L::\n---files-without-match::\n+`-l`::\n+`--files-with-matches`::\n+`--name-only`::\n+`-L`::\n+`--files-without-match`::\n \tInstead of showing every matched line, show only the\n \tnames of files that contain (or do not contain) matches.\n-\tFor better compatibility with 'git diff', `--name-only` is a\n+\tFor better compatibility with `git diff`, `--name-only` is a\n \tsynonym for `--files-with-matches`.\n \n--O[]::\n---open-files-in-pager[=]::\n-\tOpen the matching files in the pager (not the output of 'grep').\n+`-O[]`::\n+`--open-files-in-pager[=]`::\n+\tOpen the matching files in the pager (not the output of `grep`).\n \tIf the pager happens to be \"less\" or \"vi\", and the user\n \tspecified only one pattern, the first file is positioned at\n \tthe first match automatically. The `pager` argument is\n@@ -181,65 +181,65 @@ providing this option will cause it to die.\n \twithout a space. If `pager` is unspecified, the default pager\n \twill be used (see `core.pager` in linkgit:git-config[1]).\n \n--z::\n---null::\n+`-z`::\n+`--null`::\n \tUse \\0 as the delimiter for pathnames in the output, and print\n \tthem verbatim. Without this option, pathnames with \"unusual\"\n \tcharacters are quoted as explained for the configuration\n \tvariable `core.quotePath` (see linkgit:git-config[1]).\n \n--o::\n---only-matching::\n+`-o`::\n+`--only-matching`::\n \tPrint only the matched (non-empty) parts of a matching line, with each such\n \tpart on a separate output line.\n \n--c::\n---count::\n+`-c`::\n+`--count`::\n \tInstead of showing every matched line, show the number of\n \tlines that match.\n \n---color[=]::\n+`--color[=]`::\n \tShow colored matches.\n-\tThe value must be always (the default), never, or auto.\n+\tThe value must be `always` (the default), `never`, or `auto`.\n \n---no-color::\n+`--no-color`::\n \tTurn off match highlighting, even when the configuration file\n \tgives the default to color output.\n \tSame as `--color=never`.\n \n---break::\n+`--break`::\n \tPrint an empty line between matches from different files.\n \n---heading::\n+`--heading`::\n \tShow the filename above the matches in that file instead of\n \tat the start of each shown line.\n \n--p::\n---show-function::\n+`-p`::\n+`--show-function`::\n \tShow the preceding line that contains the function name of\n \tthe match, unless the matching line is a function name itself.\n \tThe name is determined in the same way as `git diff` works out\n \tpatch hunk headers (see 'Defining a custom hunk-header' in\n \tlinkgit:gitattributes[5]).\n \n--::\n--C ::\n---context ::\n-\tShow  leading and trailing lines, and place a line\n+`-`::\n+`-C `::\n+`--context `::\n+\tShow __ leading and trailing lines, and place a line\n \tcontaining `--` between contiguous groups of matches.\n \n--A ::\n---after-context ::\n-\tShow  trailing lines, and place a line containing\n+`-A `::\n+`--after-context `::\n+\tShow __ trailing lines, and place a line containing\n \t`--` between contiguous groups of matches.\n \n--B ::\n---before-context ::\n-\tShow  leading lines, and place a line containing\n+`-B `::\n+`--before-context `::\n+\tShow __ leading lines, and place a line containing\n \t`--` between contiguous groups of matches.\n \n--W::\n---function-context::\n+`-W`::\n+`--function-context`::\n \tShow the surrounding text from the previous line containing a\n \tfunction name up to the one before the next function name,\n \teffectively showing the whole function in which the match was\n@@ -247,22 +247,22 @@ providing this option will cause it to die.\n \t`git diff` works out patch hunk headers (see 'Defining a\n \tcustom hunk-header' in linkgit:gitattributes[5]).\n \n--m ::\n---max-count ::\n+`-m `::\n+`--max-count `::\n \tLimit the amount of matches per file. When using the `-v` or\n \t`--invert-match` option, the search stops after the specified\n \tnumber of non-matches. A value of -1 will return unlimited\n \tresults (the default). A value of 0 will exit immediately with\n \ta non-zero status.\n \n---threads ::\n-\tNumber of `grep` worker threads to use.  See 'NOTES ON THREADS'\n+`--threads `::\n+\tNumber of `grep` worker threads to use.  See `NOTES ON THREADS`\n \tand `grep.threads` in 'CONFIGURATION' for more information.\n \n--f ::\n-\tRead patterns from , one per line.\n+`-f `::\n+\tRead patterns from __, one per line.\n +\n-Passing the pattern via  allows for providing a search pattern\n+Passing the pattern via __ allows for providing a search pattern\n containing a \\0.\n +\n Not all pattern types support patterns containing \\0. Git will error\n@@ -279,44 +279,44 @@ In future versions we may learn to support patterns containing \\0 for\n more search backends, until then we'll die when the pattern type in\n question doesn't support them.\n \n--e::\n+`-e`::\n \tThe next parameter is the pattern. This option has to be\n \tused for patterns starting with `-` and should be used in\n \tscripts passing user input to grep.  Multiple patterns are\n-\tcombined by 'or'.\n+\tcombined by `or`.\n \n---and::\n---or::\n---not::\n-( ... )::\n+`--and`::\n+`--or`::\n+`--not`::\n+`( ... )`::\n \tSpecify how multiple patterns are combined using Boolean\n \texpressions.  `--or` is the default operator.  `--and` has\n \thigher precedence than `--or`.  `-e` has to be used for all\n \tpatterns.\n \n---all-match::\n+`--all-match`::\n \tWhen giving multiple pattern expressions combined with `--or`,\n \tthis flag is specified to limit the match to files that\n \thave lines to match all of them.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tDo not output matched lines; instead, exit with status 0 when\n \tthere is a match and with non-zero status when there isn't.\n \n-...::\n+`...`::\n \tInstead of searching tracked files in the working tree, search\n \tblobs in the given trees.\n \n-\\--::\n+`--`::\n \tSignals the end of options; the rest of the parameters\n-\tare  limiters.\n+\tare __ limiters.\n \n-...::\n+`...`::\n \tIf given, limit the search to paths matching at least one pattern.\n-\tBoth leading paths match and glob(7) patterns are supported.\n+\tBoth leading paths match and `glob`(7) patterns are supported.\n +\n-For more details about the  syntax, see the 'pathspec' entry\n+For more details about the __ syntax, see the `pathspec` entry\n in linkgit:gitglossary[7].\n \n EXAMPLES\n-- \ngitgitgadget\n\n"},{"id":"544058","messageId":"b9c2adfa1ddf9923a30dea726b51638e979c05b1.1779704908.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.v2.git.1779704908.gitgitgadget@gmail.com","subject":"[PATCH v2 4/6] doc: convert git-am synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-25T10:28:25Z","receivedAt":"2026-05-25T10:28:35Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-am from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Backtick-quote all OPTIONS terms\n- Convert inline man page refs\n- Convert inline command refs\n- Convert prose placeholders:\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/am.adoc                  |   6 +-\n Documentation/format-patch-caveats.adoc       |   2 +-\n .../format-patch-end-of-commit-message.adoc   |   4 +-\n Documentation/git-am.adoc                     | 132 +++++++++---------\n 4 files changed, 72 insertions(+), 72 deletions(-)\n\ndiff --git a/Documentation/config/am.adoc b/Documentation/config/am.adoc\nindex e9561e12d7..250e6b5047 100644\n--- a/Documentation/config/am.adoc\n+++ b/Documentation/config/am.adoc\n@@ -1,11 +1,11 @@\n-am.keepcr::\n+`am.keepcr`::\n \tIf true, linkgit:git-am[1] will call linkgit:git-mailsplit[1]\n \tfor patches in mbox format with parameter `--keep-cr`. In this\n \tcase linkgit:git-mailsplit[1] will\n \tnot remove `\\r` from lines ending with `\\r\\n`. Can be overridden\n \tby giving `--no-keep-cr` from the command line.\n \n-am.threeWay::\n+`am.threeWay`::\n \tBy default, linkgit:git-am[1] will fail if the patch does not\n \tapply cleanly. When set to true, this setting tells\n \tlinkgit:git-am[1] to fall back on 3-way merge if the patch\n@@ -13,7 +13,7 @@ am.threeWay::\n \thave those blobs available locally (equivalent to giving the\n \t`--3way` option from the command line). Defaults to `false`.\n \n-am.messageId::\n+`am.messageId`::\n \tAdd a `Message-ID` trailer based on the email header to the\n \tcommit when using linkgit:git-am[1] (see\n \tlinkgit:git-interpret-trailers[1]). See also the `--message-id`\ndiff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc\nindex 807a65b885..133e4757e7 100644\n--- a/Documentation/format-patch-caveats.adoc\n+++ b/Documentation/format-patch-caveats.adoc\n@@ -28,6 +28,6 @@ repositories. This goes to show that this behavior does not only impact\n email workflows.\n \n Given these limitations, one might be tempted to use a general-purpose\n-utility like patch(1) instead. However, patch(1) will not only look for\n+utility like `patch`(1) instead. However, `patch`(1) will not only look for\n unindented diffs (like linkgit:git-am[1]) but will try to apply indented\n diffs as well.\ndiff --git a/Documentation/format-patch-end-of-commit-message.adoc b/Documentation/format-patch-end-of-commit-message.adoc\nindex ec1ef79f5e..a1a624d2ac 100644\n--- a/Documentation/format-patch-end-of-commit-message.adoc\n+++ b/Documentation/format-patch-end-of-commit-message.adoc\n@@ -1,8 +1,8 @@\n Any line that is of the form:\n \n * three-dashes and end-of-line, or\n-* a line that begins with \"diff -\", or\n-* a line that begins with \"Index: \"\n+* a line that begins with `diff -`, or\n+* a line that begins with `Index: `\n \n is taken as the beginning of a patch, and the commit log message\n is terminated before the first occurrence of such a line.\ndiff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc\nindex ac65852918..28adf4cf65 100644\n--- a/Documentation/git-am.adoc\n+++ b/Documentation/git-am.adoc\n@@ -8,17 +8,17 @@ git-am - Apply a series of patches from a mailbox\n \n SYNOPSIS\n --------\n-[verse]\n-'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]\n+[synopsis]\n+git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]\n \t [--[no-]3way] [--interactive] [--committer-date-is-author-date]\n \t [--ignore-date] [--ignore-space-change | --ignore-whitespace]\n \t [--whitespace=] [-C] [-p] [--directory=]\n \t [--exclude=] [--include=] [--reject] [-q | --quiet]\n-\t [--[no-]scissors] [-S[]] [--patch-format=]\n+\t [--[no-]scissors] [-S[]] [--patch-format=]\n \t [--quoted-cr=]\n \t [--empty=(stop|drop|keep)]\n \t [( | )...]\n-'git am' (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)\n+git am (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)\n \n DESCRIPTION\n -----------\n@@ -30,45 +30,45 @@ history without merges.\n \n OPTIONS\n -------\n-(|)...::\n+`(|)...`::\n \tThe list of mailbox files to read patches from. If you do not\n \tsupply this argument, the command reads from the standard input.\n \tIf you supply directories, they will be treated as Maildirs.\n \n--s::\n---signoff::\n+`-s`::\n+`--signoff`::\n \tAdd a `Signed-off-by` trailer to the commit message (see\n \tlinkgit:git-interpret-trailers[1]), using the committer identity\n \tof yourself.  See the signoff option in linkgit:git-commit[1]\n \tfor more information.\n \n--k::\n---keep::\n+`-k`::\n+`--keep`::\n \tPass `-k` flag to linkgit:git-mailinfo[1].\n \n---keep-non-patch::\n+`--keep-non-patch`::\n \tPass `-b` flag to linkgit:git-mailinfo[1].\n \n---keep-cr::\n---no-keep-cr::\n+`--keep-cr`::\n+`--no-keep-cr`::\n \tWith `--keep-cr`, call linkgit:git-mailsplit[1]\n \twith the same option, to prevent it from stripping CR at the end of\n \tlines. `am.keepcr` configuration variable can be used to specify the\n \tdefault behaviour.  `--no-keep-cr` is useful to override `am.keepcr`.\n \n--c::\n---scissors::\n+`-c`::\n+`--scissors`::\n \tRemove everything in body before a scissors line (see\n \tlinkgit:git-mailinfo[1]). Can be activated by default using\n \tthe `mailinfo.scissors` configuration variable.\n \n---no-scissors::\n+`--no-scissors`::\n \tIgnore scissors lines (see linkgit:git-mailinfo[1]).\n \n---quoted-cr=::\n+`--quoted-cr=`::\n \tThis flag will be passed down to linkgit:git-mailinfo[1].\n \n---empty=(drop|keep|stop)::\n+`--empty=(drop|keep|stop)`::\n \tHow to handle an e-mail message lacking a patch:\n +\n --\n@@ -82,23 +82,23 @@ OPTIONS\n \tsession. This is the default behavior.\n --\n \n--m::\n---message-id::\n+`-m`::\n+`--message-id`::\n \tPass the `-m` flag to linkgit:git-mailinfo[1],\n \tso that the `Message-ID` header is added to the commit message.\n \tThe `am.messageid` configuration variable can be used to specify\n \tthe default behaviour.\n \n---no-message-id::\n+`--no-message-id`::\n \tDo not add the Message-ID header to the commit message.\n \t`--no-message-id` is useful to override `am.messageid`.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tBe quiet. Only print error messages.\n \n--u::\n---utf8::\n+`-u`::\n+`--utf8`::\n \tPass `-u` flag to linkgit:git-mailinfo[1].\n \tThe proposed commit log message taken from the e-mail\n \tis re-coded into UTF-8 encoding (configuration variable\n@@ -108,57 +108,57 @@ OPTIONS\n This was optional in prior versions of git, but now it is the\n default.   You can use `--no-utf8` to override this.\n \n---no-utf8::\n+`--no-utf8`::\n \tPass `-n` flag to linkgit:git-mailinfo[1].\n \n--3::\n---3way::\n---no-3way::\n+`-3`::\n+`--3way`::\n+`--no-3way`::\n \tWhen the patch does not apply cleanly, fall back on\n \t3-way merge if the patch records the identity of blobs\n \tit is supposed to apply to and we have those blobs\n \tavailable locally. `--no-3way` can be used to override\n-\tam.threeWay configuration variable. For more information,\n-\tsee am.threeWay in linkgit:git-config[1].\n+\t`am.threeWay` configuration variable. For more information,\n+\tsee `am.threeWay` in linkgit:git-config[1].\n \n include::rerere-options.adoc[]\n \n---ignore-space-change::\n---ignore-whitespace::\n---whitespace=::\n--C::\n--p::\n---directory=::\n---exclude=::\n---include=::\n---reject::\n+`--ignore-space-change`::\n+`--ignore-whitespace`::\n+`--whitespace=`::\n+`-C`::\n+`-p`::\n+`--directory=`::\n+`--exclude=`::\n+`--include=`::\n+`--reject`::\n \tThese flags are passed to the linkgit:git-apply[1] program that\n \tapplies the patch.\n +\n-Valid  for the `--whitespace` option are:\n+Valid __ for the `--whitespace` option are:\n `nowarn`, `warn`, `fix`, `error`, and `error-all`.\n \n---patch-format::\n+`--patch-format`::\n \tBy default the command will try to detect the patch format\n \tautomatically. This option allows the user to bypass the automatic\n \tdetection and specify the patch format that the patch(es) should be\n \tinterpreted as. Valid formats are mbox, mboxrd,\n \tstgit, stgit-series, and hg.\n \n--i::\n---interactive::\n+`-i`::\n+`--interactive`::\n \tRun interactively.\n \n---verify::\n--n::\n---no-verify::\n+`--verify`::\n+`-n`::\n+`--no-verify`::\n \tRun the `pre-applypatch` and `applypatch-msg` hooks. This is the\n \tdefault. Skip these hooks with `-n` or `--no-verify`. See also\n \tlinkgit:githooks[5].\n +\n Note that `post-applypatch` cannot be skipped.\n \n---committer-date-is-author-date::\n+`--committer-date-is-author-date`::\n \tBy default the command records the date from the e-mail\n \tmessage as the commit author date, and uses the time of\n \tcommit creation as the committer date. This allows the\n@@ -172,29 +172,29 @@ committer date when applying commits on top of a base which commit is\n older (in terms of the commit date) than the oldest patch you are\n applying.\n \n---ignore-date::\n+`--ignore-date`::\n \tBy default the command records the date from the e-mail\n \tmessage as the commit author date, and uses the time of\n \tcommit creation as the committer date. This allows the\n \tuser to lie about the author date by using the same\n \tvalue as the committer date.\n \n---skip::\n+`--skip`::\n \tSkip the current patch.  This is only meaningful when\n \trestarting an aborted patch.\n \n--S[]::\n---gpg-sign[=]::\n---no-gpg-sign::\n-\tGPG-sign commits. The `keyid` argument is optional and\n+`-S[]`::\n+`--gpg-sign[=]`::\n+`--no-gpg-sign`::\n+\tGPG-sign commits. The __ is optional and\n \tdefaults to the committer identity; if specified, it must be\n \tstuck to the option without a space. `--no-gpg-sign` is useful to\n \tcountermand both `commit.gpgSign` configuration variable, and\n \tearlier `--gpg-sign`.\n \n---continue::\n--r::\n---resolved::\n+`--continue`::\n+`-r`::\n+`--resolved`::\n \tAfter a patch failure (e.g. attempting to apply\n \tconflicting patch), the user has applied it by hand and\n \tthe index file stores the result of the application.\n@@ -202,36 +202,36 @@ applying.\n \textracted from the e-mail message and the current index\n \tfile, and continue.\n \n---resolvemsg=::\n-\tWhen a patch failure occurs,  will be printed\n+`--resolvemsg=`::\n+\tWhen a patch failure occurs, __ will be printed\n \tto the screen before exiting.  This overrides the\n \tstandard message informing you to use `--continue`\n \tor `--skip` to handle the failure.  This is solely\n \tfor internal use between linkgit:git-rebase[1] and\n \tlinkgit:git-am[1].\n \n---abort::\n+`--abort`::\n \tRestore the original branch and abort the patching operation.\n \tRevert the contents of files involved in the am operation to their\n \tpre-am state.\n \n---quit::\n-\tAbort the patching operation but keep HEAD and the index\n+`--quit`::\n+\tAbort the patching operation but keep `HEAD` and the index\n \tuntouched.\n \n---retry::\n+`--retry`::\n \tTry to apply the last conflicting patch again. This is generally\n \tonly useful for passing extra options to the retry attempt\n \t(e.g., `--3way`), since otherwise you'll just see the same\n \tfailure again.\n \n---show-current-patch[=(diff|raw)]::\n+`--show-current-patch[=(diff|raw)]`::\n \tShow the message at which linkgit:git-am[1] has stopped due to\n \tconflicts.  If `raw` is specified, show the raw contents of\n \tthe e-mail message; if `diff`, show the diff portion only.\n \tDefaults to `raw`.\n \n---allow-empty::\n+`--allow-empty`::\n \tAfter a patch failure on an input e-mail message lacking a patch,\n \tcreate an empty commit with the contents of the e-mail message\n \tas its log message.\n@@ -278,11 +278,11 @@ operation is finished, so if you decide to start over from scratch,\n run `git am --abort` before running the command with mailbox\n names.\n \n-Before any patches are applied, ORIG_HEAD is set to the tip of the\n+Before any patches are applied, `ORIG_HEAD` is set to the tip of the\n current branch.  This is useful if you have problems with multiple\n commits, like running linkgit:git-am[1] on the wrong branch or an error\n in the commits that is more easily fixed by changing the mailbox (e.g.\n-errors in the \"From:\" lines).\n+errors in the `From:` lines).\n \n [[caveats]]\n CAVEATS\n-- \ngitgitgadget\n\n"},{"id":"544056","messageId":"60a420ea38b852570d55cf059e68b08d773571dd.1779704908.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.v2.git.1779704908.gitgitgadget@gmail.com","subject":"[PATCH v2 5/6] doc: convert git-apply synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-25T10:28:26Z","receivedAt":"2026-05-25T10:28:37Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-apply from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Backtick-quote all OPTIONS terms and config keys in config/apply.adoc\n- Convert single-quoted inline commands ('git apply', 'diff', etc.)\n- Wrap standalone placeholders in underscores (, , )\n- Backtick-quote `*.rej` and GNU `patch` tool references\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/apply.adoc |  17 +++--\n Documentation/git-apply.adoc    | 125 ++++++++++++++++----------------\n 2 files changed, 74 insertions(+), 68 deletions(-)\n\ndiff --git a/Documentation/config/apply.adoc b/Documentation/config/apply.adoc\nindex f9908e210a..36fcea6291 100644\n--- a/Documentation/config/apply.adoc\n+++ b/Documentation/config/apply.adoc\n@@ -1,11 +1,16 @@\n-apply.ignoreWhitespace::\n-\tWhen set to 'change', tells 'git apply' to ignore changes in\n+`apply.ignoreWhitespace`::\n+\tWhen set to `change`, tells `git apply` to ignore changes in\n \twhitespace, in the same way as the `--ignore-space-change`\n \toption.\n-\tWhen set to one of: no, none, never, false, it tells 'git apply' to\n+\tWhen set to one of: `no`, `none`, `never`, `false`, it tells `git apply` to\n \trespect all whitespace differences.\n+ifndef::git-apply[]\n \tSee linkgit:git-apply[1].\n+endif::git-apply[]\n \n-apply.whitespace::\n-\tTells 'git apply' how to handle whitespace, in the same way\n-\tas the `--whitespace` option. See linkgit:git-apply[1].\n+`apply.whitespace`::\n+\tTells `git apply` how to handle whitespace, in the same way\n+\tas the `--whitespace` option.\n+ifndef::git-apply[]\n+\tSee linkgit:git-apply[1].\n+endif::git-apply[]\ndiff --git a/Documentation/git-apply.adoc b/Documentation/git-apply.adoc\nindex 6c71ee69da..3f22dac1ce 100644\n--- a/Documentation/git-apply.adoc\n+++ b/Documentation/git-apply.adoc\n@@ -8,8 +8,8 @@ git-apply - Apply a patch to files and/or to the index\n \n SYNOPSIS\n --------\n-[verse]\n-'git apply' [--stat] [--numstat] [--summary] [--check]\n+[synopsis]\n+git apply [--stat] [--numstat] [--summary] [--check]\n \t  [--index | --intent-to-add] [--3way] [--ours | --theirs | --union]\n \t  [--apply] [--no-add] [--build-fake-ancestor=] [-R | --reverse]\n \t  [--allow-binary-replacement | --binary] [--reject] [-z]\n@@ -35,33 +35,33 @@ linkgit:git-format-patch[1] and/or received by email.\n \n OPTIONS\n -------\n-...::\n-\tThe files to read the patch from.  '-' can be used to read\n+`...`::\n+\tThe files to read the patch from.  `-` can be used to read\n \tfrom the standard input.\n \n---stat::\n+`--stat`::\n \tInstead of applying the patch, output diffstat for the\n \tinput.  Turns off \"apply\".\n \n---numstat::\n+`--numstat`::\n \tSimilar to `--stat`, but shows the number of added and\n \tdeleted lines in decimal notation and the pathname without\n \tabbreviation, to make it more machine friendly.  For\n \tbinary files, outputs two `-` instead of saying\n \t`0 0`.  Turns off \"apply\".\n \n---summary::\n+`--summary`::\n \tInstead of applying the patch, output a condensed\n \tsummary of information obtained from git diff extended\n \theaders, such as creations, renames, and mode changes.\n \tTurns off \"apply\".\n \n---check::\n+`--check`::\n \tInstead of applying the patch, see if the patch is\n \tapplicable to the current working tree and/or the index\n \tfile and detects errors.  Turns off \"apply\".\n \n---index::\n+`--index`::\n \tApply the patch to both the index and the working tree (or\n \tmerely check that it would apply cleanly to both if `--check` is\n \tin effect). Note that `--index` expects index entries and\n@@ -70,13 +70,13 @@ OPTIONS\n \traise an error if they are not, even if the patch would apply\n \tcleanly to both the index and the working tree in isolation.\n \n---cached::\n+`--cached`::\n \tApply the patch to just the index, without touching the working\n \ttree. If `--check` is in effect, merely check that it would\n \tapply cleanly to the index entry.\n \n--N::\n---intent-to-add::\n+`-N`::\n+`--intent-to-add`::\n \tWhen applying the patch only to the working tree, mark new\n \tfiles to be added to the index later (see `--intent-to-add`\n \toption in linkgit:git-add[1]). This option is ignored if\n@@ -84,8 +84,8 @@ OPTIONS\n \trepository. Note that `--index` could be implied by other options\n \tsuch as `--3way`.\n \n--3::\n---3way::\n+`-3`::\n+`--3way`::\n \tAttempt 3-way merge if the patch records the identity of blobs it is supposed\n \tto apply to and we have those blobs available locally, possibly leaving the\n \tconflict markers in the files in the working tree for the user to\n@@ -94,14 +94,14 @@ OPTIONS\n \tWhen used with the `--cached` option, any conflicts are left at higher stages\n \tin the cache.\n \n---ours::\n---theirs::\n---union::\n+`--ours`::\n+`--theirs`::\n+`--union`::\n \tInstead of leaving conflicts in the file, resolve conflicts favouring\n-\tour (or their or both) side of the lines. Requires --3way.\n+\tour (or their or both) side of the lines. Requires `--3way`.\n \n---build-fake-ancestor=::\n-\tNewer 'git diff' output has embedded 'index information'\n+`--build-fake-ancestor=`::\n+\tNewer `git diff` output has embedded 'index information'\n \tfor each blob to help identify the original version that\n \tthe patch applies to.  When this flag is given, and if\n \tthe original versions of the blobs are available locally,\n@@ -110,18 +110,18 @@ OPTIONS\n When a pure mode change is encountered (which has no index information),\n the information is read from the current index instead.\n \n--R::\n---reverse::\n+`-R`::\n+`--reverse`::\n \tApply the patch in reverse.\n \n---reject::\n-\tFor atomicity, 'git apply' by default fails the whole patch and\n+`--reject`::\n+\tFor atomicity, `git apply` by default fails the whole patch and\n \tdoes not touch the working tree when some of the hunks\n \tdo not apply.  This option makes it apply\n \tthe parts of the patch that are applicable, and leave the\n-\trejected hunks in corresponding *.rej files.\n+\trejected hunks in corresponding `*.rej` files.\n \n--z::\n+`-z`::\n \tWhen `--numstat` has been given, do not munge pathnames,\n \tbut use a NUL-terminated machine-readable format.\n +\n@@ -129,20 +129,20 @@ Without this option, pathnames with \"unusual\" characters are quoted as\n explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n--p::\n-\tRemove  leading path components (separated by slashes) from\n+`-p`::\n+\tRemove __ leading path components (separated by slashes) from\n \ttraditional diff paths. E.g., with `-p2`, a patch against\n \t`a/dir/file` will be applied directly to `file`. The default is\n \t1.\n \n--C::\n-\tEnsure at least  lines of surrounding context match before\n+`-C`::\n+\tEnsure at least __ lines of surrounding context match before\n \tand after each change.  When fewer lines of surrounding\n \tcontext exist they all must match.  By default no context is\n \tever ignored.\n \n---unidiff-zero::\n-\tBy default, 'git apply' expects that the patch being\n+`--unidiff-zero`::\n+\tBy default, `git apply` expects that the patch being\n \tapplied is a unified diff with at least one line of context.\n \tThis provides good safety measures, but breaks down when\n \tapplying a diff generated with `--unified=0`. To bypass these\n@@ -151,34 +151,34 @@ linkgit:git-config[1]).\n Note, for the reasons stated above, the usage of context-free patches is\n discouraged.\n \n---apply::\n+`--apply`::\n \tIf you use any of the options marked \"Turns off\n-\t'apply'\" above, 'git apply' reads and outputs the\n+\t'apply'\" above, `git apply` reads and outputs the\n \trequested information without actually applying the\n \tpatch.  Give this flag after those flags to also apply\n \tthe patch.\n \n---no-add::\n+`--no-add`::\n \tWhen applying a patch, ignore additions made by the\n \tpatch.  This can be used to extract the common part between\n-\ttwo files by first running 'diff' on them and applying\n+\ttwo files by first running `diff` on them and applying\n \tthe result with this option, which would apply the\n \tdeletion part but not the addition part.\n \n---allow-binary-replacement::\n---binary::\n+`--allow-binary-replacement`::\n+`--binary`::\n \tHistorically we did not allow binary patch application\n \twithout an explicit permission from the user, and this\n \tflag was the way to do so.  Currently, we always allow binary\n \tpatch application, so this is a no-op.\n \n---exclude=::\n-\tDon't apply changes to files matching the given path pattern. This can\n+`--exclude=`::\n+\tDon't apply changes to files matching __. This can\n \tbe useful when importing patchsets, where you want to exclude certain\n \tfiles or directories.\n \n---include=::\n-\tApply changes to files matching the given path pattern. This can\n+`--include=`::\n+\tApply changes to files matching the __. This can\n \tbe useful when importing patchsets, where you want to include certain\n \tfiles or directories.\n +\n@@ -188,15 +188,15 @@ patch to each path is used.  A patch to a path that does not match any\n include/exclude pattern is used by default if there is no include pattern\n on the command line, and ignored if there is any include pattern.\n \n---ignore-space-change::\n---ignore-whitespace::\n+`--ignore-space-change`::\n+`--ignore-whitespace`::\n \tWhen applying a patch, ignore changes in whitespace in context\n \tlines if necessary.\n \tContext lines will preserve their whitespace, and they will not\n \tundergo whitespace fixing regardless of the value of the\n \t`--whitespace` option. New lines will still be fixed, though.\n \n---whitespace=::\n+`--whitespace=`::\n \tWhen applying a patch, detect a new or modified line that has\n \twhitespace errors.  What are considered whitespace errors is\n \tcontrolled by `core.whitespace` configuration.  By default,\n@@ -209,7 +209,7 @@ By default, the command outputs warning messages but applies the patch.\n When `git-apply` is used for statistics and not applying a\n patch, it defaults to `nowarn`.\n +\n-You can use different `` values to control this\n+You can use different __ values to control this\n behavior:\n +\n * `nowarn` turns off the trailing whitespace warning.\n@@ -223,48 +223,48 @@ behavior:\n   to apply the patch.\n * `error-all` is similar to `error` but shows all errors.\n \n---inaccurate-eof::\n-\tUnder certain circumstances, some versions of 'diff' do not correctly\n+`--inaccurate-eof`::\n+\tUnder certain circumstances, some versions of `diff` do not correctly\n \tdetect a missing new-line at the end of the file. As a result, patches\n-\tcreated by such 'diff' programs do not record incomplete lines\n+\tcreated by such `diff` programs do not record incomplete lines\n \tcorrectly. This option adds support for applying such patches by\n \tworking around this bug.\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tReport progress to stderr. By default, only a message about the\n \tcurrent patch being applied will be printed. This option will cause\n \tadditional information to be reported.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tSuppress stderr output. Messages about patch status and progress\n \twill not be printed.\n \n---recount::\n+`--recount`::\n \tDo not trust the line counts in the hunk headers, but infer them\n \tby inspecting the patch (e.g. after editing the patch without\n \tadjusting the hunk headers appropriately).\n \n---directory=::\n-\tPrepend  to all filenames.  If a \"-p\" argument was also passed,\n+`--directory=`::\n+\tPrepend __ to all filenames.  If a `-p` argument was also passed,\n \tit is applied before prepending the new root.\n +\n For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh`\n can be applied to the file in the working tree `modules/git-gui/git-gui.sh` by\n running `git apply --directory=modules/git-gui`.\n \n---unsafe-paths::\n+`--unsafe-paths`::\n \tBy default, a patch that affects outside the working area\n \t(either a Git controlled working tree, or the current working\n-\tdirectory when \"git apply\" is used as a replacement of GNU\n-\tpatch) is rejected as a mistake (or a mischief).\n+\tdirectory when `git apply` is used as a replacement of GNU\n+\t`patch`) is rejected as a mistake (or a mischief).\n +\n-When `git apply` is used as a \"better GNU patch\", the user can pass\n+When `git apply` is used as a \"better GNU `patch`\", the user can pass\n the `--unsafe-paths` option to override this safety check.  This option\n has no effect when `--index` or `--cached` is in use.\n \n---allow-empty::\n+`--allow-empty`::\n \tDon't return an error for patches containing no diff. This includes\n \tempty patches and patches with commit text only.\n \n@@ -273,11 +273,12 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.adoc[]\n \n+:git-apply: 1\n include::config/apply.adoc[]\n \n SUBMODULES\n ----------\n-If the patch contains any changes to submodules then 'git apply'\n+If the patch contains any changes to submodules then `git apply`\n treats these changes as follows.\n \n If `--index` is specified (explicitly or implicitly), then the submodule\n-- \ngitgitgadget\n\n"},{"id":"544057","messageId":"d88824bf0918b1d9f70de700cc04593bea8145b5.1779704908.git.gitgitgadget@gmail.com","threadId":"65651","inReplyTo":"pull.2117.v2.git.1779704908.gitgitgadget@gmail.com","subject":"[PATCH v2 6/6] doc: convert git-imap-send synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-25T10:28:27Z","receivedAt":"2026-05-25T10:28:39Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nConvert git-imap-send from [verse]/single-quote style to the modern\nsynopsis-block style:\n\n- Replace [verse] with [synopsis] in SYNOPSIS block\n- Backtick-quote all OPTIONS terms\n- Backtick-quote all config keys in config/imap.adoc\n- Backtick-quote bare config key references in prose\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/imap.adoc   | 30 +++++++++++++++---------------\n Documentation/git-imap-send.adoc | 24 ++++++++++++------------\n 2 files changed, 27 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc\nindex 4682a6bd03..cb8f5e2700 100644\n--- a/Documentation/config/imap.adoc\n+++ b/Documentation/config/imap.adoc\n@@ -1,44 +1,44 @@\n-imap.folder::\n+`imap.folder`::\n \tThe folder to drop the mails into, which is typically the Drafts\n \tfolder. For example: `INBOX.Drafts`, `INBOX/Drafts` or\n \t`[Gmail]/Drafts`. The IMAP folder to interact with MUST be specified;\n \tthe value of this configuration variable is used as the fallback\n \tdefault value when the `--folder` option is not given.\n \n-imap.tunnel::\n+`imap.tunnel`::\n \tCommand used to set up a tunnel to the IMAP server through which\n \tcommands will be piped instead of using a direct network connection\n-\tto the server. Required when imap.host is not set.\n+\tto the server. Required when `imap.host` is not set.\n \n-imap.host::\n+`imap.host`::\n \tA URL identifying the server. Use an `imap://` prefix for non-secure\n \tconnections and an `imaps://` prefix for secure connections.\n-\tIgnored when imap.tunnel is set, but required otherwise.\n+\tIgnored when `imap.tunnel` is set, but required otherwise.\n \n-imap.user::\n+`imap.user`::\n \tThe username to use when logging in to the server.\n \n-imap.pass::\n+`imap.pass`::\n \tThe password to use when logging in to the server.\n \n-imap.port::\n+`imap.port`::\n \tAn integer port number to connect to on the server.\n-\tDefaults to 143 for imap:// hosts and 993 for imaps:// hosts.\n-\tIgnored when imap.tunnel is set.\n+\tDefaults to 143 for `imap://` hosts and 993 for `imaps://` hosts.\n+\tIgnored when `imap.tunnel` is set.\n \n-imap.sslverify::\n+`imap.sslverify`::\n \tA boolean to enable/disable verification of the server certificate\n \tused by the SSL/TLS connection. Default is `true`. Ignored when\n-\timap.tunnel is set.\n+\t`imap.tunnel` is set.\n \n-imap.preformattedHTML::\n+`imap.preformattedHTML`::\n \tA boolean to enable/disable the use of html encoding when sending\n-\ta patch.  An html encoded patch will be bracketed with 
\n+\ta patch.  An html encoded patch will be bracketed with `
`\n \tand have a content type of text/html.  Ironically, enabling this\n \toption causes Thunderbird to send the patch as a plain/text,\n \tformat=fixed email.  Default is `false`.\n \n-imap.authMethod::\n+`imap.authMethod`::\n \tSpecify the authentication method for authenticating with the IMAP server.\n \tIf Git was built with the NO_CURL option, or if your curl version is older\n \tthan 7.34.0, or if you're running git-imap-send with the `--no-curl`\ndiff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc\nindex 278e5ccd36..538b91afc0 100644\n--- a/Documentation/git-imap-send.adoc\n+++ b/Documentation/git-imap-send.adoc\n@@ -8,9 +8,9 @@ git-imap-send - Send a collection of patches from stdin to an IMAP folder\n \n SYNOPSIS\n --------\n-[verse]\n-'git imap-send' [-v] [-q] [--[no-]curl] [(--folder|-f) ]\n-'git imap-send' --list\n+[synopsis]\n+git imap-send [-v] [-q] [--[no-]curl] [(--folder|-f) ]\n+git imap-send --list\n \n \n DESCRIPTION\n@@ -32,30 +32,30 @@ $ git format-patch --signoff --stdout --attach origin | git imap-send\n OPTIONS\n -------\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tBe verbose.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tBe quiet.\n \n--f ::\n---folder=::\n+`-f `::\n+`--folder=`::\n \tSpecify the folder in which the emails have to saved.\n \tFor example: `--folder=[Gmail]/Drafts` or `-f INBOX/Drafts`.\n \n---curl::\n+`--curl`::\n \tUse libcurl to communicate with the IMAP server, unless tunneling\n \tinto it.  Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND\n \toption set.\n \n---no-curl::\n+`--no-curl`::\n \tTalk to the IMAP server using git's own IMAP routines instead of\n \tusing libcurl.  Ignored if Git was built with the NO_OPENSSL option\n \tset.\n \n---list::\n+`--list`::\n \tRun the IMAP LIST command to output a list of all the folders present.\n \n CONFIGURATION\n-- \ngitgitgadget\n"}]}