{"thread":{"id":"66038","subject":"[PATCH 0/4] A new batch of synopsis conversion","startedAt":"2026-07-19T19:54:41Z","lastAt":"2026-07-29T21:29:40Z","messageCount":16,"participants":["Jean-Noël Avila via GitGitGadget","Junio C Hamano","Jean-Noël AVILA"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"548633","messageId":"pull.2185.git.1784490878.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":null,"subject":"[PATCH 0/4] A new batch of synopsis conversion","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-19T19:54:33Z","receivedAt":"2026-07-19T19:54:41Z","isPatch":true,"body":"The conversion to synopsis continues. Now the commands are less common, so I\nmay propose larger PRs if it's ok.\n\nJean-Noël Avila (4):\n  doc: convert git-imap-send synopsis and options to new style\n  doc: convert git-format-patch synopsis and options to new style\n  doc: convert git-send-email synopsis and options to new style\n  doc: convert git-request-pull synopsis and options to new style\n\n Documentation/config/imap.adoc      |   2 +-\n Documentation/config/sendemail.adoc |  92 +++++-----\n Documentation/diff-options.adoc     |   8 +-\n Documentation/git-format-patch.adoc | 264 ++++++++++++++--------------\n Documentation/git-imap-send.adoc    |   7 +-\n Documentation/git-request-pull.adoc |  38 ++--\n Documentation/git-send-email.adoc   | 162 ++++++++---------\n 7 files changed, 292 insertions(+), 281 deletions(-)\n\n\nbase-commit: 08621c32d5536babd139ab1a9086349b3672edd6\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2185%2Fjnavila%2Fconvert_synopsis_202606-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2185/jnavila/convert_synopsis_202606-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2185\n-- \ngitgitgadget\n"},{"id":"548634","messageId":"798c06439015b3f5056574be4eaf09ef71f66494.1784490878.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.git.1784490878.gitgitgadget@gmail.com","subject":"[PATCH 1/4] doc: convert git-imap-send synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-19T19:54:34Z","receivedAt":"2026-07-19T19:54:43Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\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 <jn.avila@free.fr>\n---\n Documentation/config/imap.adoc   | 2 +-\n Documentation/git-imap-send.adoc | 7 +++++--\n 2 files changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc\nindex cb8f5e2700..6b97776bc3 100644\n--- a/Documentation/config/imap.adoc\n+++ b/Documentation/config/imap.adoc\n@@ -41,7 +41,7 @@\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`\n+\tthan 7.34.0, or if you're running `git-imap-send` with the `--no-curl`\n \toption, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER`\n \tand `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP\n \tplaintext `LOGIN` command.\ndiff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc\nindex 538b91afc0..dd1e0a3718 100644\n--- a/Documentation/git-imap-send.adoc\n+++ b/Documentation/git-imap-send.adoc\n@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.\n \n Once the commits are ready to be sent, run the following command:\n \n-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n+\n+---------\n+$ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n+---------\n \n Just make sure to disable line wrapping in the email client (Gmail's web\n interface will wrap lines no matter what, so you need to use a real\n@@ -217,7 +220,7 @@ users may wish to visit this web page for more information:\n \n SEE ALSO\n --------\n-linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)\n+linkgit:git-format-patch[1], linkgit:git-send-email[1], `mbox`(5)\n \n GIT\n ---\n-- \ngitgitgadget\n\n"},{"id":"548635","messageId":"e1ed85e3f2733f0f1cc46416903d1e0c8b4c1856.1784490878.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.git.1784490878.gitgitgadget@gmail.com","subject":"[PATCH 2/4] doc: convert git-format-patch synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-19T19:54:35Z","receivedAt":"2026-07-19T19:54:44Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nReplace [verse] with [synopsis] in the SYNOPSIS block and remove\nsingle-quote formatting from the command name.\n\nBacktick-quote all option terms in the OPTIONS section, convert\nstandalone placeholders to _<placeholder>_ form, and convert\nsingle-quoted commands and tools in prose to backtick form.\n\nAlso update the included files:\n- diff-options.adoc: backtick-quote the git-format-patch-specific\n  option terms (-p, --no-stat, --max-depth=<depth>)\n- format-patch-caveats.adoc: convert patch(1) to `patch`(1)\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-options.adoc     |   8 +-\n Documentation/git-format-patch.adoc | 264 ++++++++++++++--------------\n 2 files changed, 136 insertions(+), 136 deletions(-)\n\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex c8242e2462..e605d28678 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -13,8 +13,8 @@ endif::git-diff[]\n endif::git-format-patch[]\n \n ifdef::git-format-patch[]\n--p::\n---no-stat::\n+`-p`::\n+`--no-stat`::\n \tGenerate plain patches without any diffstats.\n endif::git-format-patch[]\n \n@@ -893,8 +893,8 @@ endif::git-format-patch[]\n \treverted with `--ita-visible-in-index`. Both options are\n \texperimental and could be removed in future.\n \n---max-depth=<depth>::\n-\tFor each pathspec given on command line, descend at most `<depth>`\n+`--max-depth=<depth>`::\n+\tFor each pathspec given on command line, descend at most _<depth>_\n \tlevels of directories. A value of `-1` means no limit.\n \tCannot be combined with wildcards in the pathspec.\n \tGiven a tree containing `foo/bar/baz`, the following list shows the\ndiff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc\nindex f7905c0f7c..5eccb2cf60 100644\n--- a/Documentation/git-format-patch.adoc\n+++ b/Documentation/git-format-patch.adoc\n@@ -8,8 +8,8 @@ git-format-patch - Prepare patches for e-mail submission\n \n SYNOPSIS\n --------\n-[verse]\n-'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]\n+[synopsis]\n+git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]\n \t\t   [--no-thread | --thread[=<style>]]\n \t\t   [(--attach|--inline)[=<boundary>] | --no-attach]\n \t\t   [-s | --signoff]\n@@ -40,20 +40,20 @@ DESCRIPTION\n Prepare each non-merge commit with its \"patch\" in\n one \"message\" per commit, formatted to resemble a UNIX mailbox.\n The output of this command is convenient for e-mail submission or\n-for use with 'git am'.\n+for use with `git am`.\n \n A \"message\" generated by the command consists of three parts:\n \n * A brief metadata header that begins with `From <commit>`\n   with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs\n-  like \"file(1)\" to recognize that the file is an output from this\n+  like `file`(1) to recognize that the file is an output from this\n   command, fields that record the author identity, the author date,\n   and the title of the change (taken from the first paragraph of the\n   commit log message).\n \n * The second and subsequent paragraphs of the commit log message.\n \n-* The \"patch\", which is the \"diff -p --stat\" output (see\n+* The \"patch\", which is the `diff -p --stat` output (see\n   linkgit:git-diff[1]) between the commit and its parent.\n \n The log message and the patch are separated by a line with a\n@@ -61,18 +61,18 @@ three-dash line.\n \n There are two ways to specify which commits to operate on.\n \n-1. A single commit, <since>, specifies that the commits leading\n+1. A single commit, _<since>_, specifies that the commits leading\n    to the tip of the current branch that are not in the history\n-   that leads to the <since> to be output.\n+   that leads to the _<since>_ to be output.\n \n-2. Generic <revision-range> expression (see \"SPECIFYING\n-   REVISIONS\" section in linkgit:gitrevisions[7]) means the\n+2. Generic _<revision-range>_ expression (see 'SPECIFYING\n+   REVISIONS' section in linkgit:gitrevisions[7]) means the\n    commits in the specified range.\n \n-The first rule takes precedence in the case of a single <commit>.  To\n+The first rule takes precedence in the case of a single _<commit>_.  To\n apply the second rule, i.e., format everything since the beginning of\n-history up until <commit>, use the `--root` option: `git format-patch\n---root <commit>`.  If you want to format only <commit> itself, you\n+history up until _<commit>_, use the `--root` option: `git format-patch\n+--root <commit>`.  If you want to format only _<commit>_ itself, you\n can do this with `git format-patch -1 <commit>`.\n \n By default, each output file is numbered sequentially from 1, and uses the\n@@ -82,7 +82,7 @@ will only be numbers, without the first line of the commit appended.\n The names of the output files are printed to standard\n output, unless the `--stdout` option is specified.\n \n-If `-o` is specified, output files are created in <dir>.  Otherwise\n+If `-o` is specified, output files are created in _<dir>_.  Otherwise\n they are created in the current working directory. The default path\n can be set with the `format.outputDirectory` configuration option.\n The `-o` option takes precedence over `format.outputDirectory`.\n@@ -108,119 +108,119 @@ OPTIONS\n :git-format-patch: 1\n include::diff-options.adoc[]\n \n--<n>::\n-\tPrepare patches from the topmost <n> commits.\n+`-<n>`::\n+\tPrepare patches from the topmost _<n>_ commits.\n \n--o <dir>::\n---output-directory <dir>::\n-\tUse <dir> to store the resulting files, instead of the\n+`-o <dir>`::\n+`--output-directory=<dir>`::\n+\tUse _<dir>_ to store the resulting files, instead of the\n \tcurrent working directory.\n \n--n::\n---numbered::\n+`-n`::\n+`--numbered`::\n \tName output in '[PATCH n/m]' format, even with a single patch.\n \n--N::\n---no-numbered::\n+`-N`::\n+`--no-numbered`::\n \tName output in '[PATCH]' format.\n \n---start-number <n>::\n-\tStart numbering the patches at <n> instead of 1.\n+`--start-number <n>`::\n+\tStart numbering the patches at _<n>_ instead of 1.\n \n---numbered-files::\n+`--numbered-files`::\n \tOutput file names will be a simple number sequence\n \twithout the default first line of the commit appended.\n \n--k::\n---keep-subject::\n+`-k`::\n+`--keep-subject`::\n \tDo not strip/add '[PATCH]' from the first line of the\n \tcommit log message.\n \n--s::\n---signoff::\n+`-s`::\n+`--signoff`::\n \tAdd a `Signed-off-by` trailer to the commit message, using\n \tthe committer identity of yourself.\n \tSee the signoff option in linkgit:git-commit[1] for more information.\n \n---stdout::\n+`--stdout`::\n \tPrint all commits to the standard output in mbox format,\n \tinstead of creating a file for each one.\n \n---attach[=<boundary>]::\n+`--attach[=<boundary>]`::\n \tCreate multipart/mixed attachment, the first part of\n \twhich is the commit message and the patch itself in the\n \tsecond part, with `Content-Disposition: attachment`.\n \n---no-attach::\n+`--no-attach`::\n \tDisable the creation of an attachment, overriding the\n \tconfiguration setting.\n \n---inline[=<boundary>]::\n+`--inline[=<boundary>]`::\n \tCreate multipart/mixed attachment, the first part of\n \twhich is the commit message and the patch itself in the\n \tsecond part, with `Content-Disposition: inline`.\n \n---thread[=<style>]::\n---no-thread::\n-\tControls addition of `In-Reply-To` and `References` headers to\n+`--thread[=<style>]`::\n+`--no-thread`::\n+\tControl addition of `In-Reply-To` and `References` headers to\n \tmake the second and subsequent mails appear as replies to the\n \tfirst.  Also controls generation of the `Message-ID` header to\n \treference.\n +\n-The optional <style> argument can be either `shallow` or `deep`.\n-'shallow' threading makes every mail a reply to the head of the\n+The optional _<style>_ argument can be either `shallow` or `deep`.\n+`shallow` threading makes every mail a reply to the head of the\n series, where the head is chosen from the cover letter, the\n-`--in-reply-to`, and the first patch mail, in this order.  'deep'\n+`--in-reply-to`, and the first patch mail, in this order.  `deep`\n threading makes every mail a reply to the previous one.\n +\n The default is `--no-thread`, unless the `format.thread` configuration\n is set.  `--thread` without an argument is equivalent to `--thread=shallow`.\n +\n-Beware that the default for 'git send-email' is to thread emails\n+Beware that the default for `git send-email` is to thread emails\n itself.  If you want `git format-patch` to take care of threading, you\n will want to ensure that threading is disabled for `git send-email`.\n \n---in-reply-to=<message-id>::\n+`--in-reply-to=<message-id>`::\n \tMake the first mail (or all the mails with `--no-thread`) appear as a\n-\treply to the given <message-id>, which avoids breaking threads to\n+\treply to the given _<message-id>_, which avoids breaking threads to\n \tprovide a new patch series.\n \n---ignore-if-in-upstream::\n+`--ignore-if-in-upstream`::\n \tDo not include a patch that matches a commit in\n-\t<until>..<since>.  This will examine all patches reachable\n-\tfrom <since> but not from <until> and compare them with the\n+\t_<until>_.._<since>_.  This will examine all patches reachable\n+\tfrom _<since>_ but not from _<until>_ and compare them with the\n \tpatches being generated, and any patch that matches is\n \tignored.\n \n---always::\n+`--always`::\n \tInclude patches for commits that do not introduce any change,\n \twhich are omitted by default.\n \n---cover-from-description=<mode>::\n-\tControls which parts of the cover letter will be automatically\n+`--cover-from-description=<mode>`::\n+\tControl which parts of the cover letter will be automatically\n \tpopulated using the branch's description.\n +\n-If `<mode>` is `message` or `default`, the cover letter subject will be\n+_<mode>_ can have the following values:\n+\n+`message`;;\n+`default`;; the cover letter subject will be\n populated with placeholder text. The body of the cover letter will be\n populated with the branch's description. This is the default mode when\n no configuration nor command line option is specified.\n-+\n-If `<mode>` is `subject`, the first paragraph of the branch description will\n+`subject`;; the first paragraph of the branch description will\n populate the cover letter subject. The remainder of the description will\n populate the body of the cover letter.\n-+\n-If `<mode>` is `auto`, if the first paragraph of the branch description\n+`auto`;; if the first paragraph of the branch description\n is greater than 100 bytes, then the mode will be `message`, otherwise\n `subject` will be used.\n-+\n-If `<mode>` is `none`, both the cover letter subject and body will be\n+`none`;; both the cover letter subject and body will be\n populated with placeholder text.\n \n---description-file=<file>::\n-\tUse the contents of <file> instead of the branch's description\n+`--description-file=<file>`::\n+\tUse the contents of _<file>_ instead of the branch's description\n \tfor generating the cover letter.\n \n---subject-prefix=<subject-prefix>::\n+`--subject-prefix=<subject-prefix>`::\n \tUse '[<subject-prefix>]' instead of the standard '[PATCH]'\n \tprefix in the subject line. This can be used to name a patch\n \tseries, and can be combined with the `--numbered` option.\n@@ -231,14 +231,14 @@ all patches. This is often useful on mailing lists which receive\n patches for several repositories and can be used to disambiguate\n the patches (with a value of e.g. \"PATCH my-project\").\n \n---filename-max-length=<n>::\n+`--filename-max-length=<n>`::\n \tInstead of the standard 64 bytes, chomp the generated output\n-\tfilenames at around '<n>' bytes (too short a value will be\n+\tfilenames at around _<n>_ bytes (too short a value will be\n \tsilently raised to a reasonable length).  Defaults to the\n \tvalue of the `format.filenameMaxLength` configuration\n \tvariable, or 64 if unconfigured.\n \n---rfc[=<rfc>]::\n+`--rfc[=<rfc>]`::\n \tPrepends the string _<rfc>_ (defaults to \"RFC\") to\n \tthe subject prefix.  As the subject prefix defaults to\n \t\"PATCH\", you'll get \"RFC PATCH\" by default.\n@@ -254,38 +254,38 @@ can be prefixed with a dash (\"`-`\") to signal that the rest of\n the _<rfc>_ string should be appended to the subject prefix instead,\n e.g., `--rfc='-(WIP)'` results in \"PATCH (WIP)\".\n \n--v <n>::\n---reroll-count=<n>::\n-\tMark the series as the <n>-th iteration of the topic. The\n+`-v <n>`::\n+`--reroll-count=<n>`::\n+\tMark the series as the _<n>_-th iteration of the topic. The\n \toutput filenames have `v<n>` prepended to them, and the\n \tsubject prefix (\"PATCH\" by default, but configurable via the\n-\t`--subject-prefix` option) has ` v<n>` appended to it.  E.g.\n+\t`--subject-prefix` option) has `v<n>` appended to it.  E.g.\n \t`--reroll-count=4` may produce `v4-0001-add-makefile.patch`\n \tfile that has \"Subject: [PATCH v4 1/20] Add makefile\" in it.\n-\t`<n>` does not have to be an integer (e.g. \"--reroll-count=4.4\",\n-\tor \"--reroll-count=4rev2\" are allowed), but the downside of\n+\t_<n>_ does not have to be an integer (e.g. `--reroll-count=4.4`,\n+\tor `--reroll-count=4rev2` are allowed), but the downside of\n \tusing such a reroll-count is that the range-diff/interdiff\n \twith the previous version does not state exactly which\n \tversion the new iteration is compared against.\n \n---to=<email>::\n+`--to=<email>`::\n \tAdd a `To:` header to the email headers. This is in addition\n \tto any configured headers, and may be used multiple times.\n \tThe negated form `--no-to` discards all `To:` headers added so\n \tfar (from config or command line).\n \n---cc=<email>::\n+`--cc=<email>`::\n \tAdd a `Cc:` header to the email headers. This is in addition\n \tto any configured headers, and may be used multiple times.\n \tThe negated form `--no-cc` discards all `Cc:` headers added so\n \tfar (from config or command line).\n \n---from::\n---from=<ident>::\n-\tUse `ident` in the `From:` header of each email. In case of a\n+`--from`::\n+`--from=<ident>`::\n+\tUse _<ident>_ in the `From:` header of each email. In case of a\n \tcommit email, if the author ident of the commit is not textually\n-\tidentical to the provided `ident`, place a `From:` header in the\n-\tbody of the message with the original author. If no `ident` is\n+\tidentical to the provided _<ident>_, place a `From:` header in the\n+\tbody of the message with the original author. If no _<ident>_ is\n \tgiven, or if the option is not passed at all, use the ident of\n \tthe current committer.\n +\n@@ -296,8 +296,8 @@ header). Note also that `git send-email` already handles this\n transformation for you, and this option should not be used if you are\n feeding the result to `git send-email`.\n \n---force-in-body-from::\n---no-force-in-body-from::\n+`--force-in-body-from`::\n+`--no-force-in-body-from`::\n \tWith the e-mail sender specified via the `--from` option, by\n \tdefault, an in-body \"From:\" to identify the real author of\n \tthe commit is added at the top of the commit log message if\n@@ -308,7 +308,7 @@ feeding the result to `git send-email`.\n \tDefaults to the value of the `format.forceInBodyFrom`\n \tconfiguration variable.\n \n---add-header=<header>::\n+`--add-header=<header>`::\n \tAdd an arbitrary header to the email headers.  This is in addition\n \tto any configured headers, and may be used multiple times.\n \tFor example, `--add-header=\"Organization: git-foo\"`.\n@@ -316,13 +316,13 @@ feeding the result to `git send-email`.\n \t`Cc:`, and custom) headers added so far from config or command\n \tline.\n \n---cover-letter::\n---no-cover-letter::\n+`--cover-letter`::\n+`--no-cover-letter`::\n \tIn addition to the patches, generate a cover letter file containing the\n \tbranch description, commit list and the overall diffstat.  You can fill\n \tin a description in the file before sending it out.\n \n---commit-list-format=<format-spec>::\n+`--commit-list-format=<format-spec>`::\n \tSpecify the format in which to generate the commit list of the patch\n \tseries. The accepted values for format-spec are `shortlog`, `modern` or\n \ta format-string prefixed with `log:`. E.g. `log: %s (%an)`.\n@@ -334,28 +334,28 @@ feeding the result to `git send-email`.\n \tThis option given from the command-line implies the use of\n \t`--cover-letter` unless `--no-cover-letter` is given.\n \n---encode-email-headers::\n---no-encode-email-headers::\n+`--encode-email-headers`::\n+`--no-encode-email-headers`::\n \tEncode email headers that have non-ASCII characters with\n \t\"Q-encoding\" (described in RFC 2047), instead of outputting the\n \theaders verbatim. Defaults to the value of the\n \t`format.encodeEmailHeaders` configuration variable.\n \n---interdiff=<previous>::\n+`--interdiff=<previous>`::\n \tAs a reviewer aid, insert an interdiff into the cover letter,\n \tor as commentary of the lone patch of a 1-patch series, showing\n \tthe differences between the previous version of the patch series and\n-\tthe series currently being formatted. `previous` is a single revision\n+\tthe series currently being formatted. _<previous>_ is a single revision\n \tnaming the tip of the previous series which shares a common base with\n \tthe series being formatted (for example `git format-patch\n \t--cover-letter --interdiff=feature/v1 -3 feature/v2`).\n \n---range-diff=<previous>::\n+`--range-diff=<previous>`::\n \tAs a reviewer aid, insert a range-diff (see linkgit:git-range-diff[1])\n \tinto the cover letter, or as commentary of the lone patch of a\n \t1-patch series, showing the differences between the previous\n \tversion of the patch series and the series currently being formatted.\n-\t`previous` can be a single revision naming the tip of the previous\n+\t_<previous>_ can be a single revision naming the tip of the previous\n \tseries if it shares a common base with the series being formatted (for\n \texample `git format-patch --cover-letter --range-diff=feature/v1 -3\n \tfeature/v2`), or a revision range if the two versions of the series are\n@@ -367,7 +367,7 @@ product of `format-patch` is generated, and they are not passed to\n the underlying `range-diff` machinery used to generate the cover-letter\n material (this may change in the future).\n \n---creation-factor=<percent>::\n+`--creation-factor=<percent>`::\n \tUsed with `--range-diff`, tweak the heuristic which matches up commits\n \tbetween the previous and current series of patches by adjusting the\n \tcreation/deletion cost fudge factor. See linkgit:git-range-diff[1])\n@@ -378,8 +378,8 @@ case is to show comparison with an older iteration of the same\n topic and the tool should find more correspondence between the two\n sets of patches.\n \n---notes[=<ref>]::\n---no-notes::\n+`--notes[=<ref>]`::\n+`--no-notes`::\n \tAppend the notes (see linkgit:git-notes[1]) for the commit\n \tafter the three-dash line.\n +\n@@ -394,17 +394,17 @@ configuration options in linkgit:git-notes[1] to use this workflow).\n The default is `--no-notes`, unless the `format.notes` configuration is\n set.\n \n---signature=<signature>::\n---no-signature::\n+`--signature=<signature>`::\n+`--no-signature`::\n \tAdd a signature to each message produced. Per RFC 3676 the signature\n-\tis separated from the body by a line with '-- ' on it. If the\n+\tis separated from the body by a line with \"-- \" on it. If the\n \tsignature option is omitted the signature defaults to the Git version\n \tnumber.\n \n---signature-file=<file>::\n-\tWorks just like --signature except the signature is read from a file.\n+`--signature-file=<file>`::\n+\tWorks just like `--signature` except the signature is read from a file.\n \n---suffix=.<sfx>::\n+`--suffix=.<sfx>`::\n \tInstead of using `.patch` as the suffix for generated\n \tfilenames, use specified suffix.  A common alternative is\n \t`--suffix=.txt`.  Leaving this empty will remove the `.patch`\n@@ -413,36 +413,36 @@ set.\n Note that the leading character does not have to be a dot; for example,\n you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tDo not print the names of the generated files to standard output.\n \n---no-binary::\n+`--no-binary`::\n \tDo not output contents of changes in binary files, instead\n \tdisplay a notice that those files changed.  Patches generated\n \tusing this option cannot be applied properly, but they are\n \tstill useful for code review.\n \n---zero-commit::\n+`--zero-commit`::\n   Output an all-zero hash in each patch's From header instead\n   of the hash of the commit.\n \n---no-base::\n---base[=<commit>]::\n+`--no-base`::\n+`--base[=<commit>]`::\n \tRecord the base tree information to identify the state the\n \tpatch series applies to.  See the BASE TREE INFORMATION section\n-\tbelow for details. If <commit> is \"auto\", a base commit is\n+\tbelow for details. If _<commit>_ is `auto`, a base commit is\n \tautomatically chosen. The `--no-base` option overrides a\n \t`format.useAutoBase` configuration.\n \n---root::\n-\tTreat the revision argument as a <revision-range>, even if it\n+`--root`::\n+\tTreat the revision argument as a _<revision-range>_, even if it\n \tis just a single commit (that would normally be treated as a\n-\t<since>).  Note that root commits included in the specified\n+\t_<since>_).  Note that root commits included in the specified\n \trange are always formatted as creation patches, independently\n \tof this flag.\n \n---progress::\n+`--progress`::\n \tShow progress reports on stderr as patches are generated.\n \n CONFIGURATION\n@@ -473,7 +473,7 @@ with configuration variables.\n DISCUSSION\n ----------\n \n-The patch produced by 'git format-patch' is in UNIX mailbox format,\n+The patch produced by `git format-patch` is in UNIX mailbox format,\n with a fixed \"magic\" time stamp to indicate that the file is output\n from format-patch rather than a real mailbox, like so:\n \n@@ -502,8 +502,8 @@ can save interesting patches in a UNIX mailbox and apply them with\n linkgit:git-am[1].\n \n When a patch is part of an ongoing discussion, the patch generated by\n-'git format-patch' can be tweaked to take advantage of the 'git am\n---scissors' feature.  After your response to the discussion comes a\n+`git format-patch` can be tweaked to take advantage of the `git am\n+--scissors` feature.  After your response to the discussion comes a\n line that consists solely of \"`-- >8 --`\" (scissors and perforation),\n followed by the patch with unnecessary header fields removed:\n \n@@ -540,7 +540,7 @@ two common types of corruption:\n One way to test if your MUA is set up correctly is:\n \n * Send the patch to yourself, exactly the way you would, except\n-  with To: and Cc: lines that do not contain the list and\n+  with `To:` and `Cc:` lines that do not contain the list and\n   maintainer address.\n \n * Save that patch to a file in UNIX mailbox format.  Call it a.patch,\n@@ -561,12 +561,12 @@ If it does not apply correctly, there can be various reasons.\n   this case.\n \n * The MUA corrupted your patch; \"am\" would complain that\n-  the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and\n-  see what 'patch' file contains and check for the common\n-  corruption patterns mentioned above.\n+  the patch does not apply.  Look in the `.git/rebase-apply/` subdirectory and\n+   see what `patch` file contains and check for the common\n+   corruption patterns mentioned above.\n \n-* While at it, check the 'info' and 'final-commit' files as well.\n-  If what is in 'final-commit' is not exactly what you would want to\n+* While at it, check the `info` and `final-commit` files as well.\n+  If what is in `final-commit` is not exactly what you would want to\n   see in the commit log message, it is very likely that the\n   receiver would end up hand editing the log message when applying\n   your patch.  Things like \"Hi, this is my first patch.\\n\" in the\n@@ -582,11 +582,11 @@ GMail\n ~~~~~\n GMail does not have any way to turn off line wrapping in the web\n interface, so it will mangle any emails that you send.  You can however\n-use \"git send-email\" and send your patches through the GMail SMTP server, or\n+use `git send-email` and send your patches through the GMail SMTP server, or\n use any IMAP email client to connect to the google IMAP server and forward\n the emails through that.\n \n-For hints on using 'git send-email' to send your patches through the\n+For hints on using `git send-email` to send your patches through the\n GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1].\n \n For hints on submission using the IMAP interface, see the EXAMPLE\n@@ -595,7 +595,7 @@ section of linkgit:git-imap-send[1].\n Thunderbird\n ~~~~~~~~~~~\n By default, Thunderbird will both wrap emails as well as flag\n-them as being 'format=flowed', both of which will make the\n+them as being `format=flowed`, both of which will make the\n resulting email unusable by Git.\n \n There are three different approaches: use an add-on to turn off line wraps,\n@@ -609,14 +609,14 @@ Install the Toggle Line Wrap add-on that is available from\n https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap\n It adds a button \"Line Wrap\" to the composer's toolbar\n that you can tick off. Now you can compose the message as you otherwise do\n-(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to\n+(cut + paste, `git format-patch` | `git imap-send`, etc), but you have to\n insert line breaks manually in any text that you type.\n \n As a bonus feature, the add-on can detect patch text in the composer\n and warns when line wrapping has not yet been turned off.\n \n The add-on requires a few tweaks of the advanced configuration\n-(about:config). These are listed on the download page.\n+(`about:config`). These are listed on the download page.\n \n Approach #2 (configuration)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^\n@@ -643,7 +643,7 @@ Toggle it to make sure it is set to `false`. Also, search for\n    Toggle it to make sure it is set to `false`.\n \n After that is done, you should be able to compose email as you\n-otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc),\n+otherwise would (cut + paste, `git format-patch` | `git imap-send`, etc),\n and the patches will not be mangled.\n \n Approach #3 (external editor)\n@@ -660,7 +660,7 @@ External Editor from https://globs.org/articles.php?lng=en&pg=8\n    \"Composition & Addressing\" panel of the account to be used to\n    send the patch.\n \n-3. In the main Thunderbird window, 'before' you open the compose\n+3. In the main Thunderbird window, _before_ you open the compose\n    window for the patch, use Tools->about:config to set the\n    following to the indicated values:\n +\n@@ -708,15 +708,15 @@ BASE TREE INFORMATION\n \n The base tree information block is used for maintainers or third party\n testers to know the exact state the patch series applies to. It consists\n-of the 'base commit', which is a well-known commit that is part of the\n+of the \"base commit\", which is a well-known commit that is part of the\n stable part of the project history everybody else works off of, and zero\n-or more 'prerequisite patches', which are well-known patches in flight\n-that is not yet part of the 'base commit' that need to be applied on top\n-of 'base commit' in topological order before the patches can be applied.\n+or more \"prerequisite patches\", which are well-known patches in flight\n+that is not yet part of the \"base commit\" that need to be applied on top\n+of \"base commit\" in topological order before the patches can be applied.\n \n-The 'base commit' is shown as \"base-commit: \" followed by the 40-hex of\n-the commit object name.  A 'prerequisite patch' is shown as\n-\"prerequisite-patch-id: \" followed by the 40-hex 'patch id', which can\n+The \"base commit\" is shown as \"base-commit: \" followed by the 40-hex of\n+the commit object name.  A `prerequisite patch` is shown as\n+\"prerequisite-patch-id: \" followed by the 40-hex `patch id`, which can\n be obtained by passing the patch through the `git patch-id --stable`\n command.\n \n@@ -763,7 +763,7 @@ EXAMPLES\n --------\n \n * Extract commits between revisions R1 and R2, and apply them on top of\n-  the current branch using 'git am' to cherry-pick them:\n+  the current branch using `git am` to cherry-pick them:\n +\n ------------\n $ git format-patch -k --stdout R1..R2 | git am -3 -k\n@@ -778,7 +778,7 @@ $ git format-patch origin\n +\n For each commit a separate file is created in the current directory.\n \n-* Extract all commits that lead to 'origin' since the inception of the\n+* Extract all commits that lead to `origin` since the inception of the\n   project:\n +\n ------------\n@@ -794,7 +794,7 @@ $ git format-patch -M -B origin\n Additionally, it detects and handles renames and complete rewrites\n intelligently to produce a renaming patch.  A renaming patch reduces\n the amount of text output, and generally makes it easier to review.\n-Note that non-Git \"patch\" programs won't understand renaming patches, so\n+Note that non-Git `patch` programs won't understand renaming patches, so\n use it only when you know the recipient uses Git to apply your patch.\n \n * Extract three topmost commits from the current branch and format them\n-- \ngitgitgadget\n\n"},{"id":"548636","messageId":"723450c5a0dbbb46ad8ec7cacc59262f6ad760fa.1784490878.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.git.1784490878.gitgitgadget@gmail.com","subject":"[PATCH 3/4] doc: convert git-send-email synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-19T19:54:36Z","receivedAt":"2026-07-19T19:54:45Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nReplace [verse] with [synopsis] in the SYNOPSIS block and remove\nsingle-quote formatting from the command name.\n\nBacktick-quote all option terms in the OPTIONS section, convert\nthe standalone placeholder _<encoding>_ in prose, fix single-quoted\nserver names to backtick form, and convert mbox(5) to `mbox`(5).\n\nAlso update config/sendemail.adoc: backtick-quote all configuration\nkey terms and fix a bare sendemail.aliasesFile reference in prose.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/sendemail.adoc |  92 ++++++++--------\n Documentation/git-send-email.adoc   | 162 ++++++++++++++--------------\n 2 files changed, 127 insertions(+), 127 deletions(-)\n\ndiff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc\nindex 1d700559b4..5499f91036 100644\n--- a/Documentation/config/sendemail.adoc\n+++ b/Documentation/config/sendemail.adoc\n@@ -1,25 +1,25 @@\n-sendemail.identity::\n+`sendemail.identity`::\n \tA configuration identity. When given, causes values in the\n \t`sendemail.<identity>` subsection to take precedence over\n \tvalues in the `sendemail` section. The default identity is\n \tthe value of `sendemail.identity`.\n \n-sendemail.smtpEncryption::\n+`sendemail.smtpEncryption`::\n \tSee linkgit:git-send-email[1] for description.  Note that this\n \tsetting is not subject to the `identity` mechanism.\n \n-sendemail.smtpSSLCertPath::\n+`sendemail.smtpSSLCertPath`::\n \tPath to ca-certificates (either a directory or a single file).\n \tSet it to an empty string to disable certificate verification.\n \n-sendemail.smtpSSLClientCert::\n+`sendemail.smtpSSLClientCert`::\n \tPath to the client certificate file to present if requested by the\n \tserver. This is required when the server is set up to verify client\n \tcertificates. If the corresponding private key is not included in the\n \tfile, it must be supplied using `sendemail.smtpSSLClientKey` or the\n \t`--smtp-ssl-client-key` option.\n \n-sendemail.smtpSSLClientKey::\n+`sendemail.smtpSSLClientKey`::\n \tPath to the client private key file that corresponds to the client\n \tcertificate. To avoid misconfiguration, this configuration must be used\n \tin conjunction with `sendemail.smtpSSLClientCert` or the\n@@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey::\n \tthe certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more\n \tdetails.\n \n-sendemail.<identity>.*::\n-\tIdentity-specific versions of the `sendemail.*` parameters\n+`sendemail.<identity>.<config>`::\n+\tIdentity-specific versions of the `sendemail.<config>` parameters\n \tfound below, taking precedence over those when this\n \tidentity is selected, through either the command-line or\n \t`sendemail.identity`.\n \n-sendemail.multiEdit::\n+`sendemail.multiEdit`::\n \tIf `true` (default), a single editor instance will be spawned to edit\n \tfiles you have to edit (patches when `--annotate` is used, and the\n \tsummary when `--compose` is used). If `false`, files will be edited one\n \tafter the other, spawning a new editor each time.\n \n-sendemail.confirm::\n+`sendemail.confirm`::\n \tSets the default for whether to confirm before sending. Must be\n \tone of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm`\n \tin the linkgit:git-send-email[1] documentation for the meaning of these\n \tvalues.\n \n-sendemail.mailmap::\n+`sendemail.mailmap`::\n \tIf `true`, makes linkgit:git-send-email[1] assume `--mailmap`,\n \totherwise assume `--no-mailmap`. `False` by default.\n \n-sendemail.mailmap.file::\n+`sendemail.mailmap.file`::\n \tThe location of a linkgit:git-send-email[1] specific augmenting\n \tmailmap file. The default mailmap and `mailmap.file` are loaded\n \tfirst. Thus, entries in this file take precedence over entries in\n \tthe default mailmap locations. See linkgit:gitmailmap[5].\n \n-sendemail.mailmap.blob::\n+`sendemail.mailmap.blob`::\n \tLike `sendemail.mailmap.file`, but consider the value as a reference\n \tto a blob in the repository. Entries in `sendemail.mailmap.file`\n \ttake precedence over entries here. See linkgit:gitmailmap[5].\n \n-sendemail.aliasesFile::\n+`sendemail.aliasesFile`::\n \tTo avoid typing long email addresses, point this to one or more\n \temail aliases files.  You must also supply `sendemail.aliasFileType`.\n \n-sendemail.aliasFileType::\n-\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n+`sendemail.aliasFileType`::\n+\tFormat of the file(s) specified in `sendemail.aliasesFile`. Must be\n \tone of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`.\n +\n What an alias file in each format looks like can be found in\n@@ -75,7 +75,7 @@ differences and limitations from the standard formats are\n described below:\n +\n --\n-sendmail;;\n+`sendmail`;;\n *\tQuoted aliases and quoted addresses are not supported: lines that\n \tcontain a `\"` symbol are ignored.\n *\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n@@ -85,54 +85,54 @@ sendmail;;\n \texplicitly unsupported constructs, and any other lines that are not\n \trecognized by the parser.\n --\n-sendemail.annotate::\n-sendemail.bcc::\n-sendemail.cc::\n-sendemail.ccCmd::\n-sendemail.chainReplyTo::\n-sendemail.envelopeSender::\n-sendemail.from::\n-sendemail.headerCmd::\n-sendemail.signedOffByCc::\n-sendemail.smtpPass::\n-sendemail.suppressCc::\n-sendemail.suppressFrom::\n-sendemail.to::\n-sendemail.toCmd::\n-sendemail.smtpDomain::\n-sendemail.smtpServer::\n-sendemail.smtpServerPort::\n-sendemail.smtpServerOption::\n-sendemail.smtpUser::\n-sendemail.imapSentFolder::\n-sendemail.useImapOnly::\n-sendemail.thread::\n-sendemail.transferEncoding::\n-sendemail.validate::\n-sendemail.xmailer::\n+`sendemail.annotate`::\n+`sendemail.bcc`::\n+`sendemail.cc`::\n+`sendemail.ccCmd`::\n+`sendemail.chainReplyTo`::\n+`sendemail.envelopeSender`::\n+`sendemail.from`::\n+`sendemail.headerCmd`::\n+`sendemail.signedOffByCc`::\n+`sendemail.smtpPass`::\n+`sendemail.suppressCc`::\n+`sendemail.suppressFrom`::\n+`sendemail.to`::\n+`sendemail.toCmd`::\n+`sendemail.smtpDomain`::\n+`sendemail.smtpServer`::\n+`sendemail.smtpServerPort`::\n+`sendemail.smtpServerOption`::\n+`sendemail.smtpUser`::\n+`sendemail.imapSentFolder`::\n+`sendemail.useImapOnly`::\n+`sendemail.thread`::\n+`sendemail.transferEncoding`::\n+`sendemail.validate`::\n+`sendemail.xmailer`::\n \tThese configuration variables all provide a default for\n \tlinkgit:git-send-email[1] command-line options. See its\n \tdocumentation for details.\n \n-sendemail.outlookidfix::\n+`sendemail.outlookidfix`::\n \tIf `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`,\n \tand if `false` assume `--no-outlook-id-fix`. If not specified, it will\n \tbehave the same way as if `--outlook-id-fix` is not specified.\n \n-sendemail.signedOffCc (deprecated)::\n+`sendemail.signedOffCc` (deprecated)::\n \tDeprecated alias for `sendemail.signedOffByCc`.\n \n-sendemail.smtpBatchSize::\n+`sendemail.smtpBatchSize`::\n \tNumber of messages to be sent per connection, after that a relogin\n \twill happen.  If the value is `0` or undefined, send all messages in\n \tone connection.\n \tSee also the `--batch-size` option of linkgit:git-send-email[1].\n \n-sendemail.smtpReloginDelay::\n+`sendemail.smtpReloginDelay`::\n \tSeconds to wait before reconnecting to the smtp server.\n \tSee also the `--relogin-delay` option of linkgit:git-send-email[1].\n \n-sendemail.forbidSendmailVariables::\n+`sendemail.forbidSendmailVariables`::\n \tTo avoid common misconfiguration mistakes, linkgit:git-send-email[1]\n \twill abort with a warning if any configuration options for `sendmail`\n \texist. Set this variable to bypass the check.\ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex dea3b86460..5c9ab39944 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -8,11 +8,11 @@ git-send-email - Send a collection of patches as emails\n \n SYNOPSIS\n --------\n-[verse]\n-'git send-email' [<options>] (<file>|<directory>)...\n-'git send-email' [<options>] <format-patch-options>\n-'git send-email' --dump-aliases\n-'git send-email' --translate-aliases\n+[synopsis]\n+git send-email [<options>] (<file>|<directory>)...\n+git send-email [<options>] <format-patch-options>\n+git send-email --dump-aliases\n+git send-email --translate-aliases\n \n \n DESCRIPTION\n@@ -48,24 +48,24 @@ OPTIONS\n Composing\n ~~~~~~~~~\n \n---annotate::\n+`--annotate`::\n \tReview and edit each patch you're about to send. Default is the value\n \tof `sendemail.annotate`. See the CONFIGURATION section for\n \t`sendemail.multiEdit`.\n \n---bcc=<address>,...::\n+`--bcc=<address>,...`::\n \tSpecify a `Bcc:` value for each email. Default is the value of\n \t`sendemail.bcc`.\n +\n This option may be specified multiple times.\n \n---cc=<address>,...::\n+`--cc=<address>,...`::\n \tSpecify a starting `Cc:` value for each email.\n \tDefault is the value of `sendemail.cc`.\n +\n This option may be specified multiple times.\n \n---compose::\n+`--compose`::\n \tInvoke a text editor (see GIT_EDITOR in linkgit:git-var[1])\n \tto edit an introductory message for the patch series.\n +\n@@ -80,7 +80,7 @@ Missing `From` or `In-Reply-To` headers will be prompted for.\n +\n See the CONFIGURATION section for `sendemail.multiEdit`.\n \n---from=<address>::\n+`--from=<address>`::\n \tSpecify the sender of the emails.  If not specified on the command line,\n \tthe value of the `sendemail.from` configuration option is used.  If\n \tneither the command-line option nor `sendemail.from` are set, then the\n@@ -88,12 +88,12 @@ See the CONFIGURATION section for `sendemail.multiEdit`.\n \tthe value of `GIT_AUTHOR_IDENT`, or `GIT_COMMITTER_IDENT` if that is not\n \tset, as returned by `git var -l`.\n \n---reply-to=<address>::\n+`--reply-to=<address>`::\n \tSpecify the address where replies from recipients should go to.\n \tUse this if replies to messages should go to another address than what\n \tis specified with the `--from` parameter.\n \n---in-reply-to=<identifier>::\n+`--in-reply-to=<identifier>`::\n \tMake the first mail (or all the mails with `--no-thread`) appear as a\n \treply to the given Message-ID, which avoids breaking threads to\n \tprovide a new patch series.\n@@ -115,8 +115,8 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:\n Only necessary if `--compose` is also set.  If `--compose`\n is not set, this will be prompted for.\n \n---outlook-id-fix::\n---no-outlook-id-fix::\n+`--outlook-id-fix`::\n+`--no-outlook-id-fix`::\n \tMicrosoft Outlook SMTP servers discard the Message-ID sent via email and\n \tassign a new random Message-ID, thus breaking threads.\n +\n@@ -126,15 +126,15 @@ threading. Use it only when you know that the server reports the\n rewritten Message-ID the same way as Outlook servers do.\n +\n Without this option specified, the fix is done by default when talking\n-to 'smtp.office365.com' or 'smtp-mail.outlook.com'. Use\n+to `smtp.office365.com` or `smtp-mail.outlook.com`. Use\n `--no-outlook-id-fix` to disable even when talking to these two servers.\n \n---subject=<string>::\n+`--subject=<string>`::\n \tSpecify the initial subject of the email thread.\n \tOnly necessary if `--compose` is also set.  If `--compose`\n \tis not set, this will be prompted for.\n \n---to=<address>,...::\n+`--to=<address>,...`::\n \tSpecify the primary recipient of the emails generated. Generally, this\n \twill be the upstream maintainer of the project involved. Default is the\n \tvalue of the `sendemail.to` configuration value; if that is unspecified,\n@@ -142,20 +142,20 @@ to 'smtp.office365.com' or 'smtp-mail.outlook.com'. Use\n +\n This option may be specified multiple times.\n \n---8bit-encoding=<encoding>::\n+`--8bit-encoding=<encoding>`::\n \tWhen encountering a non-ASCII message or subject that does not\n \tdeclare its encoding, add headers/quoting to indicate it is\n-\tencoded in <encoding>.  Default is the value of the\n+\tencoded in _<encoding>_.  Default is the value of the\n \t`sendemail.assume8bitEncoding`; if that is unspecified, this\n \twill be prompted for if any non-ASCII files are encountered.\n +\n Note that no attempts whatsoever are made to validate the encoding.\n \n---compose-encoding=<encoding>::\n+`--compose-encoding=<encoding>`::\n \tSpecify encoding of compose message. Default is the value of the\n \t`sendemail.composeEncoding`; if that is unspecified, UTF-8 is assumed.\n \n---transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::\n+`--transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)`::\n \tSpecify the transfer encoding to be used to send the message over SMTP.\n \t`7bit` will fail upon encountering a non-ASCII message. `quoted-printable`\n \tcan be useful when the repository contains files that contain carriage\n@@ -167,8 +167,8 @@ Note that no attempts whatsoever are made to validate the encoding.\n Default is the value of the `sendemail.transferEncoding` configuration\n value; if that is unspecified, default to `auto`.\n \n---xmailer::\n---no-xmailer::\n+`--xmailer`::\n+`--no-xmailer`::\n \tAdd (or prevent adding) the `X-Mailer:` header.  By default,\n \tthe header is added, but it can be turned off by setting the\n \t`sendemail.xmailer` configuration variable to `false`.\n@@ -176,7 +176,7 @@ value; if that is unspecified, default to `auto`.\n Sending\n ~~~~~~~\n \n---envelope-sender=<address>::\n+`--envelope-sender=<address>`::\n \tSpecify the envelope sender used to send the emails.\n \tThis is useful if your default address is not the address that is\n \tsubscribed to a list. In order to use the `From` address, set the\n@@ -185,7 +185,7 @@ Sending\n \t`sendemail.envelopeSender` configuration variable; if that is\n \tunspecified, choosing the envelope sender is left to your MTA.\n \n---sendmail-cmd=<command>::\n+`--sendmail-cmd=<command>`::\n \tSpecify a command to run to send the email. The command should\n \tbe sendmail-like; specifically, it must support the `-i` option.\n \tThe command will be executed in the shell if necessary.  Default\n@@ -193,7 +193,7 @@ Sending\n \t`--smtp-server` is also unspecified, `git send-email` will search\n \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH`.\n \n---smtp-encryption=<encryption>::\n+`--smtp-encryption=<encryption>`::\n \tSpecify in what way encrypting begins for the SMTP connection.\n \tValid values are `ssl` and `tls`. Any other value reverts to plain\n \t(unencrypted) SMTP, which defaults to port 25.\n@@ -207,14 +207,14 @@ Sending\n \tdocumentation or your server configuration to make sure\n \tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n \n---smtp-domain=<FQDN>::\n+`--smtp-domain=<FQDN>`::\n \tSpecify the Fully Qualified Domain Name (FQDN) used in the\n \tHELO/EHLO command to the SMTP server.  Some servers require the\n \tFQDN to match your IP address.  If not set, `git send-email` attempts\n \tto determine your FQDN automatically.  Default is the value of\n \t`sendemail.smtpDomain`.\n \n---smtp-auth=<mechanisms>::\n+`--smtp-auth=<mechanisms>`::\n \tWhitespace-separated list of allowed SMTP-AUTH mechanisms. This setting\n \tforces using only the listed mechanisms. Example:\n +\n@@ -229,7 +229,7 @@ is specified, all mechanisms supported by the SASL library can be used. The\n special value `none` maybe specified to completely disable authentication\n independently of `--smtp-user`.\n \n---smtp-pass[=<password>]::\n+`--smtp-pass[=<password>]`::\n \tPassword for SMTP-AUTH. The argument is optional: If no\n \targument is specified, then the empty string is used as\n \tthe password. Default is the value of `sendemail.smtpPass`,\n@@ -241,10 +241,10 @@ or on the command line. If a username has been specified (with\n specified (with `--smtp-pass` or `sendemail.smtpPass`), then\n a password is obtained using linkgit:git-credential[1].\n \n---no-smtp-auth::\n+`--no-smtp-auth`::\n \tDisable SMTP authentication. Short hand for `--smtp-auth=none`.\n \n---smtp-server=<host>::\n+`--smtp-server=<host>`::\n \tSpecify the outgoing SMTP server to use (e.g.\n \t`smtp.example.com` or a raw IP address).  If unspecified, and if\n \t`--sendmail-cmd` is also unspecified, the default is to search\n@@ -257,7 +257,7 @@ option.  This method does not support passing arguments or using plain\n command names.  For those use cases, consider using `--sendmail-cmd`\n instead.\n \n---smtp-server-port=<port>::\n+`--smtp-server-port=<port>`::\n \tSpecify a port different from the default port (SMTP\n \tservers typically listen to smtp port 25, but may also listen to\n \tsubmission port 587, or the common SSL smtp port 465);\n@@ -265,7 +265,7 @@ instead.\n \tare also accepted. The port can also be set with the\n \t`sendemail.smtpServerPort` configuration variable.\n \n---smtp-server-option=<option>::\n+`--smtp-server-option=<option>`::\n \tSpecify the outgoing SMTP server option to use.\n \tDefault value can be specified by the `sendemail.smtpServerOption`\n \tconfiguration option.\n@@ -274,15 +274,15 @@ The `--smtp-server-option` option must be repeated for each option you want\n to pass to the server. Likewise, different lines in the configuration files\n must be used for each option.\n \n---smtp-ssl::\n+`--smtp-ssl`::\n \tLegacy alias for `--smtp-encryption ssl`.\n \n---smtp-ssl-cert-path <path>::\n+`--smtp-ssl-cert-path <path>`::\n \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n \tcertificate validation (either a directory that has been processed\n \tby `c_rehash`, or a single file containing one or more PEM format\n \tcertificates concatenated together: see the description of the\n-\t`-CAfile` _<file>_ and the `-CApath` _<dir>_ options of\n+\t`-CAfile <file>` and the `-CApath <dir>` options of\n \thttps://docs.openssl.org/master/man1/openssl-verify/\n \t[OpenSSL's verify(1) manual page] for more information on these).\n \tSet it to an empty string to disable certificate verification.\n@@ -290,7 +290,7 @@ must be used for each option.\n \tvariable, if set, or the backing SSL library's compiled-in default\n \totherwise (which should be the best choice on most platforms).\n \n---smtp-ssl-client-cert <path>::\n+`--smtp-ssl-client-cert <path>`::\n \tPath to the client certificate file to present if requested by the\n \tserver. This option is required when the server is set up to verify\n \tclient certificates. If the corresponding private key is not included in\n@@ -299,7 +299,7 @@ must be used for each option.\n \tto the value of the `sendemail.smtpSSLClientCert` configuration\n \tvariable, if set.\n \n---smtp-ssl-client-key <path>::\n+`--smtp-ssl-client-key <path>`::\n \tPath to the client private key file that corresponds to the client\n \tcertificate. To avoid misconfiguration, this option must be used in\n \tconjunction with the `sendemail.smtpSSLClientKey` configuration variable\n@@ -309,17 +309,17 @@ must be used for each option.\n \tmore details. Defaults to the value of the `sendemail.smtpSSLClientKey`\n \tconfiguration variable, if set.\n \n---smtp-user=<user>::\n+`--smtp-user=<user>`::\n \tUsername for SMTP-AUTH. Default is the value of `sendemail.smtpUser`;\n \tif a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),\n \tthen authentication is not attempted.\n \n---smtp-debug=(0|1)::\n+`--smtp-debug=(0|1)`::\n \tEnable (1) or disable (0) debug output. If enabled, SMTP\n \tcommands and replies will be printed. Useful to debug TLS\n \tconnection and authentication problems.\n \n---imap-sent-folder=<folder>::\n+`--imap-sent-folder=<folder>`::\n \tSome email providers (e.g. iCloud) do not send a copy of the emails sent\n \tusing SMTP to the `Sent` folder or similar in your mailbox. Use this option\n \tto use `git imap-send` to send a copy of the emails to the folder specified\n@@ -331,8 +331,8 @@ must be used for each option.\n This feature requires setting up `git imap-send`. See linkgit:git-imap-send[1]\n for instructions.\n \n---use-imap-only::\n---no-use-imap-only::\n+`--use-imap-only`::\n+`--no-use-imap-only`::\n \tIf this is set, all emails will only be copied to the IMAP folder specified\n \twith `--imap-sent-folder` or `sendemail.imapSentFolder` and will not be sent\n \tto the recipients. Useful if you just want to create a draft of the emails\n@@ -344,8 +344,8 @@ for instructions.\n This feature requires setting up `git imap-send`. See linkgit:git-imap-send[1]\n for instructions.\n \n---batch-size=<num>::\n-\tSome email servers (e.g. 'smtp.163.com') limit the number of emails to be\n+`--batch-size=<num>`::\n+\tSome email servers (e.g. `smtp.163.com`) limit the number of emails to be\n \tsent per session (connection) and this will lead to a failure when\n \tsending many messages.  With this option, send-email will disconnect after\n \tsending _<num>_ messages and wait for a few seconds\n@@ -354,7 +354,7 @@ for instructions.\n \tretype your password every time this happens.  Defaults to the\n \t`sendemail.smtpBatchSize` configuration variable.\n \n---relogin-delay=<int>::\n+`--relogin-delay=<int>`::\n \tWaiting _<int>_ seconds before reconnecting to SMTP server. Used together\n \twith `--batch-size` option.  Defaults to the `sendemail.smtpReloginDelay`\n \tconfiguration variable.\n@@ -362,29 +362,29 @@ for instructions.\n Automating\n ~~~~~~~~~~\n \n---no-to::\n---no-cc::\n---no-bcc::\n+`--no-to`::\n+`--no-cc`::\n+`--no-bcc`::\n \tClear any list of `To:`, `Cc:`, `Bcc:` addresses previously\n \tset via config.\n \n---no-identity::\n+`--no-identity`::\n \tClear the previously read value of `sendemail.identity` set\n \tvia config, if any.\n \n---to-cmd=<command>::\n+`--to-cmd=<command>`::\n \tSpecify a command to execute once per patch file which\n \tshould generate patch file specific `To:` entries.\n \tOutput of this command must be single email address per line.\n \tDefault is the value of `sendemail.toCmd` configuration value.\n \n---cc-cmd=<command>::\n+`--cc-cmd=<command>`::\n \tSpecify a command to execute once per patch file which\n \tshould generate patch file specific `Cc:` entries.\n \tOutput of this command must be single email address per line.\n \tDefault is the value of `sendemail.ccCmd` configuration value.\n \n---header-cmd=<command>::\n+`--header-cmd=<command>`::\n \tSpecify a command that is executed once per outgoing message\n \tand output RFC 2822 style header lines to be inserted into\n \tthem. When the `sendemail.headerCmd` configuration variable is\n@@ -392,11 +392,11 @@ Automating\n \tat the command line, its value takes precedence over the\n \t`sendemail.headerCmd` configuration variable.\n \n---no-header-cmd::\n+`--no-header-cmd`::\n \tDisable any header command in use.\n \n---chain-reply-to::\n---no-chain-reply-to::\n+`--chain-reply-to`::\n+`--no-chain-reply-to`::\n \tIf this is set, each email will be sent as a reply to the previous\n \temail sent.  If disabled with `--no-chain-reply-to`, all emails after\n \tthe first will be sent as replies to the first email sent.  When using\n@@ -404,34 +404,34 @@ Automating\n \tentire patch series. Disabled by default, but the `sendemail.chainReplyTo`\n \tconfiguration variable can be used to enable it.\n \n---identity=<identity>::\n+`--identity=<identity>`::\n \tA configuration identity. When given, causes values in the\n \t`sendemail.<identity>` subsection to take precedence over\n \tvalues in the `sendemail` section. The default identity is\n \tthe value of `sendemail.identity`.\n \n---signed-off-by-cc::\n---no-signed-off-by-cc::\n+`--signed-off-by-cc`::\n+`--no-signed-off-by-cc`::\n \tIf this is set, add emails found in the `Signed-off-by` trailer or `Cc:`\n \tlines to the cc list. Default is the value of `sendemail.signedOffByCc`\n \tconfiguration value; if that is unspecified, default to\n \t`--signed-off-by-cc`.\n \n---cc-cover::\n---no-cc-cover::\n+`--cc-cover`::\n+`--no-cc-cover`::\n \tIf this is set, emails found in `Cc:` headers in the first patch of\n \tthe series (typically the cover letter) are added to the cc list\n \tfor each email set. Default is the value of `sendemail.ccCover`\n \tconfiguration value; if that is unspecified, default to `--no-cc-cover`.\n \n---to-cover::\n---no-to-cover::\n+`--to-cover`::\n+`--no-to-cover`::\n \tIf this is set, emails found in `To:` headers in the first patch of\n \tthe series (typically the cover letter) are added to the to list\n \tfor each email set. Default is the value of `sendemail.toCover`\n \tconfiguration value; if that is unspecified, default to `--no-to-cover`.\n \n---suppress-cc=<category>::\n+`--suppress-cc=<category>`::\n \tSpecify an additional category of recipients to suppress the\n \tauto-cc of:\n +\n@@ -456,14 +456,14 @@ Default is the value of `sendemail.suppressCc` configuration value; if\n that is unspecified, default to `self` if `--suppress-from` is\n specified, as well as `body` if `--no-signed-off-by-cc` is specified.\n \n---suppress-from::\n---no-suppress-from::\n+`--suppress-from`::\n+`--no-suppress-from`::\n \tIf this is set, do not add the `From:` address to the `Cc:` list.\n \tDefault is the value of `sendemail.suppressFrom` configuration\n \tvalue; if that is unspecified, default to `--no-suppress-from`.\n \n---thread::\n---no-thread::\n+`--thread`::\n+`--no-thread`::\n \tIf this is set, the `In-Reply-To` and `References` headers will be\n \tadded to each email sent.  Whether each mail refers to the\n \tprevious email (`deep` threading per `git format-patch`\n@@ -481,8 +481,8 @@ exists when `git send-email` is asked to add it (especially note that\n Failure to do so may not produce the expected result in the\n recipient's MUA.\n \n---mailmap::\n---no-mailmap::\n+`--mailmap`::\n+`--no-mailmap`::\n \tUse the mailmap file (see linkgit:gitmailmap[5]) to map all\n \taddresses to their canonical real name and email address. Additional\n \tmailmap data specific to `git send-email` may be provided using the\n@@ -492,7 +492,7 @@ recipient's MUA.\n Administering\n ~~~~~~~~~~~~~\n \n---confirm=<mode>::\n+`--confirm=<mode>`::\n \tConfirm just before sending:\n +\n --\n@@ -508,22 +508,22 @@ Default is the value of `sendemail.confirm` configuration value; if that\n is unspecified, default to `auto` unless any of the suppress options\n have been specified, in which case default to `compose`.\n \n---dry-run::\n+`--dry-run`::\n \tDo everything except actually send the emails.\n \n---format-patch::\n---no-format-patch::\n+`--format-patch`::\n+`--no-format-patch`::\n \tWhen an argument may be understood either as a reference or as a file name,\n \tchoose to understand it as a format-patch argument (`--format-patch`)\n \tor as a file name (`--no-format-patch`). By default, when such a conflict\n \toccurs, `git send-email` will fail.\n \n---quiet::\n+`--quiet`::\n \tMake `git send-email` less verbose.  One line per email should be\n \tall that is output.\n \n---validate::\n---no-validate::\n+`--validate`::\n+`--no-validate`::\n \tPerform sanity checks on patches.\n \tCurrently, validation means the following:\n +\n@@ -539,20 +539,20 @@ have been specified, in which case default to `compose`.\n Default is the value of `sendemail.validate`; if this is not set,\n default to `--validate`.\n \n---force::\n+`--force`::\n \tSend emails even if safety checks would prevent it.\n \n \n Information\n ~~~~~~~~~~~\n \n---dump-aliases::\n+`--dump-aliases`::\n \tInstead of the normal operation, dump the shorthand alias names from\n \tthe configured alias file(s), one per line in alphabetical order. Note\n \tthat this only includes the alias name and not its expanded email addresses.\n \tSee `sendemail.aliasesFile` for more information about aliases.\n \n---translate-aliases::\n+`--translate-aliases`::\n \tInstead of the normal operation, read from standard input and\n \tinterpret each line as an email alias. Translate it according to the\n \tconfigured alias file(s). Output each translated name and email\n@@ -718,7 +718,7 @@ include::format-patch-caveats.adoc[]\n \n SEE ALSO\n --------\n-linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)\n+linkgit:git-format-patch[1], linkgit:git-imap-send[1], `mbox`(5)\n \n GIT\n ---\n-- \ngitgitgadget\n\n"},{"id":"548637","messageId":"5b6e9bd3f3569cf9977d1cfd120a92756ec86b29.1784490878.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.git.1784490878.gitgitgadget@gmail.com","subject":"[PATCH 4/4] doc: convert git-request-pull synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-19T19:54:37Z","receivedAt":"2026-07-19T19:54:46Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n * Replace [verse] with [synopsis] in the SYNOPSIS block\n * remove single-quote formatting from the command name\n * backtick-quote the flag\n * use _<placeholder>_ form for positional parameter terms\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-request-pull.adoc | 38 +++++++++++++++++------------\n 1 file changed, 23 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-request-pull.adoc b/Documentation/git-request-pull.adoc\nindex 15dcbb6d91..8b6642b312 100644\n--- a/Documentation/git-request-pull.adoc\n+++ b/Documentation/git-request-pull.adoc\n@@ -7,8 +7,8 @@ git-request-pull - Generates a summary of pending changes\n \n SYNOPSIS\n --------\n-[verse]\n-'git request-pull' [-p] <start> <URL> [<end>]\n+[synopsis]\n+git request-pull [-p] <start> <URL> [<end>]\n \n DESCRIPTION\n -----------\n@@ -19,28 +19,28 @@ begins with the branch description, summarizes\n the changes, and indicates from where they can be pulled.\n \n The upstream project is expected to have the commit named by\n-`<start>` and the output asks it to integrate the changes you made\n-since that commit, up to the commit named by `<end>`, by visiting\n-the repository named by `<URL>`.\n+_<start>_ and the output asks it to integrate the changes you made\n+since that commit, up to the commit named by _<end>_, by visiting\n+the repository named by _<URL>_.\n \n \n OPTIONS\n -------\n--p::\n+`-p`::\n \tInclude patch text in the output.\n \n-<start>::\n+_<start>_::\n \tCommit to start at.  This names a commit that is already in\n \tthe upstream history.\n \n-<URL>::\n+_<URL>_::\n \tThe repository URL to be pulled from.\n \n-<end>::\n-\tCommit to end at (defaults to HEAD).  This names the commit\n+_<end>_::\n+\tCommit to end at (defaults to `HEAD`).  This names the commit\n \tat the tip of the history you are asking to be pulled.\n +\n-When the repository named by `<URL>` has the commit at a tip of a\n+When the repository named by _<URL>_ has the commit at a tip of a\n ref that is different from the ref you have locally, you can use the\n `<local>:<remote>` syntax, to have its local name, a colon `:`, and\n its remote name.\n@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project.\n First you push that change to your public repository for others to\n see:\n \n-\tgit push https://git.ko.xz/project master\n+-----\n+git push https://git.ko.xz/project master\n+-----\n \n Then, you run this command:\n \n-\tgit request-pull v1.0 https://git.ko.xz/project master\n+------\n+git request-pull v1.0 https://git.ko.xz/project master\n+------\n \n which will produce a request to the upstream, summarizing the\n changes between the `v1.0` release and your `master`, to pull it\n@@ -67,11 +71,15 @@ from your public repository.\n If you pushed your change to a branch whose name is different from\n the one you have locally, e.g.\n \n-\tgit push https://git.ko.xz/project master:for-linus\n+-----\n+git push https://git.ko.xz/project master:for-linus\n+-----\n \n then you can ask that to be pulled with\n \n-\tgit request-pull v1.0 https://git.ko.xz/project master:for-linus\n+-----\n+git request-pull v1.0 https://git.ko.xz/project master:for-linus\n+-----\n \n \n GIT\n-- \ngitgitgadget\n"},{"id":"548639","messageId":"xmqqldb6lfa6.fsf@gitster.g","threadId":"66038","inReplyTo":"e1ed85e3f2733f0f1cc46416903d1e0c8b4c1856.1784490878.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/4] doc: convert git-format-patch synopsis and options to new style","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-19T23:40:17Z","receivedAt":"2026-07-19T23:40:20Z","isPatch":true,"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Backtick-quote all option terms in the OPTIONS section, convert\n> standalone placeholders to _<placeholder>_ form, and convert\n> single-quoted commands and tools in prose to backtick form.\n\nOK.\n\n> @@ -708,15 +708,15 @@ BASE TREE INFORMATION\n>  \n>  The base tree information block is used for maintainers or third party\n>  testers to know the exact state the patch series applies to. It consists\n> +of the \"base commit\", which is a well-known commit that is part of the\n>  stable part of the project history everybody else works off of, and zero\n> +or more \"prerequisite patches\", which are well-known patches in flight\n> +that is not yet part of the \"base commit\" that need to be applied on top\n> +of \"base commit\" in topological order before the patches can be applied.\n\nGIven that the last part of this hunk below uses backtick-quoting\nfor `prerequisite patch` and `patch id`, shouldn't the references to\n`base commit`, and `prerequisite patch(es)` in the above also be\nbacktick quoted for consistency?\n\n> +The \"base commit\" is shown as \"base-commit: \" followed by the 40-hex of\n> +the commit object name.  A `prerequisite patch` is shown as\n> +\"prerequisite-patch-id: \" followed by the 40-hex `patch id`, which can\n>  be obtained by passing the patch through the `git patch-id --stable`\n>  command.\n\n"},{"id":"548640","messageId":"xmqqfr1eleyx.fsf@gitster.g","threadId":"66038","inReplyTo":"5b6e9bd3f3569cf9977d1cfd120a92756ec86b29.1784490878.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-19T23:47:02Z","receivedAt":"2026-07-19T23:47:04Z","isPatch":true,"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> @@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project.\n>  First you push that change to your public repository for others to\n>  see:\n>  \n> -\tgit push https://git.ko.xz/project master\n> +-----\n> +git push https://git.ko.xz/project master\n> +-----\n>  \n>  Then, you run this command:\n>  \n> -\tgit request-pull v1.0 https://git.ko.xz/project master\n> +------\n> +git request-pull v1.0 https://git.ko.xz/project master\n> +------\n>  \n>  which will produce a request to the upstream, summarizing the\n>  changes between the `v1.0` release and your `master`, to pull it\n> @@ -67,11 +71,15 @@ from your public repository.\n>  If you pushed your change to a branch whose name is different from\n>  the one you have locally, e.g.\n>  \n> -\tgit push https://git.ko.xz/project master:for-linus\n> +-----\n> +git push https://git.ko.xz/project master:for-linus\n> +-----\n>  \n>  then you can ask that to be pulled with\n>  \n> -\tgit request-pull v1.0 https://git.ko.xz/project master:for-linus\n> +-----\n> +git request-pull v1.0 https://git.ko.xz/project master:for-linus\n> +-----\n\nIs there a widely accepted guideline among AsciiDoc users governing\nhow many dashes should delimit these blocks, other than \"at least\nfour, with the opening and closing counts matching\"?  If so, what is\nit?  We see five, six, five, and five dashes in the proposed changes\nabove, and in '[PATCH 1/4]' we saw nine.  Even if varying counts are\nfunctionally equivalent, the inconsistency is a bit distracting.\n\nThanks.\n\n[Footnote]\n\n * an excerpt from [PATCH 1/4]\n\ndiff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc\nindex 538b91afc0..dd1e0a3718 100644\n--- a/Documentation/git-imap-send.adoc\n+++ b/Documentation/git-imap-send.adoc\n@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.\n \n Once the commits are ready to be sent, run the following command:\n \n-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n+\n+---------\n+$ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n+---------\n"},{"id":"548690","messageId":"2418232.ElGaqSPkdT@piment-oiseau","threadId":"66038","inReplyTo":"xmqqldb6lfa6.fsf@gitster.g","subject":"Re: [PATCH 2/4] doc: convert git-format-patch synopsis and options to new style","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2026-07-20T20:09:55Z","receivedAt":"2026-07-20T20:10:12Z","isPatch":true,"body":"On Monday, 20 July 2026 01:40:17 CEST Junio C Hamano wrote:\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> > Backtick-quote all option terms in the OPTIONS section, convert\n> > standalone placeholders to _<placeholder>_ form, and convert\n> > single-quoted commands and tools in prose to backtick form.\n> \n> OK.\n> \n> > @@ -708,15 +708,15 @@ BASE TREE INFORMATION\n> > \n> >  The base tree information block is used for maintainers or third party\n> >  testers to know the exact state the patch series applies to. It consists\n> > \n> > +of the \"base commit\", which is a well-known commit that is part of the\n> > \n> >  stable part of the project history everybody else works off of, and zero\n> > \n> > +or more \"prerequisite patches\", which are well-known patches in flight\n> > +that is not yet part of the \"base commit\" that need to be applied on top\n> > +of \"base commit\" in topological order before the patches can be applied.\n> \n> GIven that the last part of this hunk below uses backtick-quoting\n> for `prerequisite patch` and `patch id`, shouldn't the references to\n> `base commit`, and `prerequisite patch(es)` in the above also be\n> backtick quoted for consistency?\n> \n\nIn fact, the formatting were swapped. For proper rendering and preservation of \nspaces, it should be:\n\nThe \"base commit\" is shown as \"`base-commit:` \" followed by the 40-hex of\nthe commit object name.  A \"prerequisite patch\" is shown as\n\"`prerequisite-patch-id:` \" followed by the 40-hex \"patch id\", which can\nbe obtained by passing the patch through the `git patch-id --stable`\ncommand.\n\n\nOnly the constant strings are back-ticked. The others are only quoted.\n\nWill reroll.\n\n> > +The \"base commit\" is shown as \"base-commit: \" followed by the 40-hex of\n> > +the commit object name.  A `prerequisite patch` is shown as\n> > +\"prerequisite-patch-id: \" followed by the 40-hex `patch id`, which can\n> > \n> >  be obtained by passing the patch through the `git patch-id --stable`\n> >  command.\n\n\n\n\n"},{"id":"548691","messageId":"23179740.EfDdHjke4D@piment-oiseau","threadId":"66038","inReplyTo":"xmqqfr1eleyx.fsf@gitster.g","subject":"Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2026-07-20T20:39:29Z","receivedAt":"2026-07-20T20:39:34Z","isPatch":true,"body":"On Monday, 20 July 2026 01:47:02 CEST Junio C Hamano wrote:\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> > @@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into \nthe\n> > project.> \n> >  First you push that change to your public repository for others to\n> > \n> >  see:\n> > -\tgit push https://git.ko.xz/project master\n> > +-----\n> > +git push https://git.ko.xz/project master\n> > +-----\n> > \n> >  Then, you run this command:\n> > -\tgit request-pull v1.0 https://git.ko.xz/project master\n> > +------\n> > +git request-pull v1.0 https://git.ko.xz/project master\n> > +------\n> > \n> >  which will produce a request to the upstream, summarizing the\n> >  changes between the `v1.0` release and your `master`, to pull it\n> > \n> > @@ -67,11 +71,15 @@ from your public repository.\n> > \n> >  If you pushed your change to a branch whose name is different from\n> >  the one you have locally, e.g.\n> > \n> > -\tgit push https://git.ko.xz/project master:for-linus\n> > +-----\n> > +git push https://git.ko.xz/project master:for-linus\n> > +-----\n> > \n> >  then you can ask that to be pulled with\n> > \n> > -\tgit request-pull v1.0 https://git.ko.xz/project master:for-linus\n> > +-----\n> > +git request-pull v1.0 https://git.ko.xz/project master:for-linus\n> > +-----\n> \n> Is there a widely accepted guideline among AsciiDoc users governing\n> how many dashes should delimit these blocks, other than \"at least\n> four, with the opening and closing counts matching\"?  If so, what is\n> it?  We see five, six, five, and five dashes in the proposed changes\n> above, and in '[PATCH 1/4]' we saw nine.  Even if varying counts are\n> functionally equivalent, the inconsistency is a bit distracting.\n> \n> Thanks.\n> \n> [Footnote]\n> \n>  * an excerpt from [PATCH 1/4]\n> \n> diff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-\nsend.adoc\n> index 538b91afc0..dd1e0a3718 100644\n> --- a/Documentation/git-imap-send.adoc\n> +++ b/Documentation/git-imap-send.adoc\n> @@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.\n> \n>  Once the commits are ready to be sent, run the following command:\n> \n> -  $ git format-patch --cover-letter -M --stdout origin/master | git imap-\nsend\n> +\n> +---------\n> +$ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n> +---------\n\n\n\"Widely accepted\", I do not know. I would better frame it as \"because at least \nfour is needed and I'm lazy, then it's four\". I'm not expert enough the \nasciidoc specification to have a definitive answer of mine, but the \nasciidoctor specification says exactly four [1]\n\nWe could indeed apply the rule of 4 dashes by default.\n\nNote that this only applies because it is a listing block which does not \naccept nesting.\n\nI will reroll.\n\n[1]: https://docs.asciidoctor.org/asciidoc/latest/verbatim/listing-blocks/\n#delimited-listing-block\n\n\n"},{"id":"548693","messageId":"xmqqy0f5bbfb.fsf@gitster.g","threadId":"66038","inReplyTo":"23179740.EfDdHjke4D@piment-oiseau","subject":"Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-20T21:26:00Z","receivedAt":"2026-07-20T21:26:03Z","isPatch":true,"body":"Jean-Noël AVILA <jn.avila@free.fr> writes:\n\n> \"Widely accepted\", I do not know. I would better frame it as \"because at least \n> four is needed and I'm lazy, then it's four\". I'm not expert enough the \n> asciidoc specification to have a definitive answer of mine, but the \n> asciidoctor specification says exactly four [1]\n>\n> We could indeed apply the rule of 4 dashes by default.\n>\n> Note that this only applies because it is a listing block which does not \n> accept nesting.\n>\n> I will reroll.\n\nThanks.  Sounds like a good plan to me.\n"},{"id":"548828","messageId":"pull.2185.v2.git.1784841567.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.git.1784490878.gitgitgadget@gmail.com","subject":"[PATCH v2 0/4] A new batch of synopsis conversion","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-23T21:19:22Z","receivedAt":"2026-07-23T21:19:31Z","isPatch":true,"body":"The conversion to synopsis continues. Now the commands are less common, so I\nmay propose larger PRs if it's ok.\n\nChanges since v1:\n\n * swap formats following comments\n * switch all listing blocks to 4 dash fences\n\nJean-Noël Avila (4):\n  doc: convert git-imap-send synopsis and options to new style\n  doc: convert git-format-patch synopsis and options to new style\n  doc: convert git-send-email synopsis and options to new style\n  doc: convert git-request-pull synopsis and options to new style\n\n Documentation/config/imap.adoc      |   2 +-\n Documentation/config/sendemail.adoc |  92 ++++-----\n Documentation/diff-options.adoc     |   8 +-\n Documentation/git-format-patch.adoc | 289 ++++++++++++++--------------\n Documentation/git-imap-send.adoc    |  22 ++-\n Documentation/git-request-pull.adoc |  38 ++--\n Documentation/git-send-email.adoc   | 162 ++++++++--------\n 7 files changed, 311 insertions(+), 302 deletions(-)\n\n\nbase-commit: 08621c32d5536babd139ab1a9086349b3672edd6\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2185%2Fjnavila%2Fconvert_synopsis_202606-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2185/jnavila/convert_synopsis_202606-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/2185\n\nRange-diff vs v1:\n\n 1:  798c064390 ! 1:  697b4b55c3 doc: convert git-imap-send synopsis and options to new style\n     @@ Documentation/config/imap.adoc\n       \tplaintext `LOGIN` command.\n      \n       ## Documentation/git-imap-send.adoc ##\n     -@@ Documentation/git-imap-send.adoc: supports only `XOAUTH2` as the mechanism.\n     +@@ Documentation/git-imap-send.adoc: that order.\n     + \n     + Typical usage is something like:\n     + \n     +-------\n     ++----\n     + $ git format-patch --signoff --stdout --attach origin | git imap-send\n     +-------\n     ++----\n     + \n     + \n     + OPTIONS\n     +@@ Documentation/git-imap-send.adoc: have set up) may not be verified correctly.\n     + \n     + Using Gmail's IMAP interface:\n     + \n     +----------\n     ++----\n     + [imap]\n     +     folder = \"[Gmail]/Drafts\"\n     +     host = imaps://imap.gmail.com\n     +     user = user@gmail.com\n     +     port = 993\n     +----------\n     ++----\n     + \n     + Gmail does not allow using your regular password for `git imap-send`.\n     + If you have multi-factor authentication set up on your Gmail account, you\n     +@@ Documentation/git-imap-send.adoc: than using app-specific passwords, and also does not enforce the need of\n     + having multi-factor authentication. You will have to use an OAuth2.0\n     + access token in place of your password when using this authentication.\n     + \n     +----------\n     ++----\n     + [imap]\n     +     folder = \"[Gmail]/Drafts\"\n     +     host = imaps://imap.gmail.com\n     +     user = user@gmail.com\n     +     port = 993\n     +     authmethod = OAUTHBEARER\n     +----------\n     ++----\n     + \n     + Using Outlook's IMAP interface:\n     + \n     + Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it\n     + supports only `XOAUTH2` as the mechanism.\n     + \n     +----------\n     ++----\n     + [imap]\n     +     folder = \"Drafts\"\n     +     host = imaps://outlook.office365.com\n     +     user = user@outlook.com\n     +     port = 993\n     +     authmethod = XOAUTH2\n     +----------\n     ++----\n       \n       Once the commits are ready to be sent, run the following command:\n       \n      -  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n     -+\n     -+---------\n     ++----\n      +$ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n     -+---------\n     ++----\n       \n       Just make sure to disable line wrapping in the email client (Gmail's web\n       interface will wrap lines no matter what, so you need to use a real\n 2:  e1ed85e3f2 ! 2:  3850fb33ff doc: convert git-format-patch synopsis and options to new style\n     @@ Documentation/git-format-patch.adoc: set.\n       \tShow progress reports on stderr as patches are generated.\n       \n       CONFIGURATION\n     +@@ Documentation/git-format-patch.adoc: outputting more than one patch, add \"To:\" or \"Cc:\" headers, configure\n     + attachments, change the patch output directory, and sign off patches\n     + with configuration variables.\n     + \n     +-------------\n     ++----\n     + [format]\n     + \theaders = \"Organization: git-foo\\n\"\n     + \tsubjectPrefix = CHANGE\n      @@ Documentation/git-format-patch.adoc: with configuration variables.\n     + \tcoverLetter = auto\n     + \tcommitListFormat = shortlog\n     + \tcoverFromDescription = auto\n     +-------------\n     +-\n     ++----\n     + \n       DISCUSSION\n       ----------\n       \n     @@ Documentation/git-format-patch.adoc: with configuration variables.\n       with a fixed \"magic\" time stamp to indicate that the file is output\n       from format-patch rather than a real mailbox, like so:\n       \n     +-------------\n     ++----\n     + From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001\n     + From: Tony Luck <tony.luck@intel.com>\n     + Date: Tue, 13 Jul 2010 11:42:54 -0700\n     +@@ Documentation/git-format-patch.adoc: arch/arm config files were slimmed down using a python script\n     + \n     + Do the same for ia64 so we can have sleek & trim looking\n     + ...\n     +-------------\n     ++----\n     + \n     + Typically it will be placed in a MUA's drafts folder, edited to add\n     + timely commentary that should not go in the changelog after the three\n      @@ Documentation/git-format-patch.adoc: can save interesting patches in a UNIX mailbox and apply them with\n       linkgit:git-am[1].\n       \n     @@ Documentation/git-format-patch.adoc: can save interesting patches in a UNIX mail\n       line that consists solely of \"`-- >8 --`\" (scissors and perforation),\n       followed by the patch with unnecessary header fields removed:\n       \n     +-------------\n     ++----\n     + ...\n     + > So we should do such-and-such.\n     + \n     +@@ Documentation/git-format-patch.adoc: Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet\n     + \n     + arch/arm config files were slimmed down using a python script\n     + ...\n     +-------------\n     ++----\n     + \n     + When sending a patch this way, most often you are sending your own\n     + patch, so in addition to the \"`From $SHA1 $magic_timestamp`\" marker you\n      @@ Documentation/git-format-patch.adoc: two common types of corruption:\n       One way to test if your MUA is set up correctly is:\n       \n     @@ Documentation/git-format-patch.adoc: External Editor from https://globs.org/arti\n          window for the patch, use Tools->about:config to set the\n          following to the indicated values:\n       +\n     +-----------\n     ++----\n     + \tmailnews.send_plaintext_flowed  => false\n     + \tmailnews.wraplength             => 0\n     +-----------\n     ++----\n     + \n     + 4. Open a compose window and click the external editor icon.\n     + \n     +@@ Documentation/git-format-patch.adoc: External Editor from https://globs.org/articles.php?lng=en&pg=8\n     + Side note: it may be possible to do step 2 with\n     + about:config and the following settings but no one's tried yet.\n     + \n     +-----------\n     ++----\n     + \tmail.html_compose                       => false\n     + \tmail.identity.default.compose_html      => false\n     + \tmail.identity.id?.compose_html          => false\n     +-----------\n     ++----\n     + \n     + There is a script in contrib/thunderbird-patch-inline which can help\n     + you include patches with Thunderbird in an easy way. To use it, do the\n      @@ Documentation/git-format-patch.adoc: BASE TREE INFORMATION\n       \n       The base tree information block is used for maintainers or third party\n     @@ Documentation/git-format-patch.adoc: BASE TREE INFORMATION\n      -The 'base commit' is shown as \"base-commit: \" followed by the 40-hex of\n      -the commit object name.  A 'prerequisite patch' is shown as\n      -\"prerequisite-patch-id: \" followed by the 40-hex 'patch id', which can\n     -+The \"base commit\" is shown as \"base-commit: \" followed by the 40-hex of\n     -+the commit object name.  A `prerequisite patch` is shown as\n     -+\"prerequisite-patch-id: \" followed by the 40-hex `patch id`, which can\n     ++The \"base commit\" is shown as \"`base-commit:` \" followed by the 40-hex of\n     ++the commit object name.  A \"prerequisite patch\" is shown as\n     ++\"`prerequisite-patch-id:` \" followed by the 40-hex \"patch id\", which can\n       be obtained by passing the patch through the `git patch-id --stable`\n       command.\n       \n     +@@ Documentation/git-format-patch.adoc: range), the base tree information block is shown at the end of the\n     + first message the command outputs (either the first patch, or the\n     + cover letter), like this:\n     + \n     +-------------\n     ++----\n     + base-commit: P\n     + prerequisite-patch-id: X\n     + prerequisite-patch-id: Y\n     + prerequisite-patch-id: Z\n     +-------------\n     ++----\n     + \n     + For non-linear topology, such as\n     + \n      @@ Documentation/git-format-patch.adoc: EXAMPLES\n       --------\n       \n 3:  723450c5a0 = 3:  94751ae58b doc: convert git-send-email synopsis and options to new style\n 4:  5b6e9bd3f3 ! 4:  740b24631d doc: convert git-request-pull synopsis and options to new style\n     @@ Documentation/git-request-pull.adoc: the `v1.0` release, and want it to be integ\n       see:\n       \n      -\tgit push https://git.ko.xz/project master\n     -+-----\n     ++----\n      +git push https://git.ko.xz/project master\n     -+-----\n     ++----\n       \n       Then, you run this command:\n       \n      -\tgit request-pull v1.0 https://git.ko.xz/project master\n     -+------\n     ++----\n      +git request-pull v1.0 https://git.ko.xz/project master\n     -+------\n     ++----\n       \n       which will produce a request to the upstream, summarizing the\n       changes between the `v1.0` release and your `master`, to pull it\n     @@ Documentation/git-request-pull.adoc: from your public repository.\n       the one you have locally, e.g.\n       \n      -\tgit push https://git.ko.xz/project master:for-linus\n     -+-----\n     ++----\n      +git push https://git.ko.xz/project master:for-linus\n     -+-----\n     ++----\n       \n       then you can ask that to be pulled with\n       \n      -\tgit request-pull v1.0 https://git.ko.xz/project master:for-linus\n     -+-----\n     ++----\n      +git request-pull v1.0 https://git.ko.xz/project master:for-linus\n     -+-----\n     ++----\n       \n       \n       GIT\n\n-- \ngitgitgadget\n"},{"id":"548829","messageId":"697b4b55c37053e2038a5d108987fed39f4b765a.1784841567.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.v2.git.1784841567.gitgitgadget@gmail.com","subject":"[PATCH v2 1/4] doc: convert git-imap-send synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-23T21:19:23Z","receivedAt":"2026-07-23T21:19:34Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\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 <jn.avila@free.fr>\n---\n Documentation/config/imap.adoc   |  2 +-\n Documentation/git-imap-send.adoc | 22 ++++++++++++----------\n 2 files changed, 13 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc\nindex cb8f5e2700..6b97776bc3 100644\n--- a/Documentation/config/imap.adoc\n+++ b/Documentation/config/imap.adoc\n@@ -41,7 +41,7 @@\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`\n+\tthan 7.34.0, or if you're running `git-imap-send` with the `--no-curl`\n \toption, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER`\n \tand `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP\n \tplaintext `LOGIN` command.\ndiff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc\nindex 538b91afc0..1814d94491 100644\n--- a/Documentation/git-imap-send.adoc\n+++ b/Documentation/git-imap-send.adoc\n@@ -24,9 +24,9 @@ that order.\n \n Typical usage is something like:\n \n-------\n+----\n $ git format-patch --signoff --stdout --attach origin | git imap-send\n-------\n+----\n \n \n OPTIONS\n@@ -138,13 +138,13 @@ have set up) may not be verified correctly.\n \n Using Gmail's IMAP interface:\n \n----------\n+----\n [imap]\n     folder = \"[Gmail]/Drafts\"\n     host = imaps://imap.gmail.com\n     user = user@gmail.com\n     port = 993\n----------\n+----\n \n Gmail does not allow using your regular password for `git imap-send`.\n If you have multi-factor authentication set up on your Gmail account, you\n@@ -167,32 +167,34 @@ than using app-specific passwords, and also does not enforce the need of\n having multi-factor authentication. You will have to use an OAuth2.0\n access token in place of your password when using this authentication.\n \n----------\n+----\n [imap]\n     folder = \"[Gmail]/Drafts\"\n     host = imaps://imap.gmail.com\n     user = user@gmail.com\n     port = 993\n     authmethod = OAUTHBEARER\n----------\n+----\n \n Using Outlook's IMAP interface:\n \n Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it\n supports only `XOAUTH2` as the mechanism.\n \n----------\n+----\n [imap]\n     folder = \"Drafts\"\n     host = imaps://outlook.office365.com\n     user = user@outlook.com\n     port = 993\n     authmethod = XOAUTH2\n----------\n+----\n \n Once the commits are ready to be sent, run the following command:\n \n-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n+----\n+$ git format-patch --cover-letter -M --stdout origin/master | git imap-send\n+----\n \n Just make sure to disable line wrapping in the email client (Gmail's web\n interface will wrap lines no matter what, so you need to use a real\n@@ -217,7 +219,7 @@ users may wish to visit this web page for more information:\n \n SEE ALSO\n --------\n-linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)\n+linkgit:git-format-patch[1], linkgit:git-send-email[1], `mbox`(5)\n \n GIT\n ---\n-- \ngitgitgadget\n\n"},{"id":"548830","messageId":"3850fb33ffbc585c68d59861c6e943e0dddf9cee.1784841567.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.v2.git.1784841567.gitgitgadget@gmail.com","subject":"[PATCH v2 2/4] doc: convert git-format-patch synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-23T21:19:24Z","receivedAt":"2026-07-23T21:19:35Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nReplace [verse] with [synopsis] in the SYNOPSIS block and remove\nsingle-quote formatting from the command name.\n\nBacktick-quote all option terms in the OPTIONS section, convert\nstandalone placeholders to _<placeholder>_ form, and convert\nsingle-quoted commands and tools in prose to backtick form.\n\nAlso update the included files:\n- diff-options.adoc: backtick-quote the git-format-patch-specific\n  option terms (-p, --no-stat, --max-depth=<depth>)\n- format-patch-caveats.adoc: convert patch(1) to `patch`(1)\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/diff-options.adoc     |   8 +-\n Documentation/git-format-patch.adoc | 289 ++++++++++++++--------------\n 2 files changed, 148 insertions(+), 149 deletions(-)\n\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex c8242e2462..e605d28678 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -13,8 +13,8 @@ endif::git-diff[]\n endif::git-format-patch[]\n \n ifdef::git-format-patch[]\n--p::\n---no-stat::\n+`-p`::\n+`--no-stat`::\n \tGenerate plain patches without any diffstats.\n endif::git-format-patch[]\n \n@@ -893,8 +893,8 @@ endif::git-format-patch[]\n \treverted with `--ita-visible-in-index`. Both options are\n \texperimental and could be removed in future.\n \n---max-depth=<depth>::\n-\tFor each pathspec given on command line, descend at most `<depth>`\n+`--max-depth=<depth>`::\n+\tFor each pathspec given on command line, descend at most _<depth>_\n \tlevels of directories. A value of `-1` means no limit.\n \tCannot be combined with wildcards in the pathspec.\n \tGiven a tree containing `foo/bar/baz`, the following list shows the\ndiff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc\nindex f7905c0f7c..191f64b77d 100644\n--- a/Documentation/git-format-patch.adoc\n+++ b/Documentation/git-format-patch.adoc\n@@ -8,8 +8,8 @@ git-format-patch - Prepare patches for e-mail submission\n \n SYNOPSIS\n --------\n-[verse]\n-'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]\n+[synopsis]\n+git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]\n \t\t   [--no-thread | --thread[=<style>]]\n \t\t   [(--attach|--inline)[=<boundary>] | --no-attach]\n \t\t   [-s | --signoff]\n@@ -40,20 +40,20 @@ DESCRIPTION\n Prepare each non-merge commit with its \"patch\" in\n one \"message\" per commit, formatted to resemble a UNIX mailbox.\n The output of this command is convenient for e-mail submission or\n-for use with 'git am'.\n+for use with `git am`.\n \n A \"message\" generated by the command consists of three parts:\n \n * A brief metadata header that begins with `From <commit>`\n   with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs\n-  like \"file(1)\" to recognize that the file is an output from this\n+  like `file`(1) to recognize that the file is an output from this\n   command, fields that record the author identity, the author date,\n   and the title of the change (taken from the first paragraph of the\n   commit log message).\n \n * The second and subsequent paragraphs of the commit log message.\n \n-* The \"patch\", which is the \"diff -p --stat\" output (see\n+* The \"patch\", which is the `diff -p --stat` output (see\n   linkgit:git-diff[1]) between the commit and its parent.\n \n The log message and the patch are separated by a line with a\n@@ -61,18 +61,18 @@ three-dash line.\n \n There are two ways to specify which commits to operate on.\n \n-1. A single commit, <since>, specifies that the commits leading\n+1. A single commit, _<since>_, specifies that the commits leading\n    to the tip of the current branch that are not in the history\n-   that leads to the <since> to be output.\n+   that leads to the _<since>_ to be output.\n \n-2. Generic <revision-range> expression (see \"SPECIFYING\n-   REVISIONS\" section in linkgit:gitrevisions[7]) means the\n+2. Generic _<revision-range>_ expression (see 'SPECIFYING\n+   REVISIONS' section in linkgit:gitrevisions[7]) means the\n    commits in the specified range.\n \n-The first rule takes precedence in the case of a single <commit>.  To\n+The first rule takes precedence in the case of a single _<commit>_.  To\n apply the second rule, i.e., format everything since the beginning of\n-history up until <commit>, use the `--root` option: `git format-patch\n---root <commit>`.  If you want to format only <commit> itself, you\n+history up until _<commit>_, use the `--root` option: `git format-patch\n+--root <commit>`.  If you want to format only _<commit>_ itself, you\n can do this with `git format-patch -1 <commit>`.\n \n By default, each output file is numbered sequentially from 1, and uses the\n@@ -82,7 +82,7 @@ will only be numbers, without the first line of the commit appended.\n The names of the output files are printed to standard\n output, unless the `--stdout` option is specified.\n \n-If `-o` is specified, output files are created in <dir>.  Otherwise\n+If `-o` is specified, output files are created in _<dir>_.  Otherwise\n they are created in the current working directory. The default path\n can be set with the `format.outputDirectory` configuration option.\n The `-o` option takes precedence over `format.outputDirectory`.\n@@ -108,119 +108,119 @@ OPTIONS\n :git-format-patch: 1\n include::diff-options.adoc[]\n \n--<n>::\n-\tPrepare patches from the topmost <n> commits.\n+`-<n>`::\n+\tPrepare patches from the topmost _<n>_ commits.\n \n--o <dir>::\n---output-directory <dir>::\n-\tUse <dir> to store the resulting files, instead of the\n+`-o <dir>`::\n+`--output-directory=<dir>`::\n+\tUse _<dir>_ to store the resulting files, instead of the\n \tcurrent working directory.\n \n--n::\n---numbered::\n+`-n`::\n+`--numbered`::\n \tName output in '[PATCH n/m]' format, even with a single patch.\n \n--N::\n---no-numbered::\n+`-N`::\n+`--no-numbered`::\n \tName output in '[PATCH]' format.\n \n---start-number <n>::\n-\tStart numbering the patches at <n> instead of 1.\n+`--start-number <n>`::\n+\tStart numbering the patches at _<n>_ instead of 1.\n \n---numbered-files::\n+`--numbered-files`::\n \tOutput file names will be a simple number sequence\n \twithout the default first line of the commit appended.\n \n--k::\n---keep-subject::\n+`-k`::\n+`--keep-subject`::\n \tDo not strip/add '[PATCH]' from the first line of the\n \tcommit log message.\n \n--s::\n---signoff::\n+`-s`::\n+`--signoff`::\n \tAdd a `Signed-off-by` trailer to the commit message, using\n \tthe committer identity of yourself.\n \tSee the signoff option in linkgit:git-commit[1] for more information.\n \n---stdout::\n+`--stdout`::\n \tPrint all commits to the standard output in mbox format,\n \tinstead of creating a file for each one.\n \n---attach[=<boundary>]::\n+`--attach[=<boundary>]`::\n \tCreate multipart/mixed attachment, the first part of\n \twhich is the commit message and the patch itself in the\n \tsecond part, with `Content-Disposition: attachment`.\n \n---no-attach::\n+`--no-attach`::\n \tDisable the creation of an attachment, overriding the\n \tconfiguration setting.\n \n---inline[=<boundary>]::\n+`--inline[=<boundary>]`::\n \tCreate multipart/mixed attachment, the first part of\n \twhich is the commit message and the patch itself in the\n \tsecond part, with `Content-Disposition: inline`.\n \n---thread[=<style>]::\n---no-thread::\n-\tControls addition of `In-Reply-To` and `References` headers to\n+`--thread[=<style>]`::\n+`--no-thread`::\n+\tControl addition of `In-Reply-To` and `References` headers to\n \tmake the second and subsequent mails appear as replies to the\n \tfirst.  Also controls generation of the `Message-ID` header to\n \treference.\n +\n-The optional <style> argument can be either `shallow` or `deep`.\n-'shallow' threading makes every mail a reply to the head of the\n+The optional _<style>_ argument can be either `shallow` or `deep`.\n+`shallow` threading makes every mail a reply to the head of the\n series, where the head is chosen from the cover letter, the\n-`--in-reply-to`, and the first patch mail, in this order.  'deep'\n+`--in-reply-to`, and the first patch mail, in this order.  `deep`\n threading makes every mail a reply to the previous one.\n +\n The default is `--no-thread`, unless the `format.thread` configuration\n is set.  `--thread` without an argument is equivalent to `--thread=shallow`.\n +\n-Beware that the default for 'git send-email' is to thread emails\n+Beware that the default for `git send-email` is to thread emails\n itself.  If you want `git format-patch` to take care of threading, you\n will want to ensure that threading is disabled for `git send-email`.\n \n---in-reply-to=<message-id>::\n+`--in-reply-to=<message-id>`::\n \tMake the first mail (or all the mails with `--no-thread`) appear as a\n-\treply to the given <message-id>, which avoids breaking threads to\n+\treply to the given _<message-id>_, which avoids breaking threads to\n \tprovide a new patch series.\n \n---ignore-if-in-upstream::\n+`--ignore-if-in-upstream`::\n \tDo not include a patch that matches a commit in\n-\t<until>..<since>.  This will examine all patches reachable\n-\tfrom <since> but not from <until> and compare them with the\n+\t_<until>_.._<since>_.  This will examine all patches reachable\n+\tfrom _<since>_ but not from _<until>_ and compare them with the\n \tpatches being generated, and any patch that matches is\n \tignored.\n \n---always::\n+`--always`::\n \tInclude patches for commits that do not introduce any change,\n \twhich are omitted by default.\n \n---cover-from-description=<mode>::\n-\tControls which parts of the cover letter will be automatically\n+`--cover-from-description=<mode>`::\n+\tControl which parts of the cover letter will be automatically\n \tpopulated using the branch's description.\n +\n-If `<mode>` is `message` or `default`, the cover letter subject will be\n+_<mode>_ can have the following values:\n+\n+`message`;;\n+`default`;; the cover letter subject will be\n populated with placeholder text. The body of the cover letter will be\n populated with the branch's description. This is the default mode when\n no configuration nor command line option is specified.\n-+\n-If `<mode>` is `subject`, the first paragraph of the branch description will\n+`subject`;; the first paragraph of the branch description will\n populate the cover letter subject. The remainder of the description will\n populate the body of the cover letter.\n-+\n-If `<mode>` is `auto`, if the first paragraph of the branch description\n+`auto`;; if the first paragraph of the branch description\n is greater than 100 bytes, then the mode will be `message`, otherwise\n `subject` will be used.\n-+\n-If `<mode>` is `none`, both the cover letter subject and body will be\n+`none`;; both the cover letter subject and body will be\n populated with placeholder text.\n \n---description-file=<file>::\n-\tUse the contents of <file> instead of the branch's description\n+`--description-file=<file>`::\n+\tUse the contents of _<file>_ instead of the branch's description\n \tfor generating the cover letter.\n \n---subject-prefix=<subject-prefix>::\n+`--subject-prefix=<subject-prefix>`::\n \tUse '[<subject-prefix>]' instead of the standard '[PATCH]'\n \tprefix in the subject line. This can be used to name a patch\n \tseries, and can be combined with the `--numbered` option.\n@@ -231,14 +231,14 @@ all patches. This is often useful on mailing lists which receive\n patches for several repositories and can be used to disambiguate\n the patches (with a value of e.g. \"PATCH my-project\").\n \n---filename-max-length=<n>::\n+`--filename-max-length=<n>`::\n \tInstead of the standard 64 bytes, chomp the generated output\n-\tfilenames at around '<n>' bytes (too short a value will be\n+\tfilenames at around _<n>_ bytes (too short a value will be\n \tsilently raised to a reasonable length).  Defaults to the\n \tvalue of the `format.filenameMaxLength` configuration\n \tvariable, or 64 if unconfigured.\n \n---rfc[=<rfc>]::\n+`--rfc[=<rfc>]`::\n \tPrepends the string _<rfc>_ (defaults to \"RFC\") to\n \tthe subject prefix.  As the subject prefix defaults to\n \t\"PATCH\", you'll get \"RFC PATCH\" by default.\n@@ -254,38 +254,38 @@ can be prefixed with a dash (\"`-`\") to signal that the rest of\n the _<rfc>_ string should be appended to the subject prefix instead,\n e.g., `--rfc='-(WIP)'` results in \"PATCH (WIP)\".\n \n--v <n>::\n---reroll-count=<n>::\n-\tMark the series as the <n>-th iteration of the topic. The\n+`-v <n>`::\n+`--reroll-count=<n>`::\n+\tMark the series as the _<n>_-th iteration of the topic. The\n \toutput filenames have `v<n>` prepended to them, and the\n \tsubject prefix (\"PATCH\" by default, but configurable via the\n-\t`--subject-prefix` option) has ` v<n>` appended to it.  E.g.\n+\t`--subject-prefix` option) has `v<n>` appended to it.  E.g.\n \t`--reroll-count=4` may produce `v4-0001-add-makefile.patch`\n \tfile that has \"Subject: [PATCH v4 1/20] Add makefile\" in it.\n-\t`<n>` does not have to be an integer (e.g. \"--reroll-count=4.4\",\n-\tor \"--reroll-count=4rev2\" are allowed), but the downside of\n+\t_<n>_ does not have to be an integer (e.g. `--reroll-count=4.4`,\n+\tor `--reroll-count=4rev2` are allowed), but the downside of\n \tusing such a reroll-count is that the range-diff/interdiff\n \twith the previous version does not state exactly which\n \tversion the new iteration is compared against.\n \n---to=<email>::\n+`--to=<email>`::\n \tAdd a `To:` header to the email headers. This is in addition\n \tto any configured headers, and may be used multiple times.\n \tThe negated form `--no-to` discards all `To:` headers added so\n \tfar (from config or command line).\n \n---cc=<email>::\n+`--cc=<email>`::\n \tAdd a `Cc:` header to the email headers. This is in addition\n \tto any configured headers, and may be used multiple times.\n \tThe negated form `--no-cc` discards all `Cc:` headers added so\n \tfar (from config or command line).\n \n---from::\n---from=<ident>::\n-\tUse `ident` in the `From:` header of each email. In case of a\n+`--from`::\n+`--from=<ident>`::\n+\tUse _<ident>_ in the `From:` header of each email. In case of a\n \tcommit email, if the author ident of the commit is not textually\n-\tidentical to the provided `ident`, place a `From:` header in the\n-\tbody of the message with the original author. If no `ident` is\n+\tidentical to the provided _<ident>_, place a `From:` header in the\n+\tbody of the message with the original author. If no _<ident>_ is\n \tgiven, or if the option is not passed at all, use the ident of\n \tthe current committer.\n +\n@@ -296,8 +296,8 @@ header). Note also that `git send-email` already handles this\n transformation for you, and this option should not be used if you are\n feeding the result to `git send-email`.\n \n---force-in-body-from::\n---no-force-in-body-from::\n+`--force-in-body-from`::\n+`--no-force-in-body-from`::\n \tWith the e-mail sender specified via the `--from` option, by\n \tdefault, an in-body \"From:\" to identify the real author of\n \tthe commit is added at the top of the commit log message if\n@@ -308,7 +308,7 @@ feeding the result to `git send-email`.\n \tDefaults to the value of the `format.forceInBodyFrom`\n \tconfiguration variable.\n \n---add-header=<header>::\n+`--add-header=<header>`::\n \tAdd an arbitrary header to the email headers.  This is in addition\n \tto any configured headers, and may be used multiple times.\n \tFor example, `--add-header=\"Organization: git-foo\"`.\n@@ -316,13 +316,13 @@ feeding the result to `git send-email`.\n \t`Cc:`, and custom) headers added so far from config or command\n \tline.\n \n---cover-letter::\n---no-cover-letter::\n+`--cover-letter`::\n+`--no-cover-letter`::\n \tIn addition to the patches, generate a cover letter file containing the\n \tbranch description, commit list and the overall diffstat.  You can fill\n \tin a description in the file before sending it out.\n \n---commit-list-format=<format-spec>::\n+`--commit-list-format=<format-spec>`::\n \tSpecify the format in which to generate the commit list of the patch\n \tseries. The accepted values for format-spec are `shortlog`, `modern` or\n \ta format-string prefixed with `log:`. E.g. `log: %s (%an)`.\n@@ -334,28 +334,28 @@ feeding the result to `git send-email`.\n \tThis option given from the command-line implies the use of\n \t`--cover-letter` unless `--no-cover-letter` is given.\n \n---encode-email-headers::\n---no-encode-email-headers::\n+`--encode-email-headers`::\n+`--no-encode-email-headers`::\n \tEncode email headers that have non-ASCII characters with\n \t\"Q-encoding\" (described in RFC 2047), instead of outputting the\n \theaders verbatim. Defaults to the value of the\n \t`format.encodeEmailHeaders` configuration variable.\n \n---interdiff=<previous>::\n+`--interdiff=<previous>`::\n \tAs a reviewer aid, insert an interdiff into the cover letter,\n \tor as commentary of the lone patch of a 1-patch series, showing\n \tthe differences between the previous version of the patch series and\n-\tthe series currently being formatted. `previous` is a single revision\n+\tthe series currently being formatted. _<previous>_ is a single revision\n \tnaming the tip of the previous series which shares a common base with\n \tthe series being formatted (for example `git format-patch\n \t--cover-letter --interdiff=feature/v1 -3 feature/v2`).\n \n---range-diff=<previous>::\n+`--range-diff=<previous>`::\n \tAs a reviewer aid, insert a range-diff (see linkgit:git-range-diff[1])\n \tinto the cover letter, or as commentary of the lone patch of a\n \t1-patch series, showing the differences between the previous\n \tversion of the patch series and the series currently being formatted.\n-\t`previous` can be a single revision naming the tip of the previous\n+\t_<previous>_ can be a single revision naming the tip of the previous\n \tseries if it shares a common base with the series being formatted (for\n \texample `git format-patch --cover-letter --range-diff=feature/v1 -3\n \tfeature/v2`), or a revision range if the two versions of the series are\n@@ -367,7 +367,7 @@ product of `format-patch` is generated, and they are not passed to\n the underlying `range-diff` machinery used to generate the cover-letter\n material (this may change in the future).\n \n---creation-factor=<percent>::\n+`--creation-factor=<percent>`::\n \tUsed with `--range-diff`, tweak the heuristic which matches up commits\n \tbetween the previous and current series of patches by adjusting the\n \tcreation/deletion cost fudge factor. See linkgit:git-range-diff[1])\n@@ -378,8 +378,8 @@ case is to show comparison with an older iteration of the same\n topic and the tool should find more correspondence between the two\n sets of patches.\n \n---notes[=<ref>]::\n---no-notes::\n+`--notes[=<ref>]`::\n+`--no-notes`::\n \tAppend the notes (see linkgit:git-notes[1]) for the commit\n \tafter the three-dash line.\n +\n@@ -394,17 +394,17 @@ configuration options in linkgit:git-notes[1] to use this workflow).\n The default is `--no-notes`, unless the `format.notes` configuration is\n set.\n \n---signature=<signature>::\n---no-signature::\n+`--signature=<signature>`::\n+`--no-signature`::\n \tAdd a signature to each message produced. Per RFC 3676 the signature\n-\tis separated from the body by a line with '-- ' on it. If the\n+\tis separated from the body by a line with \"-- \" on it. If the\n \tsignature option is omitted the signature defaults to the Git version\n \tnumber.\n \n---signature-file=<file>::\n-\tWorks just like --signature except the signature is read from a file.\n+`--signature-file=<file>`::\n+\tWorks just like `--signature` except the signature is read from a file.\n \n---suffix=.<sfx>::\n+`--suffix=.<sfx>`::\n \tInstead of using `.patch` as the suffix for generated\n \tfilenames, use specified suffix.  A common alternative is\n \t`--suffix=.txt`.  Leaving this empty will remove the `.patch`\n@@ -413,36 +413,36 @@ set.\n Note that the leading character does not have to be a dot; for example,\n you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tDo not print the names of the generated files to standard output.\n \n---no-binary::\n+`--no-binary`::\n \tDo not output contents of changes in binary files, instead\n \tdisplay a notice that those files changed.  Patches generated\n \tusing this option cannot be applied properly, but they are\n \tstill useful for code review.\n \n---zero-commit::\n+`--zero-commit`::\n   Output an all-zero hash in each patch's From header instead\n   of the hash of the commit.\n \n---no-base::\n---base[=<commit>]::\n+`--no-base`::\n+`--base[=<commit>]`::\n \tRecord the base tree information to identify the state the\n \tpatch series applies to.  See the BASE TREE INFORMATION section\n-\tbelow for details. If <commit> is \"auto\", a base commit is\n+\tbelow for details. If _<commit>_ is `auto`, a base commit is\n \tautomatically chosen. The `--no-base` option overrides a\n \t`format.useAutoBase` configuration.\n \n---root::\n-\tTreat the revision argument as a <revision-range>, even if it\n+`--root`::\n+\tTreat the revision argument as a _<revision-range>_, even if it\n \tis just a single commit (that would normally be treated as a\n-\t<since>).  Note that root commits included in the specified\n+\t_<since>_).  Note that root commits included in the specified\n \trange are always formatted as creation patches, independently\n \tof this flag.\n \n---progress::\n+`--progress`::\n \tShow progress reports on stderr as patches are generated.\n \n CONFIGURATION\n@@ -453,7 +453,7 @@ outputting more than one patch, add \"To:\" or \"Cc:\" headers, configure\n attachments, change the patch output directory, and sign off patches\n with configuration variables.\n \n-------------\n+----\n [format]\n \theaders = \"Organization: git-foo\\n\"\n \tsubjectPrefix = CHANGE\n@@ -467,17 +467,16 @@ with configuration variables.\n \tcoverLetter = auto\n \tcommitListFormat = shortlog\n \tcoverFromDescription = auto\n-------------\n-\n+----\n \n DISCUSSION\n ----------\n \n-The patch produced by 'git format-patch' is in UNIX mailbox format,\n+The patch produced by `git format-patch` is in UNIX mailbox format,\n with a fixed \"magic\" time stamp to indicate that the file is output\n from format-patch rather than a real mailbox, like so:\n \n-------------\n+----\n From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001\n From: Tony Luck <tony.luck@intel.com>\n Date: Tue, 13 Jul 2010 11:42:54 -0700\n@@ -492,7 +491,7 @@ arch/arm config files were slimmed down using a python script\n \n Do the same for ia64 so we can have sleek & trim looking\n ...\n-------------\n+----\n \n Typically it will be placed in a MUA's drafts folder, edited to add\n timely commentary that should not go in the changelog after the three\n@@ -502,12 +501,12 @@ can save interesting patches in a UNIX mailbox and apply them with\n linkgit:git-am[1].\n \n When a patch is part of an ongoing discussion, the patch generated by\n-'git format-patch' can be tweaked to take advantage of the 'git am\n---scissors' feature.  After your response to the discussion comes a\n+`git format-patch` can be tweaked to take advantage of the `git am\n+--scissors` feature.  After your response to the discussion comes a\n line that consists solely of \"`-- >8 --`\" (scissors and perforation),\n followed by the patch with unnecessary header fields removed:\n \n-------------\n+----\n ...\n > So we should do such-and-such.\n \n@@ -518,7 +517,7 @@ Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet\n \n arch/arm config files were slimmed down using a python script\n ...\n-------------\n+----\n \n When sending a patch this way, most often you are sending your own\n patch, so in addition to the \"`From $SHA1 $magic_timestamp`\" marker you\n@@ -540,7 +539,7 @@ two common types of corruption:\n One way to test if your MUA is set up correctly is:\n \n * Send the patch to yourself, exactly the way you would, except\n-  with To: and Cc: lines that do not contain the list and\n+  with `To:` and `Cc:` lines that do not contain the list and\n   maintainer address.\n \n * Save that patch to a file in UNIX mailbox format.  Call it a.patch,\n@@ -561,12 +560,12 @@ If it does not apply correctly, there can be various reasons.\n   this case.\n \n * The MUA corrupted your patch; \"am\" would complain that\n-  the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and\n-  see what 'patch' file contains and check for the common\n-  corruption patterns mentioned above.\n+  the patch does not apply.  Look in the `.git/rebase-apply/` subdirectory and\n+   see what `patch` file contains and check for the common\n+   corruption patterns mentioned above.\n \n-* While at it, check the 'info' and 'final-commit' files as well.\n-  If what is in 'final-commit' is not exactly what you would want to\n+* While at it, check the `info` and `final-commit` files as well.\n+  If what is in `final-commit` is not exactly what you would want to\n   see in the commit log message, it is very likely that the\n   receiver would end up hand editing the log message when applying\n   your patch.  Things like \"Hi, this is my first patch.\\n\" in the\n@@ -582,11 +581,11 @@ GMail\n ~~~~~\n GMail does not have any way to turn off line wrapping in the web\n interface, so it will mangle any emails that you send.  You can however\n-use \"git send-email\" and send your patches through the GMail SMTP server, or\n+use `git send-email` and send your patches through the GMail SMTP server, or\n use any IMAP email client to connect to the google IMAP server and forward\n the emails through that.\n \n-For hints on using 'git send-email' to send your patches through the\n+For hints on using `git send-email` to send your patches through the\n GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1].\n \n For hints on submission using the IMAP interface, see the EXAMPLE\n@@ -595,7 +594,7 @@ section of linkgit:git-imap-send[1].\n Thunderbird\n ~~~~~~~~~~~\n By default, Thunderbird will both wrap emails as well as flag\n-them as being 'format=flowed', both of which will make the\n+them as being `format=flowed`, both of which will make the\n resulting email unusable by Git.\n \n There are three different approaches: use an add-on to turn off line wraps,\n@@ -609,14 +608,14 @@ Install the Toggle Line Wrap add-on that is available from\n https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap\n It adds a button \"Line Wrap\" to the composer's toolbar\n that you can tick off. Now you can compose the message as you otherwise do\n-(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to\n+(cut + paste, `git format-patch` | `git imap-send`, etc), but you have to\n insert line breaks manually in any text that you type.\n \n As a bonus feature, the add-on can detect patch text in the composer\n and warns when line wrapping has not yet been turned off.\n \n The add-on requires a few tweaks of the advanced configuration\n-(about:config). These are listed on the download page.\n+(`about:config`). These are listed on the download page.\n \n Approach #2 (configuration)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^\n@@ -643,7 +642,7 @@ Toggle it to make sure it is set to `false`. Also, search for\n    Toggle it to make sure it is set to `false`.\n \n After that is done, you should be able to compose email as you\n-otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc),\n+otherwise would (cut + paste, `git format-patch` | `git imap-send`, etc),\n and the patches will not be mangled.\n \n Approach #3 (external editor)\n@@ -660,14 +659,14 @@ External Editor from https://globs.org/articles.php?lng=en&pg=8\n    \"Composition & Addressing\" panel of the account to be used to\n    send the patch.\n \n-3. In the main Thunderbird window, 'before' you open the compose\n+3. In the main Thunderbird window, _before_ you open the compose\n    window for the patch, use Tools->about:config to set the\n    following to the indicated values:\n +\n-----------\n+----\n \tmailnews.send_plaintext_flowed  => false\n \tmailnews.wraplength             => 0\n-----------\n+----\n \n 4. Open a compose window and click the external editor icon.\n \n@@ -677,11 +676,11 @@ External Editor from https://globs.org/articles.php?lng=en&pg=8\n Side note: it may be possible to do step 2 with\n about:config and the following settings but no one's tried yet.\n \n-----------\n+----\n \tmail.html_compose                       => false\n \tmail.identity.default.compose_html      => false\n \tmail.identity.id?.compose_html          => false\n-----------\n+----\n \n There is a script in contrib/thunderbird-patch-inline which can help\n you include patches with Thunderbird in an easy way. To use it, do the\n@@ -708,15 +707,15 @@ BASE TREE INFORMATION\n \n The base tree information block is used for maintainers or third party\n testers to know the exact state the patch series applies to. It consists\n-of the 'base commit', which is a well-known commit that is part of the\n+of the \"base commit\", which is a well-known commit that is part of the\n stable part of the project history everybody else works off of, and zero\n-or more 'prerequisite patches', which are well-known patches in flight\n-that is not yet part of the 'base commit' that need to be applied on top\n-of 'base commit' in topological order before the patches can be applied.\n+or more \"prerequisite patches\", which are well-known patches in flight\n+that is not yet part of the \"base commit\" that need to be applied on top\n+of \"base commit\" in topological order before the patches can be applied.\n \n-The 'base commit' is shown as \"base-commit: \" followed by the 40-hex of\n-the commit object name.  A 'prerequisite patch' is shown as\n-\"prerequisite-patch-id: \" followed by the 40-hex 'patch id', which can\n+The \"base commit\" is shown as \"`base-commit:` \" followed by the 40-hex of\n+the commit object name.  A \"prerequisite patch\" is shown as\n+\"`prerequisite-patch-id:` \" followed by the 40-hex \"patch id\", which can\n be obtained by passing the patch through the `git patch-id --stable`\n command.\n \n@@ -734,12 +733,12 @@ range), the base tree information block is shown at the end of the\n first message the command outputs (either the first patch, or the\n cover letter), like this:\n \n-------------\n+----\n base-commit: P\n prerequisite-patch-id: X\n prerequisite-patch-id: Y\n prerequisite-patch-id: Z\n-------------\n+----\n \n For non-linear topology, such as\n \n@@ -763,7 +762,7 @@ EXAMPLES\n --------\n \n * Extract commits between revisions R1 and R2, and apply them on top of\n-  the current branch using 'git am' to cherry-pick them:\n+  the current branch using `git am` to cherry-pick them:\n +\n ------------\n $ git format-patch -k --stdout R1..R2 | git am -3 -k\n@@ -778,7 +777,7 @@ $ git format-patch origin\n +\n For each commit a separate file is created in the current directory.\n \n-* Extract all commits that lead to 'origin' since the inception of the\n+* Extract all commits that lead to `origin` since the inception of the\n   project:\n +\n ------------\n@@ -794,7 +793,7 @@ $ git format-patch -M -B origin\n Additionally, it detects and handles renames and complete rewrites\n intelligently to produce a renaming patch.  A renaming patch reduces\n the amount of text output, and generally makes it easier to review.\n-Note that non-Git \"patch\" programs won't understand renaming patches, so\n+Note that non-Git `patch` programs won't understand renaming patches, so\n use it only when you know the recipient uses Git to apply your patch.\n \n * Extract three topmost commits from the current branch and format them\n-- \ngitgitgadget\n\n"},{"id":"548831","messageId":"94751ae58b9a492bc9a252442407b7475ea6dee6.1784841567.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.v2.git.1784841567.gitgitgadget@gmail.com","subject":"[PATCH v2 3/4] doc: convert git-send-email synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-23T21:19:25Z","receivedAt":"2026-07-23T21:19:39Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nReplace [verse] with [synopsis] in the SYNOPSIS block and remove\nsingle-quote formatting from the command name.\n\nBacktick-quote all option terms in the OPTIONS section, convert\nthe standalone placeholder _<encoding>_ in prose, fix single-quoted\nserver names to backtick form, and convert mbox(5) to `mbox`(5).\n\nAlso update config/sendemail.adoc: backtick-quote all configuration\nkey terms and fix a bare sendemail.aliasesFile reference in prose.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/config/sendemail.adoc |  92 ++++++++--------\n Documentation/git-send-email.adoc   | 162 ++++++++++++++--------------\n 2 files changed, 127 insertions(+), 127 deletions(-)\n\ndiff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc\nindex 1d700559b4..5499f91036 100644\n--- a/Documentation/config/sendemail.adoc\n+++ b/Documentation/config/sendemail.adoc\n@@ -1,25 +1,25 @@\n-sendemail.identity::\n+`sendemail.identity`::\n \tA configuration identity. When given, causes values in the\n \t`sendemail.<identity>` subsection to take precedence over\n \tvalues in the `sendemail` section. The default identity is\n \tthe value of `sendemail.identity`.\n \n-sendemail.smtpEncryption::\n+`sendemail.smtpEncryption`::\n \tSee linkgit:git-send-email[1] for description.  Note that this\n \tsetting is not subject to the `identity` mechanism.\n \n-sendemail.smtpSSLCertPath::\n+`sendemail.smtpSSLCertPath`::\n \tPath to ca-certificates (either a directory or a single file).\n \tSet it to an empty string to disable certificate verification.\n \n-sendemail.smtpSSLClientCert::\n+`sendemail.smtpSSLClientCert`::\n \tPath to the client certificate file to present if requested by the\n \tserver. This is required when the server is set up to verify client\n \tcertificates. If the corresponding private key is not included in the\n \tfile, it must be supplied using `sendemail.smtpSSLClientKey` or the\n \t`--smtp-ssl-client-key` option.\n \n-sendemail.smtpSSLClientKey::\n+`sendemail.smtpSSLClientKey`::\n \tPath to the client private key file that corresponds to the client\n \tcertificate. To avoid misconfiguration, this configuration must be used\n \tin conjunction with `sendemail.smtpSSLClientCert` or the\n@@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey::\n \tthe certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more\n \tdetails.\n \n-sendemail.<identity>.*::\n-\tIdentity-specific versions of the `sendemail.*` parameters\n+`sendemail.<identity>.<config>`::\n+\tIdentity-specific versions of the `sendemail.<config>` parameters\n \tfound below, taking precedence over those when this\n \tidentity is selected, through either the command-line or\n \t`sendemail.identity`.\n \n-sendemail.multiEdit::\n+`sendemail.multiEdit`::\n \tIf `true` (default), a single editor instance will be spawned to edit\n \tfiles you have to edit (patches when `--annotate` is used, and the\n \tsummary when `--compose` is used). If `false`, files will be edited one\n \tafter the other, spawning a new editor each time.\n \n-sendemail.confirm::\n+`sendemail.confirm`::\n \tSets the default for whether to confirm before sending. Must be\n \tone of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm`\n \tin the linkgit:git-send-email[1] documentation for the meaning of these\n \tvalues.\n \n-sendemail.mailmap::\n+`sendemail.mailmap`::\n \tIf `true`, makes linkgit:git-send-email[1] assume `--mailmap`,\n \totherwise assume `--no-mailmap`. `False` by default.\n \n-sendemail.mailmap.file::\n+`sendemail.mailmap.file`::\n \tThe location of a linkgit:git-send-email[1] specific augmenting\n \tmailmap file. The default mailmap and `mailmap.file` are loaded\n \tfirst. Thus, entries in this file take precedence over entries in\n \tthe default mailmap locations. See linkgit:gitmailmap[5].\n \n-sendemail.mailmap.blob::\n+`sendemail.mailmap.blob`::\n \tLike `sendemail.mailmap.file`, but consider the value as a reference\n \tto a blob in the repository. Entries in `sendemail.mailmap.file`\n \ttake precedence over entries here. See linkgit:gitmailmap[5].\n \n-sendemail.aliasesFile::\n+`sendemail.aliasesFile`::\n \tTo avoid typing long email addresses, point this to one or more\n \temail aliases files.  You must also supply `sendemail.aliasFileType`.\n \n-sendemail.aliasFileType::\n-\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n+`sendemail.aliasFileType`::\n+\tFormat of the file(s) specified in `sendemail.aliasesFile`. Must be\n \tone of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`.\n +\n What an alias file in each format looks like can be found in\n@@ -75,7 +75,7 @@ differences and limitations from the standard formats are\n described below:\n +\n --\n-sendmail;;\n+`sendmail`;;\n *\tQuoted aliases and quoted addresses are not supported: lines that\n \tcontain a `\"` symbol are ignored.\n *\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n@@ -85,54 +85,54 @@ sendmail;;\n \texplicitly unsupported constructs, and any other lines that are not\n \trecognized by the parser.\n --\n-sendemail.annotate::\n-sendemail.bcc::\n-sendemail.cc::\n-sendemail.ccCmd::\n-sendemail.chainReplyTo::\n-sendemail.envelopeSender::\n-sendemail.from::\n-sendemail.headerCmd::\n-sendemail.signedOffByCc::\n-sendemail.smtpPass::\n-sendemail.suppressCc::\n-sendemail.suppressFrom::\n-sendemail.to::\n-sendemail.toCmd::\n-sendemail.smtpDomain::\n-sendemail.smtpServer::\n-sendemail.smtpServerPort::\n-sendemail.smtpServerOption::\n-sendemail.smtpUser::\n-sendemail.imapSentFolder::\n-sendemail.useImapOnly::\n-sendemail.thread::\n-sendemail.transferEncoding::\n-sendemail.validate::\n-sendemail.xmailer::\n+`sendemail.annotate`::\n+`sendemail.bcc`::\n+`sendemail.cc`::\n+`sendemail.ccCmd`::\n+`sendemail.chainReplyTo`::\n+`sendemail.envelopeSender`::\n+`sendemail.from`::\n+`sendemail.headerCmd`::\n+`sendemail.signedOffByCc`::\n+`sendemail.smtpPass`::\n+`sendemail.suppressCc`::\n+`sendemail.suppressFrom`::\n+`sendemail.to`::\n+`sendemail.toCmd`::\n+`sendemail.smtpDomain`::\n+`sendemail.smtpServer`::\n+`sendemail.smtpServerPort`::\n+`sendemail.smtpServerOption`::\n+`sendemail.smtpUser`::\n+`sendemail.imapSentFolder`::\n+`sendemail.useImapOnly`::\n+`sendemail.thread`::\n+`sendemail.transferEncoding`::\n+`sendemail.validate`::\n+`sendemail.xmailer`::\n \tThese configuration variables all provide a default for\n \tlinkgit:git-send-email[1] command-line options. See its\n \tdocumentation for details.\n \n-sendemail.outlookidfix::\n+`sendemail.outlookidfix`::\n \tIf `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`,\n \tand if `false` assume `--no-outlook-id-fix`. If not specified, it will\n \tbehave the same way as if `--outlook-id-fix` is not specified.\n \n-sendemail.signedOffCc (deprecated)::\n+`sendemail.signedOffCc` (deprecated)::\n \tDeprecated alias for `sendemail.signedOffByCc`.\n \n-sendemail.smtpBatchSize::\n+`sendemail.smtpBatchSize`::\n \tNumber of messages to be sent per connection, after that a relogin\n \twill happen.  If the value is `0` or undefined, send all messages in\n \tone connection.\n \tSee also the `--batch-size` option of linkgit:git-send-email[1].\n \n-sendemail.smtpReloginDelay::\n+`sendemail.smtpReloginDelay`::\n \tSeconds to wait before reconnecting to the smtp server.\n \tSee also the `--relogin-delay` option of linkgit:git-send-email[1].\n \n-sendemail.forbidSendmailVariables::\n+`sendemail.forbidSendmailVariables`::\n \tTo avoid common misconfiguration mistakes, linkgit:git-send-email[1]\n \twill abort with a warning if any configuration options for `sendmail`\n \texist. Set this variable to bypass the check.\ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex dea3b86460..5c9ab39944 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -8,11 +8,11 @@ git-send-email - Send a collection of patches as emails\n \n SYNOPSIS\n --------\n-[verse]\n-'git send-email' [<options>] (<file>|<directory>)...\n-'git send-email' [<options>] <format-patch-options>\n-'git send-email' --dump-aliases\n-'git send-email' --translate-aliases\n+[synopsis]\n+git send-email [<options>] (<file>|<directory>)...\n+git send-email [<options>] <format-patch-options>\n+git send-email --dump-aliases\n+git send-email --translate-aliases\n \n \n DESCRIPTION\n@@ -48,24 +48,24 @@ OPTIONS\n Composing\n ~~~~~~~~~\n \n---annotate::\n+`--annotate`::\n \tReview and edit each patch you're about to send. Default is the value\n \tof `sendemail.annotate`. See the CONFIGURATION section for\n \t`sendemail.multiEdit`.\n \n---bcc=<address>,...::\n+`--bcc=<address>,...`::\n \tSpecify a `Bcc:` value for each email. Default is the value of\n \t`sendemail.bcc`.\n +\n This option may be specified multiple times.\n \n---cc=<address>,...::\n+`--cc=<address>,...`::\n \tSpecify a starting `Cc:` value for each email.\n \tDefault is the value of `sendemail.cc`.\n +\n This option may be specified multiple times.\n \n---compose::\n+`--compose`::\n \tInvoke a text editor (see GIT_EDITOR in linkgit:git-var[1])\n \tto edit an introductory message for the patch series.\n +\n@@ -80,7 +80,7 @@ Missing `From` or `In-Reply-To` headers will be prompted for.\n +\n See the CONFIGURATION section for `sendemail.multiEdit`.\n \n---from=<address>::\n+`--from=<address>`::\n \tSpecify the sender of the emails.  If not specified on the command line,\n \tthe value of the `sendemail.from` configuration option is used.  If\n \tneither the command-line option nor `sendemail.from` are set, then the\n@@ -88,12 +88,12 @@ See the CONFIGURATION section for `sendemail.multiEdit`.\n \tthe value of `GIT_AUTHOR_IDENT`, or `GIT_COMMITTER_IDENT` if that is not\n \tset, as returned by `git var -l`.\n \n---reply-to=<address>::\n+`--reply-to=<address>`::\n \tSpecify the address where replies from recipients should go to.\n \tUse this if replies to messages should go to another address than what\n \tis specified with the `--from` parameter.\n \n---in-reply-to=<identifier>::\n+`--in-reply-to=<identifier>`::\n \tMake the first mail (or all the mails with `--no-thread`) appear as a\n \treply to the given Message-ID, which avoids breaking threads to\n \tprovide a new patch series.\n@@ -115,8 +115,8 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:\n Only necessary if `--compose` is also set.  If `--compose`\n is not set, this will be prompted for.\n \n---outlook-id-fix::\n---no-outlook-id-fix::\n+`--outlook-id-fix`::\n+`--no-outlook-id-fix`::\n \tMicrosoft Outlook SMTP servers discard the Message-ID sent via email and\n \tassign a new random Message-ID, thus breaking threads.\n +\n@@ -126,15 +126,15 @@ threading. Use it only when you know that the server reports the\n rewritten Message-ID the same way as Outlook servers do.\n +\n Without this option specified, the fix is done by default when talking\n-to 'smtp.office365.com' or 'smtp-mail.outlook.com'. Use\n+to `smtp.office365.com` or `smtp-mail.outlook.com`. Use\n `--no-outlook-id-fix` to disable even when talking to these two servers.\n \n---subject=<string>::\n+`--subject=<string>`::\n \tSpecify the initial subject of the email thread.\n \tOnly necessary if `--compose` is also set.  If `--compose`\n \tis not set, this will be prompted for.\n \n---to=<address>,...::\n+`--to=<address>,...`::\n \tSpecify the primary recipient of the emails generated. Generally, this\n \twill be the upstream maintainer of the project involved. Default is the\n \tvalue of the `sendemail.to` configuration value; if that is unspecified,\n@@ -142,20 +142,20 @@ to 'smtp.office365.com' or 'smtp-mail.outlook.com'. Use\n +\n This option may be specified multiple times.\n \n---8bit-encoding=<encoding>::\n+`--8bit-encoding=<encoding>`::\n \tWhen encountering a non-ASCII message or subject that does not\n \tdeclare its encoding, add headers/quoting to indicate it is\n-\tencoded in <encoding>.  Default is the value of the\n+\tencoded in _<encoding>_.  Default is the value of the\n \t`sendemail.assume8bitEncoding`; if that is unspecified, this\n \twill be prompted for if any non-ASCII files are encountered.\n +\n Note that no attempts whatsoever are made to validate the encoding.\n \n---compose-encoding=<encoding>::\n+`--compose-encoding=<encoding>`::\n \tSpecify encoding of compose message. Default is the value of the\n \t`sendemail.composeEncoding`; if that is unspecified, UTF-8 is assumed.\n \n---transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::\n+`--transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)`::\n \tSpecify the transfer encoding to be used to send the message over SMTP.\n \t`7bit` will fail upon encountering a non-ASCII message. `quoted-printable`\n \tcan be useful when the repository contains files that contain carriage\n@@ -167,8 +167,8 @@ Note that no attempts whatsoever are made to validate the encoding.\n Default is the value of the `sendemail.transferEncoding` configuration\n value; if that is unspecified, default to `auto`.\n \n---xmailer::\n---no-xmailer::\n+`--xmailer`::\n+`--no-xmailer`::\n \tAdd (or prevent adding) the `X-Mailer:` header.  By default,\n \tthe header is added, but it can be turned off by setting the\n \t`sendemail.xmailer` configuration variable to `false`.\n@@ -176,7 +176,7 @@ value; if that is unspecified, default to `auto`.\n Sending\n ~~~~~~~\n \n---envelope-sender=<address>::\n+`--envelope-sender=<address>`::\n \tSpecify the envelope sender used to send the emails.\n \tThis is useful if your default address is not the address that is\n \tsubscribed to a list. In order to use the `From` address, set the\n@@ -185,7 +185,7 @@ Sending\n \t`sendemail.envelopeSender` configuration variable; if that is\n \tunspecified, choosing the envelope sender is left to your MTA.\n \n---sendmail-cmd=<command>::\n+`--sendmail-cmd=<command>`::\n \tSpecify a command to run to send the email. The command should\n \tbe sendmail-like; specifically, it must support the `-i` option.\n \tThe command will be executed in the shell if necessary.  Default\n@@ -193,7 +193,7 @@ Sending\n \t`--smtp-server` is also unspecified, `git send-email` will search\n \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH`.\n \n---smtp-encryption=<encryption>::\n+`--smtp-encryption=<encryption>`::\n \tSpecify in what way encrypting begins for the SMTP connection.\n \tValid values are `ssl` and `tls`. Any other value reverts to plain\n \t(unencrypted) SMTP, which defaults to port 25.\n@@ -207,14 +207,14 @@ Sending\n \tdocumentation or your server configuration to make sure\n \tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n \n---smtp-domain=<FQDN>::\n+`--smtp-domain=<FQDN>`::\n \tSpecify the Fully Qualified Domain Name (FQDN) used in the\n \tHELO/EHLO command to the SMTP server.  Some servers require the\n \tFQDN to match your IP address.  If not set, `git send-email` attempts\n \tto determine your FQDN automatically.  Default is the value of\n \t`sendemail.smtpDomain`.\n \n---smtp-auth=<mechanisms>::\n+`--smtp-auth=<mechanisms>`::\n \tWhitespace-separated list of allowed SMTP-AUTH mechanisms. This setting\n \tforces using only the listed mechanisms. Example:\n +\n@@ -229,7 +229,7 @@ is specified, all mechanisms supported by the SASL library can be used. The\n special value `none` maybe specified to completely disable authentication\n independently of `--smtp-user`.\n \n---smtp-pass[=<password>]::\n+`--smtp-pass[=<password>]`::\n \tPassword for SMTP-AUTH. The argument is optional: If no\n \targument is specified, then the empty string is used as\n \tthe password. Default is the value of `sendemail.smtpPass`,\n@@ -241,10 +241,10 @@ or on the command line. If a username has been specified (with\n specified (with `--smtp-pass` or `sendemail.smtpPass`), then\n a password is obtained using linkgit:git-credential[1].\n \n---no-smtp-auth::\n+`--no-smtp-auth`::\n \tDisable SMTP authentication. Short hand for `--smtp-auth=none`.\n \n---smtp-server=<host>::\n+`--smtp-server=<host>`::\n \tSpecify the outgoing SMTP server to use (e.g.\n \t`smtp.example.com` or a raw IP address).  If unspecified, and if\n \t`--sendmail-cmd` is also unspecified, the default is to search\n@@ -257,7 +257,7 @@ option.  This method does not support passing arguments or using plain\n command names.  For those use cases, consider using `--sendmail-cmd`\n instead.\n \n---smtp-server-port=<port>::\n+`--smtp-server-port=<port>`::\n \tSpecify a port different from the default port (SMTP\n \tservers typically listen to smtp port 25, but may also listen to\n \tsubmission port 587, or the common SSL smtp port 465);\n@@ -265,7 +265,7 @@ instead.\n \tare also accepted. The port can also be set with the\n \t`sendemail.smtpServerPort` configuration variable.\n \n---smtp-server-option=<option>::\n+`--smtp-server-option=<option>`::\n \tSpecify the outgoing SMTP server option to use.\n \tDefault value can be specified by the `sendemail.smtpServerOption`\n \tconfiguration option.\n@@ -274,15 +274,15 @@ The `--smtp-server-option` option must be repeated for each option you want\n to pass to the server. Likewise, different lines in the configuration files\n must be used for each option.\n \n---smtp-ssl::\n+`--smtp-ssl`::\n \tLegacy alias for `--smtp-encryption ssl`.\n \n---smtp-ssl-cert-path <path>::\n+`--smtp-ssl-cert-path <path>`::\n \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n \tcertificate validation (either a directory that has been processed\n \tby `c_rehash`, or a single file containing one or more PEM format\n \tcertificates concatenated together: see the description of the\n-\t`-CAfile` _<file>_ and the `-CApath` _<dir>_ options of\n+\t`-CAfile <file>` and the `-CApath <dir>` options of\n \thttps://docs.openssl.org/master/man1/openssl-verify/\n \t[OpenSSL's verify(1) manual page] for more information on these).\n \tSet it to an empty string to disable certificate verification.\n@@ -290,7 +290,7 @@ must be used for each option.\n \tvariable, if set, or the backing SSL library's compiled-in default\n \totherwise (which should be the best choice on most platforms).\n \n---smtp-ssl-client-cert <path>::\n+`--smtp-ssl-client-cert <path>`::\n \tPath to the client certificate file to present if requested by the\n \tserver. This option is required when the server is set up to verify\n \tclient certificates. If the corresponding private key is not included in\n@@ -299,7 +299,7 @@ must be used for each option.\n \tto the value of the `sendemail.smtpSSLClientCert` configuration\n \tvariable, if set.\n \n---smtp-ssl-client-key <path>::\n+`--smtp-ssl-client-key <path>`::\n \tPath to the client private key file that corresponds to the client\n \tcertificate. To avoid misconfiguration, this option must be used in\n \tconjunction with the `sendemail.smtpSSLClientKey` configuration variable\n@@ -309,17 +309,17 @@ must be used for each option.\n \tmore details. Defaults to the value of the `sendemail.smtpSSLClientKey`\n \tconfiguration variable, if set.\n \n---smtp-user=<user>::\n+`--smtp-user=<user>`::\n \tUsername for SMTP-AUTH. Default is the value of `sendemail.smtpUser`;\n \tif a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),\n \tthen authentication is not attempted.\n \n---smtp-debug=(0|1)::\n+`--smtp-debug=(0|1)`::\n \tEnable (1) or disable (0) debug output. If enabled, SMTP\n \tcommands and replies will be printed. Useful to debug TLS\n \tconnection and authentication problems.\n \n---imap-sent-folder=<folder>::\n+`--imap-sent-folder=<folder>`::\n \tSome email providers (e.g. iCloud) do not send a copy of the emails sent\n \tusing SMTP to the `Sent` folder or similar in your mailbox. Use this option\n \tto use `git imap-send` to send a copy of the emails to the folder specified\n@@ -331,8 +331,8 @@ must be used for each option.\n This feature requires setting up `git imap-send`. See linkgit:git-imap-send[1]\n for instructions.\n \n---use-imap-only::\n---no-use-imap-only::\n+`--use-imap-only`::\n+`--no-use-imap-only`::\n \tIf this is set, all emails will only be copied to the IMAP folder specified\n \twith `--imap-sent-folder` or `sendemail.imapSentFolder` and will not be sent\n \tto the recipients. Useful if you just want to create a draft of the emails\n@@ -344,8 +344,8 @@ for instructions.\n This feature requires setting up `git imap-send`. See linkgit:git-imap-send[1]\n for instructions.\n \n---batch-size=<num>::\n-\tSome email servers (e.g. 'smtp.163.com') limit the number of emails to be\n+`--batch-size=<num>`::\n+\tSome email servers (e.g. `smtp.163.com`) limit the number of emails to be\n \tsent per session (connection) and this will lead to a failure when\n \tsending many messages.  With this option, send-email will disconnect after\n \tsending _<num>_ messages and wait for a few seconds\n@@ -354,7 +354,7 @@ for instructions.\n \tretype your password every time this happens.  Defaults to the\n \t`sendemail.smtpBatchSize` configuration variable.\n \n---relogin-delay=<int>::\n+`--relogin-delay=<int>`::\n \tWaiting _<int>_ seconds before reconnecting to SMTP server. Used together\n \twith `--batch-size` option.  Defaults to the `sendemail.smtpReloginDelay`\n \tconfiguration variable.\n@@ -362,29 +362,29 @@ for instructions.\n Automating\n ~~~~~~~~~~\n \n---no-to::\n---no-cc::\n---no-bcc::\n+`--no-to`::\n+`--no-cc`::\n+`--no-bcc`::\n \tClear any list of `To:`, `Cc:`, `Bcc:` addresses previously\n \tset via config.\n \n---no-identity::\n+`--no-identity`::\n \tClear the previously read value of `sendemail.identity` set\n \tvia config, if any.\n \n---to-cmd=<command>::\n+`--to-cmd=<command>`::\n \tSpecify a command to execute once per patch file which\n \tshould generate patch file specific `To:` entries.\n \tOutput of this command must be single email address per line.\n \tDefault is the value of `sendemail.toCmd` configuration value.\n \n---cc-cmd=<command>::\n+`--cc-cmd=<command>`::\n \tSpecify a command to execute once per patch file which\n \tshould generate patch file specific `Cc:` entries.\n \tOutput of this command must be single email address per line.\n \tDefault is the value of `sendemail.ccCmd` configuration value.\n \n---header-cmd=<command>::\n+`--header-cmd=<command>`::\n \tSpecify a command that is executed once per outgoing message\n \tand output RFC 2822 style header lines to be inserted into\n \tthem. When the `sendemail.headerCmd` configuration variable is\n@@ -392,11 +392,11 @@ Automating\n \tat the command line, its value takes precedence over the\n \t`sendemail.headerCmd` configuration variable.\n \n---no-header-cmd::\n+`--no-header-cmd`::\n \tDisable any header command in use.\n \n---chain-reply-to::\n---no-chain-reply-to::\n+`--chain-reply-to`::\n+`--no-chain-reply-to`::\n \tIf this is set, each email will be sent as a reply to the previous\n \temail sent.  If disabled with `--no-chain-reply-to`, all emails after\n \tthe first will be sent as replies to the first email sent.  When using\n@@ -404,34 +404,34 @@ Automating\n \tentire patch series. Disabled by default, but the `sendemail.chainReplyTo`\n \tconfiguration variable can be used to enable it.\n \n---identity=<identity>::\n+`--identity=<identity>`::\n \tA configuration identity. When given, causes values in the\n \t`sendemail.<identity>` subsection to take precedence over\n \tvalues in the `sendemail` section. The default identity is\n \tthe value of `sendemail.identity`.\n \n---signed-off-by-cc::\n---no-signed-off-by-cc::\n+`--signed-off-by-cc`::\n+`--no-signed-off-by-cc`::\n \tIf this is set, add emails found in the `Signed-off-by` trailer or `Cc:`\n \tlines to the cc list. Default is the value of `sendemail.signedOffByCc`\n \tconfiguration value; if that is unspecified, default to\n \t`--signed-off-by-cc`.\n \n---cc-cover::\n---no-cc-cover::\n+`--cc-cover`::\n+`--no-cc-cover`::\n \tIf this is set, emails found in `Cc:` headers in the first patch of\n \tthe series (typically the cover letter) are added to the cc list\n \tfor each email set. Default is the value of `sendemail.ccCover`\n \tconfiguration value; if that is unspecified, default to `--no-cc-cover`.\n \n---to-cover::\n---no-to-cover::\n+`--to-cover`::\n+`--no-to-cover`::\n \tIf this is set, emails found in `To:` headers in the first patch of\n \tthe series (typically the cover letter) are added to the to list\n \tfor each email set. Default is the value of `sendemail.toCover`\n \tconfiguration value; if that is unspecified, default to `--no-to-cover`.\n \n---suppress-cc=<category>::\n+`--suppress-cc=<category>`::\n \tSpecify an additional category of recipients to suppress the\n \tauto-cc of:\n +\n@@ -456,14 +456,14 @@ Default is the value of `sendemail.suppressCc` configuration value; if\n that is unspecified, default to `self` if `--suppress-from` is\n specified, as well as `body` if `--no-signed-off-by-cc` is specified.\n \n---suppress-from::\n---no-suppress-from::\n+`--suppress-from`::\n+`--no-suppress-from`::\n \tIf this is set, do not add the `From:` address to the `Cc:` list.\n \tDefault is the value of `sendemail.suppressFrom` configuration\n \tvalue; if that is unspecified, default to `--no-suppress-from`.\n \n---thread::\n---no-thread::\n+`--thread`::\n+`--no-thread`::\n \tIf this is set, the `In-Reply-To` and `References` headers will be\n \tadded to each email sent.  Whether each mail refers to the\n \tprevious email (`deep` threading per `git format-patch`\n@@ -481,8 +481,8 @@ exists when `git send-email` is asked to add it (especially note that\n Failure to do so may not produce the expected result in the\n recipient's MUA.\n \n---mailmap::\n---no-mailmap::\n+`--mailmap`::\n+`--no-mailmap`::\n \tUse the mailmap file (see linkgit:gitmailmap[5]) to map all\n \taddresses to their canonical real name and email address. Additional\n \tmailmap data specific to `git send-email` may be provided using the\n@@ -492,7 +492,7 @@ recipient's MUA.\n Administering\n ~~~~~~~~~~~~~\n \n---confirm=<mode>::\n+`--confirm=<mode>`::\n \tConfirm just before sending:\n +\n --\n@@ -508,22 +508,22 @@ Default is the value of `sendemail.confirm` configuration value; if that\n is unspecified, default to `auto` unless any of the suppress options\n have been specified, in which case default to `compose`.\n \n---dry-run::\n+`--dry-run`::\n \tDo everything except actually send the emails.\n \n---format-patch::\n---no-format-patch::\n+`--format-patch`::\n+`--no-format-patch`::\n \tWhen an argument may be understood either as a reference or as a file name,\n \tchoose to understand it as a format-patch argument (`--format-patch`)\n \tor as a file name (`--no-format-patch`). By default, when such a conflict\n \toccurs, `git send-email` will fail.\n \n---quiet::\n+`--quiet`::\n \tMake `git send-email` less verbose.  One line per email should be\n \tall that is output.\n \n---validate::\n---no-validate::\n+`--validate`::\n+`--no-validate`::\n \tPerform sanity checks on patches.\n \tCurrently, validation means the following:\n +\n@@ -539,20 +539,20 @@ have been specified, in which case default to `compose`.\n Default is the value of `sendemail.validate`; if this is not set,\n default to `--validate`.\n \n---force::\n+`--force`::\n \tSend emails even if safety checks would prevent it.\n \n \n Information\n ~~~~~~~~~~~\n \n---dump-aliases::\n+`--dump-aliases`::\n \tInstead of the normal operation, dump the shorthand alias names from\n \tthe configured alias file(s), one per line in alphabetical order. Note\n \tthat this only includes the alias name and not its expanded email addresses.\n \tSee `sendemail.aliasesFile` for more information about aliases.\n \n---translate-aliases::\n+`--translate-aliases`::\n \tInstead of the normal operation, read from standard input and\n \tinterpret each line as an email alias. Translate it according to the\n \tconfigured alias file(s). Output each translated name and email\n@@ -718,7 +718,7 @@ include::format-patch-caveats.adoc[]\n \n SEE ALSO\n --------\n-linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)\n+linkgit:git-format-patch[1], linkgit:git-imap-send[1], `mbox`(5)\n \n GIT\n ---\n-- \ngitgitgadget\n\n"},{"id":"548832","messageId":"740b24631de2c2aff01dcb461f60121fbd11bfe1.1784841567.git.gitgitgadget@gmail.com","threadId":"66038","inReplyTo":"pull.2185.v2.git.1784841567.gitgitgadget@gmail.com","subject":"[PATCH v2 4/4] doc: convert git-request-pull synopsis and options to new style","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-07-23T21:19:26Z","receivedAt":"2026-07-23T21:19:41Z","isPatch":true,"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n * Replace [verse] with [synopsis] in the SYNOPSIS block\n * remove single-quote formatting from the command name\n * backtick-quote the flag\n * use _<placeholder>_ form for positional parameter terms\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-request-pull.adoc | 38 +++++++++++++++++------------\n 1 file changed, 23 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-request-pull.adoc b/Documentation/git-request-pull.adoc\nindex 15dcbb6d91..8523c4e6bb 100644\n--- a/Documentation/git-request-pull.adoc\n+++ b/Documentation/git-request-pull.adoc\n@@ -7,8 +7,8 @@ git-request-pull - Generates a summary of pending changes\n \n SYNOPSIS\n --------\n-[verse]\n-'git request-pull' [-p] <start> <URL> [<end>]\n+[synopsis]\n+git request-pull [-p] <start> <URL> [<end>]\n \n DESCRIPTION\n -----------\n@@ -19,28 +19,28 @@ begins with the branch description, summarizes\n the changes, and indicates from where they can be pulled.\n \n The upstream project is expected to have the commit named by\n-`<start>` and the output asks it to integrate the changes you made\n-since that commit, up to the commit named by `<end>`, by visiting\n-the repository named by `<URL>`.\n+_<start>_ and the output asks it to integrate the changes you made\n+since that commit, up to the commit named by _<end>_, by visiting\n+the repository named by _<URL>_.\n \n \n OPTIONS\n -------\n--p::\n+`-p`::\n \tInclude patch text in the output.\n \n-<start>::\n+_<start>_::\n \tCommit to start at.  This names a commit that is already in\n \tthe upstream history.\n \n-<URL>::\n+_<URL>_::\n \tThe repository URL to be pulled from.\n \n-<end>::\n-\tCommit to end at (defaults to HEAD).  This names the commit\n+_<end>_::\n+\tCommit to end at (defaults to `HEAD`).  This names the commit\n \tat the tip of the history you are asking to be pulled.\n +\n-When the repository named by `<URL>` has the commit at a tip of a\n+When the repository named by _<URL>_ has the commit at a tip of a\n ref that is different from the ref you have locally, you can use the\n `<local>:<remote>` syntax, to have its local name, a colon `:`, and\n its remote name.\n@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project.\n First you push that change to your public repository for others to\n see:\n \n-\tgit push https://git.ko.xz/project master\n+----\n+git push https://git.ko.xz/project master\n+----\n \n Then, you run this command:\n \n-\tgit request-pull v1.0 https://git.ko.xz/project master\n+----\n+git request-pull v1.0 https://git.ko.xz/project master\n+----\n \n which will produce a request to the upstream, summarizing the\n changes between the `v1.0` release and your `master`, to pull it\n@@ -67,11 +71,15 @@ from your public repository.\n If you pushed your change to a branch whose name is different from\n the one you have locally, e.g.\n \n-\tgit push https://git.ko.xz/project master:for-linus\n+----\n+git push https://git.ko.xz/project master:for-linus\n+----\n \n then you can ask that to be pulled with\n \n-\tgit request-pull v1.0 https://git.ko.xz/project master:for-linus\n+----\n+git request-pull v1.0 https://git.ko.xz/project master:for-linus\n+----\n \n \n GIT\n-- \ngitgitgadget\n"},{"id":"549235","messageId":"xmqqldato56l.fsf@gitster.g","threadId":"66038","inReplyTo":"pull.2185.v2.git.1784841567.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/4] A new batch of synopsis conversion","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-29T21:29:38Z","receivedAt":"2026-07-29T21:29:40Z","isPatch":true,"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> The conversion to synopsis continues. Now the commands are less common, so I\n> may propose larger PRs if it's ok.\n>\n> Changes since v1:\n>\n>  * swap formats following comments\n>  * switch all listing blocks to 4 dash fences\n\nAll of these changes look as expected.\n\nShall we mark the topic for 'next'?\n\nThanks.\n"}]}