A new batch of synopsis conversion
cover A new batch of synopsis conversion
The conversion to synopsis continues. Now the commands are less common, so I may propose larger PRs if it's ok.
Jean-Noël Avila (4):
doc: convert git-imap-send synopsis and options to new style
doc: convert git-format-patch synopsis and options to new style
doc: convert git-send-email synopsis and options to new style
doc: convert git-request-pull synopsis and options to new style
Documentation/config/imap.adoc | 2 +- Documentation/config/sendemail.adoc | 92 +++++----- Documentation/diff-options.adoc | 8 +- Documentation/git-format-patch.adoc | 264 ++++++++++++++-------------- Documentation/git-imap-send.adoc | 7 +- Documentation/git-request-pull.adoc | 38 ++-- Documentation/git-send-email.adoc | 162 ++++++++--------- 7 files changed, 292 insertions(+), 281 deletions(-)
base-commit: 08621c32d5536babd139ab1a9086349b3672edd6
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2185%2Fjnavila%2Fconvert_synopsis_202606-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2185/jnavila/convert_synopsis_202606-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2185
Signature · 1 line
gitgitgadget
PATCH 1/4 doc: convert git-imap-send synopsis and options to new style
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Convert git-imap-send from [verse]/single-quote style to the modern synopsis-block style:
- Replace [verse] with [synopsis] in SYNOPSIS block
- Backtick-quote all OPTIONS terms
- Backtick-quote all config keys in config/imap.adoc
- Backtick-quote bare config key references in prose
--- Documentation/config/imap.adoc | 2 +- Documentation/git-imap-send.adoc | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-)
Documentation/config/imap.adoc +1 -1
@@ -41,7 +41,7 @@ `imap.authMethod`:: Specify the authentication method for authenticating with the IMAP server. If Git was built with the NO_CURL option, or if your curl version is older - than 7.34.0, or if you're running git-imap-send with the `--no-curl` + than 7.34.0, or if you're running `git-imap-send` with the `--no-curl` option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER` and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP plaintext `LOGIN` command.
Documentation/git-imap-send.adoc +5 -2
@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism. Once the commits are ready to be sent, run the following command: - $ git format-patch --cover-letter -M --stdout origin/master | git imap-send + +--------- +$ git format-patch --cover-letter -M --stdout origin/master | git imap-send +--------- Just make sure to disable line wrapping in the email client (Gmail's web interface will wrap lines no matter what, so you need to use a real
@@ -217,7 +220,7 @@ users may wish to visit this web page for more information: SEE ALSO -------- -linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5) +linkgit:git-format-patch[1], linkgit:git-send-email[1], `mbox`(5) GIT ---
Signature · 1 line
gitgitgadget
PATCH 2/4 doc: convert git-format-patch synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.
Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.
Also update the included files:
- diff-options.adoc: backtick-quote the git-format-patch-specific option terms (-p, --no-stat, --max-depth=<depth>)
- format-patch-caveats.adoc: convert patch(1) to patch(1)
--- Documentation/diff-options.adoc | 8 +- Documentation/git-format-patch.adoc | 264 ++++++++++++++-------------- 2 files changed, 136 insertions(+), 136 deletions(-)
Documentation/diff-options.adoc +4 -4
@@ -13,8 +13,8 @@ endif::git-diff[] endif::git-format-patch[] ifdef::git-format-patch[] --p:: ---no-stat:: +`-p`:: +`--no-stat`:: Generate plain patches without any diffstats. endif::git-format-patch[]
@@ -893,8 +893,8 @@ endif::git-format-patch[] reverted with `--ita-visible-in-index`. Both options are experimental and could be removed in future. ---max-depth=<depth>:: - For each pathspec given on command line, descend at most `<depth>` +`--max-depth=<depth>`:: + For each pathspec given on command line, descend at most _<depth>_ levels of directories. A value of `-1` means no limit. Cannot be combined with wildcards in the pathspec. Given a tree containing `foo/bar/baz`, the following list shows the
Documentation/git-format-patch.adoc +132 -132
596 lines not on this page · raw message
Signature · 1 line
gitgitgadget
PATCH 3/4 doc: convert git-send-email synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.
Backtick-quote all option terms in the OPTIONS section, convert the standalone placeholder _<encoding>_ in prose, fix single-quoted server names to backtick form, and convert mbox(5) to mbox(5).
Also update config/sendemail.adoc: backtick-quote all configuration key terms and fix a bare sendemail.aliasesFile reference in prose.
--- Documentation/config/sendemail.adoc | 92 ++++++++-------- Documentation/git-send-email.adoc | 162 ++++++++++++++-------------- 2 files changed, 127 insertions(+), 127 deletions(-)
Documentation/config/sendemail.adoc +46 -46
@@ -1,25 +1,25 @@ -sendemail.identity:: +`sendemail.identity`:: A configuration identity. When given, causes values in the `sendemail.<identity>` subsection to take precedence over values in the `sendemail` section. The default identity is the value of `sendemail.identity`. -sendemail.smtpEncryption:: +`sendemail.smtpEncryption`:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the `identity` mechanism. -sendemail.smtpSSLCertPath:: +`sendemail.smtpSSLCertPath`:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. -sendemail.smtpSSLClientCert:: +`sendemail.smtpSSLClientCert`:: Path to the client certificate file to present if requested by the server. This is required when the server is set up to verify client certificates. If the corresponding private key is not included in the file, it must be supplied using `sendemail.smtpSSLClientKey` or the `--smtp-ssl-client-key` option. -sendemail.smtpSSLClientKey:: +`sendemail.smtpSSLClientKey`:: Path to the client private key file that corresponds to the client certificate. To avoid misconfiguration, this configuration must be used in conjunction with `sendemail.smtpSSLClientCert` or the
@@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey:: the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more details. -sendemail.<identity>.*:: - Identity-specific versions of the `sendemail.*` parameters +`sendemail.<identity>.<config>`:: + Identity-specific versions of the `sendemail.<config>` parameters found below, taking precedence over those when this identity is selected, through either the command-line or `sendemail.identity`. -sendemail.multiEdit:: +`sendemail.multiEdit`:: If `true` (default), a single editor instance will be spawned to edit files you have to edit (patches when `--annotate` is used, and the summary when `--compose` is used). If `false`, files will be edited one after the other, spawning a new editor each time. -sendemail.confirm:: +`sendemail.confirm`:: Sets the default for whether to confirm before sending. Must be one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm` in the linkgit:git-send-email[1] documentation for the meaning of these values. -sendemail.mailmap:: +`sendemail.mailmap`:: If `true`, makes linkgit:git-send-email[1] assume `--mailmap`, otherwise assume `--no-mailmap`. `False` by default. -sendemail.mailmap.file:: +`sendemail.mailmap.file`:: The location of a linkgit:git-send-email[1] specific augmenting mailmap file. The default mailmap and `mailmap.file` are loaded first. Thus, entries in this file take precedence over entries in the default mailmap locations. See linkgit:gitmailmap[5]. -sendemail.mailmap.blob:: +`sendemail.mailmap.blob`:: Like `sendemail.mailmap.file`, but consider the value as a reference to a blob in the repository. Entries in `sendemail.mailmap.file` take precedence over entries here. See linkgit:gitmailmap[5]. -sendemail.aliasesFile:: +`sendemail.aliasesFile`:: To avoid typing long email addresses, point this to one or more email aliases files. You must also supply `sendemail.aliasFileType`. -sendemail.aliasFileType:: - Format of the file(s) specified in sendemail.aliasesFile. Must be +`sendemail.aliasFileType`:: + Format of the file(s) specified in `sendemail.aliasesFile`. Must be one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`. + What an alias file in each format looks like can be found in
@@ -75,7 +75,7 @@ differences and limitations from the standard formats are described below: + -- -sendmail;; +`sendmail`;; * Quoted aliases and quoted addresses are not supported: lines that contain a `"` symbol are ignored. * Redirection to a file (`/path/name`) or pipe (`|command`) is not
@@ -85,54 +85,54 @@ sendmail;; explicitly unsupported constructs, and any other lines that are not recognized by the parser. -- -sendemail.annotate:: -sendemail.bcc:: -sendemail.cc:: -sendemail.ccCmd:: -sendemail.chainReplyTo:: -sendemail.envelopeSender:: -sendemail.from:: -sendemail.headerCmd:: -sendemail.signedOffByCc:: -sendemail.smtpPass:: -sendemail.suppressCc:: -sendemail.suppressFrom:: -sendemail.to:: -sendemail.toCmd:: -sendemail.smtpDomain:: -sendemail.smtpServer:: -sendemail.smtpServerPort:: -sendemail.smtpServerOption:: -sendemail.smtpUser:: -sendemail.imapSentFolder:: -sendemail.useImapOnly:: -sendemail.thread:: -sendemail.transferEncoding:: -sendemail.validate:: -sendemail.xmailer:: +`sendemail.annotate`:: +`sendemail.bcc`:: +`sendemail.cc`:: +`sendemail.ccCmd`:: +`sendemail.chainReplyTo`:: +`sendemail.envelopeSender`:: +`sendemail.from`:: +`sendemail.headerCmd`:: +`sendemail.signedOffByCc`:: +`sendemail.smtpPass`:: +`sendemail.suppressCc`:: +`sendemail.suppressFrom`:: +`sendemail.to`:: +`sendemail.toCmd`:: +`sendemail.smtpDomain`:: +`sendemail.smtpServer`:: +`sendemail.smtpServerPort`:: +`sendemail.smtpServerOption`:: +`sendemail.smtpUser`:: +`sendemail.imapSentFolder`:: +`sendemail.useImapOnly`:: +`sendemail.thread`:: +`sendemail.transferEncoding`:: +`sendemail.validate`:: +`sendemail.xmailer`:: These configuration variables all provide a default for linkgit:git-send-email[1] command-line options. See its documentation for details. -sendemail.outlookidfix:: +`sendemail.outlookidfix`:: If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`, and if `false` assume `--no-outlook-id-fix`. If not specified, it will behave the same way as if `--outlook-id-fix` is not specified. -sendemail.signedOffCc (deprecated):: +`sendemail.signedOffCc` (deprecated):: Deprecated alias for `sendemail.signedOffByCc`. -sendemail.smtpBatchSize:: +`sendemail.smtpBatchSize`:: Number of messages to be sent per connection, after that a relogin will happen. If the value is `0` or undefined, send all messages in one connection. See also the `--batch-size` option of linkgit:git-send-email[1]. -sendemail.smtpReloginDelay:: +`sendemail.smtpReloginDelay`:: Seconds to wait before reconnecting to the smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. -sendemail.forbidSendmailVariables:: +`sendemail.forbidSendmailVariables`:: To avoid common misconfiguration mistakes, linkgit:git-send-email[1] will abort with a warning if any configuration options for `sendmail` exist. Set this variable to bypass the check.
Documentation/git-send-email.adoc +81 -81
473 lines not on this page · raw message
Signature · 1 line
gitgitgadget
PATCH 4/4 doc: convert git-request-pull synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
* Replace [verse] with [synopsis] in the SYNOPSIS block
* remove single-quote formatting from the command name
* backtick-quote the flag
* use _<placeholder>_ form for positional parameter terms
--- Documentation/git-request-pull.adoc | 38 +++++++++++++++++------------ 1 file changed, 23 insertions(+), 15 deletions(-)
Documentation/git-request-pull.adoc +23 -15
@@ -7,8 +7,8 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- -[verse] -'git request-pull' [-p] <start> <URL> [<end>] +[synopsis] +git request-pull [-p] <start> <URL> [<end>] DESCRIPTION -----------
@@ -19,28 +19,28 @@ begins with the branch description, summarizes the changes, and indicates from where they can be pulled. The upstream project is expected to have the commit named by -`<start>` and the output asks it to integrate the changes you made -since that commit, up to the commit named by `<end>`, by visiting -the repository named by `<URL>`. +_<start>_ and the output asks it to integrate the changes you made +since that commit, up to the commit named by _<end>_, by visiting +the repository named by _<URL>_. OPTIONS ------- --p:: +`-p`:: Include patch text in the output. -<start>:: +_<start>_:: Commit to start at. This names a commit that is already in the upstream history. -<URL>:: +_<URL>_:: The repository URL to be pulled from. -<end>:: - Commit to end at (defaults to HEAD). This names the commit +_<end>_:: + Commit to end at (defaults to `HEAD`). This names the commit at the tip of the history you are asking to be pulled. + -When the repository named by `<URL>` has the commit at a tip of a +When the repository named by _<URL>_ has the commit at a tip of a ref that is different from the ref you have locally, you can use the `<local>:<remote>` syntax, to have its local name, a colon `:`, and its remote name.
@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project. First you push that change to your public repository for others to see: - git push https://git.ko.xz/project master +----- +git push https://git.ko.xz/project master +----- Then, you run this command: - git request-pull v1.0 https://git.ko.xz/project master +------ +git request-pull v1.0 https://git.ko.xz/project master +------ which will produce a request to the upstream, summarizing the changes between the `v1.0` release and your `master`, to pull it
@@ -67,11 +71,15 @@ from your public repository. If you pushed your change to a branch whose name is different from the one you have locally, e.g. - git push https://git.ko.xz/project master:for-linus +----- +git push https://git.ko.xz/project master:for-linus +----- then you can ask that to be pulled with - git request-pull v1.0 https://git.ko.xz/project master:for-linus +----- +git request-pull v1.0 https://git.ko.xz/project master:for-linus +----- GIT
Signature · 1 line
gitgitgadget
Re: [PATCH 2/4] doc: convert git-format-patch synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetQuoted 3 lines · Jean-Noël Avila via GitGitGadget
Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.
OK.
Documentation/git-format-patch.adoc BASE TREE INFORMATION · line 715
Quoted 9 lines
Documentation/git-format-patch.adoc +4
-0@@ -708,15 +708,15 @@ BASE TREE INFORMATION The base tree information block is used for maintainers or third party testers to know the exact state the patch series applies to. It consists +of the "base commit", which is a well-known commit that is part of the stable part of the project history everybody else works off of, and zero +or more "prerequisite patches", which are well-known patches in flight +that is not yet part of the "base commit" that need to be applied on top +of "base commit" in topological order before the patches can be applied.
GIven that the last part of this hunk below uses backtick-quoting for prerequisite patch and patch id, shouldn't the references to base commit, and prerequisite patch(es) in the above also be backtick quoted for consistency?
Quoted 5 lines
Documentation/git-format-patch.adoc +3
-0+The "base commit" is shown as "base-commit: " followed by the 40-hex of +the commit object name. A `prerequisite patch` is shown as +"prerequisite-patch-id: " followed by the 40-hex `patch id`, which can be obtained by passing the patch through the `git patch-id --stable` command.
Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetQuoted 23 lines · Jean-Noël Avila via GitGitGadget
(quoted diff) +6
-3@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project. First you push that change to your public repository for others to see: - git push https://git.ko.xz/project master +----- +git push https://git.ko.xz/project master +----- Then, you run this command: - git request-pull v1.0 https://git.ko.xz/project master +------ +git request-pull v1.0 https://git.ko.xz/project master +------ which will produce a request to the upstream, summarizing the changes between the `v1.0` release and your `master`, to pull it@@ -67,11 +71,15 @@ from your public repository. If you pushed your change to a branch whose name is different from the one you have locally, e.g. - git push https://git.ko.xz/project master:for-linus
Review from your public repository. · line 82
Quoted 10 lines
(quoted diff) +6
-1+----- +git push https://git.ko.xz/project master:for-linus +----- then you can ask that to be pulled with - git request-pull v1.0 https://git.ko.xz/project master:for-linus +----- +git request-pull v1.0 https://git.ko.xz/project master:for-linus +-----
Is there a widely accepted guideline among AsciiDoc users governing how many dashes should delimit these blocks, other than "at least four, with the opening and closing counts matching"? If so, what is it? We see five, six, five, and five dashes in the proposed changes above, and in '[PATCH 1/4]' we saw nine. Even if varying counts are functionally equivalent, the inconsistency is a bit distracting.
Thanks.
[Footnote]
* an excerpt from [PATCH 1/4]
Documentation/git-imap-send.adoc +4 -1
@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism. Once the commits are ready to be sent, run the following command: - $ git format-patch --cover-letter -M --stdout origin/master | git imap-send + +--------- +$ git format-patch --cover-letter -M --stdout origin/master | git imap-send +---------
Re: [PATCH 2/4] doc: convert git-format-patch synopsis and options to new style
In reply to Junio C HamanoQuoted 16 lines · On Monday, 20 July 2026 01:40:17 CEST Junio C Hamano wrote:
Quoted 3 lines · Jean-Noël Avila via GitGitGadget
Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.
OK.
Quoted 9 lines
Documentation/git-format-patch.adoc +1
-0@@ -708,15 +708,15 @@ BASE TREE INFORMATION The base tree information block is used for maintainers or third party testers to know the exact state the patch series applies to. It consists +of the "base commit", which is a well-known commit that is part of the stable part of the project history everybody else works off of, and zero
Quoted 9 lines
Documentation/git-format-patch.adoc BASE TREE INFORMATION · line 715
Quoted 3 lines
Documentation/git-format-patch.adoc +3
-0+or more "prerequisite patches", which are well-known patches in flight +that is not yet part of the "base commit" that need to be applied on top +of "base commit" in topological order before the patches can be applied.GIven that the last part of this hunk below uses backtick-quoting for
prerequisite patchandpatch id, shouldn't the references tobase commit, andprerequisite patch(es)in the above also be backtick quoted for consistency?
In fact, the formatting were swapped. For proper rendering and preservation of spaces, it should be:
The "base commit" is shown as "base-commit: " followed by the 40-hex of the commit object name. A "prerequisite patch" is shown as "prerequisite-patch-id: " followed by the 40-hex "patch id", which can be obtained by passing the patch through the git patch-id --stable command.
Only the constant strings are back-ticked. The others are only quoted.
Will reroll.
Quoted 6 lines
Quoted 6 lines
Documentation/git-format-patch.adoc +3
-0+The "base commit" is shown as "base-commit: " followed by the 40-hex of +the commit object name. A `prerequisite patch` is shown as +"prerequisite-patch-id: " followed by the 40-hex `patch id`, which can be obtained by passing the patch through the `git patch-id --stable` command.
Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style
In reply to Junio C HamanoQuoted 2 lines · On Monday, 20 July 2026 01:47:02 CEST Junio C Hamano wrote:
Review the `v1.0` release, and want it to be integrated into
Quoted 1 line · Jean-Noël Avila via GitGitGadget
(quoted diff) +0
-0@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into
the
Documentation/git-imap-
Quoted 49 lines
Quoted 24 lines
project.>
First you push that change to your public repository for others tosee:
(quoted diff) +6
-3- git push https://git.ko.xz/project master +----- +git push https://git.ko.xz/project master +----- Then, you run this command: - git request-pull v1.0 https://git.ko.xz/project master +------ +git request-pull v1.0 https://git.ko.xz/project master +------ which will produce a request to the upstream, summarizing the changes between the `v1.0` release and your `master`, to pull it@@ -67,11 +71,15 @@ from your public repository. If you pushed your change to a branch whose name is different from the one you have locally, e.g. - git push https://git.ko.xz/project master:for-linusReview from your public repository. · line 83
Quoted 10 lines
(quoted diff) +6
-1+----- +git push https://git.ko.xz/project master:for-linus +----- then you can ask that to be pulled with - git request-pull v1.0 https://git.ko.xz/project master:for-linus +----- +git request-pull v1.0 https://git.ko.xz/project master:for-linus +-----Is there a widely accepted guideline among AsciiDoc users governing how many dashes should delimit these blocks, other than "at least four, with the opening and closing counts matching"? If so, what is it? We see five, six, five, and five dashes in the proposed changes above, and in '[PATCH 1/4]' we saw nine. Even if varying counts are functionally equivalent, the inconsistency is a bit distracting.
Thanks.
[Footnote]
* an excerpt from [PATCH 1/4]
Documentation/git-imap- renamed from Documentation/git-imap-send.adoc +0
-0
send.adoc
Documentation/git-imap-send.adoc supports only `XOAUTH2` as the mechanism. · line 195
Quoted 8 lines
index
538b91afc0..dd1e0a3718100644Documentation/git-imap-send.adoc +0
-1@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism. Once the commits are ready to be sent, run the following command: - $ git format-patch --cover-letter -M --stdout origin/master | git imap-
send
Documentation/git-imap-send.adoc supports only `XOAUTH2` as the mechanism. · line 198
Quoted 4 lines
Documentation/git-imap-send.adoc +4
-0+ +--------- +$ git format-patch --cover-letter -M --stdout origin/master | git imap-send +---------
"Widely accepted", I do not know. I would better frame it as "because at least four is needed and I'm lazy, then it's four". I'm not expert enough the asciidoc specification to have a definitive answer of mine, but the asciidoctor specification says exactly four [1]
We could indeed apply the rule of 4 dashes by default.
Note that this only applies because it is a listing block which does not accept nesting.
I will reroll.
[1]: https://docs.asciidoctor.org/asciidoc/latest/verbatim/listing-blocks/
#delimited-listing-block
Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style
Quoted 11 lines · Jean-Noël AVILA
"Widely accepted", I do not know. I would better frame it as "because at least four is needed and I'm lazy, then it's four". I'm not expert enough the asciidoc specification to have a definitive answer of mine, but the asciidoctor specification says exactly four [1]
We could indeed apply the rule of 4 dashes by default.
Note that this only applies because it is a listing block which does not accept nesting.
I will reroll.
Thanks. Sounds like a good plan to me.
v2 cover A new batch of synopsis conversion
In reply to Jean-Noël Avila via GitGitGadgetThe conversion to synopsis continues. Now the commands are less common, so I may propose larger PRs if it's ok.
Changes since v1:
* swap formats following comments
* switch all listing blocks to 4 dash fences
Jean-Noël Avila (4):
doc: convert git-imap-send synopsis and options to new style
doc: convert git-format-patch synopsis and options to new style
doc: convert git-send-email synopsis and options to new style
doc: convert git-request-pull synopsis and options to new style
Documentation/config/imap.adoc | 2 +- Documentation/config/sendemail.adoc | 92 ++++----- Documentation/diff-options.adoc | 8 +- Documentation/git-format-patch.adoc | 289 ++++++++++++++-------------- Documentation/git-imap-send.adoc | 22 ++- Documentation/git-request-pull.adoc | 38 ++-- Documentation/git-send-email.adoc | 162 ++++++++-------- 7 files changed, 311 insertions(+), 302 deletions(-)
base-commit: 08621c32d5536babd139ab1a9086349b3672edd6
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2185%2Fjnavila%2Fconvert_synopsis_202606-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2185/jnavila/convert_synopsis_202606-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2185
Range-diff vs v1:
1: 798c064390 ! 1: 697b4b55c3 doc: convert git-imap-send synopsis and options to new style
@@ Documentation/config/imap.adoc
plaintext LOGIN command.
## Documentation/git-imap-send.adoc ##
-@@ Documentation/git-imap-send.adoc: supports only XOAUTH2 as the mechanism.
+@@ Documentation/git-imap-send.adoc: that order.
+
+ Typical usage is something like:
+
+-------
++----
+ $ git format-patch --signoff --stdout --attach origin | git imap-send
+-------
++----
+
+
+ OPTIONS
+@@ Documentation/git-imap-send.adoc: have set up) may not be verified correctly.
+
+ Using Gmail's IMAP interface:
+
+----------
++----
+ [imap]
+ folder = "[Gmail]/Drafts"
+ host = imaps://imap.gmail.com
+ user = [email protected]
+ port = 993
+----------
++----
+
+ Gmail does not allow using your regular password for git imap-send.
+ If you have multi-factor authentication set up on your Gmail account, you
+@@ Documentation/git-imap-send.adoc: than using app-specific passwords, and also does not enforce the need of
+ having multi-factor authentication. You will have to use an OAuth2.0
+ access token in place of your password when using this authentication.
+
+----------
++----
+ [imap]
+ folder = "[Gmail]/Drafts"
+ host = imaps://imap.gmail.com
+ user = [email protected]
+ port = 993
+ authmethod = OAUTHBEARER
+----------
++----
+
+ Using Outlook's IMAP interface:
+
+ Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it
+ supports only XOAUTH2 as the mechanism.
+
+----------
++----
+ [imap]
+ folder = "Drafts"
+ host = imaps://outlook.office365.com
+ user = [email protected]
+ port = 993
+ authmethod = XOAUTH2
+----------
++----
Once the commits are ready to be sent, run the following command:
- $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
-+
-+---------
++----
+$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
-+---------
++----
Just make sure to disable line wrapping in the email client (Gmail's web interface will wrap lines no matter what, so you need to use a real
2: e1ed85e3f2 ! 2: 3850fb33ff doc: convert git-format-patch synopsis and options to new style
@@ Documentation/git-format-patch.adoc: set.
Show progress reports on stderr as patches are generated.
CONFIGURATION
+@@ Documentation/git-format-patch.adoc: outputting more than one patch, add "To:" or "Cc:" headers, configure
+ attachments, change the patch output directory, and sign off patches
+ with configuration variables.
+
+-------------
++----
+ [format]
+ headers = "Organization: git-foo\n"
+ subjectPrefix = CHANGE
@@ Documentation/git-format-patch.adoc: with configuration variables.
+ coverLetter = auto
+ commitListFormat = shortlog
+ coverFromDescription = auto
+-------------
+-
++----
+
DISCUSSION
----------
@@ Documentation/git-format-patch.adoc: with configuration variables.
with a fixed "magic" time stamp to indicate that the file is output from format-patch rather than a real mailbox, like so:
+-------------
++----
+ From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
+ From: Tony Luck <[email protected]>
+ Date: Tue, 13 Jul 2010 11:42:54 -0700
+@@ Documentation/git-format-patch.adoc: arch/arm config files were slimmed down using a python script +
+ Do the same for ia64 so we can have sleek & trim looking
+ ...
+-------------
++----
+
+ Typically it will be placed in a MUA's drafts folder, edited to add
+ timely commentary that should not go in the changelog after the three
@@ Documentation/git-format-patch.adoc: can save interesting patches in a UNIX mailbox and apply them with
linkgit:git-am[1].
@@ Documentation/git-format-patch.adoc: can save interesting patches in a UNIX mail
line that consists solely of "-- >8 --" (scissors and perforation), followed by the patch with unnecessary header fields removed:
+-------------
++----
+ ...
+ > So we should do such-and-such.
+
+@@ Documentation/git-format-patch.adoc: Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet +
+ arch/arm config files were slimmed down using a python script
+ ...
+-------------
++----
+
+ When sending a patch this way, most often you are sending your own
+ patch, so in addition to the "From $SHA1 $magic_timestamp" marker you
@@ Documentation/git-format-patch.adoc: two common types of corruption:
One way to test if your MUA is set up correctly is:
@@ Documentation/git-format-patch.adoc: External Editor from https://globs.org/arti
window for the patch, use Tools->about:config to set the
following to the indicated values:
+
+-----------
++----
+ mailnews.send_plaintext_flowed => false
+ mailnews.wraplength => 0
+-----------
++----
+
+ 4. Open a compose window and click the external editor icon.
+
+@@ Documentation/git-format-patch.adoc: External Editor from https://globs.org/articles.php?lng=en&pg=8
+ Side note: it may be possible to do step 2 with
+ about:config and the following settings but no one's tried yet.
+
+-----------
++----
+ mail.html_compose => false
+ mail.identity.default.compose_html => false
+ mail.identity.id?.compose_html => false
+-----------
++----
+
+ There is a script in contrib/thunderbird-patch-inline which can help
+ you include patches with Thunderbird in an easy way. To use it, do the
@@ Documentation/git-format-patch.adoc: BASE TREE INFORMATION
The base tree information block is used for maintainers or third party
@@ Documentation/git-format-patch.adoc: BASE TREE INFORMATION
-The 'base commit' is shown as "base-commit: " followed by the 40-hex of -the commit object name. A 'prerequisite patch' is shown as -"prerequisite-patch-id: " followed by the 40-hex 'patch id', which can
-+The "base commit" is shown as "base-commit: " followed by the 40-hex of -+the commit object name. A prerequisite patch is shown as -+"prerequisite-patch-id: " followed by the 40-hex patch id, which can ++The "base commit" is shown as "base-commit: " followed by the 40-hex of ++the commit object name. A "prerequisite patch" is shown as ++"prerequisite-patch-id: " followed by the 40-hex "patch id", which can
be obtained by passing the patch through the git patch-id --stable command.
+@@ Documentation/git-format-patch.adoc: range), the base tree information block is shown at the end of the
+ first message the command outputs (either the first patch, or the
+ cover letter), like this:
+
+-------------
++----
+ base-commit: P
+ prerequisite-patch-id: X
+ prerequisite-patch-id: Y
+ prerequisite-patch-id: Z
+-------------
++----
+
+ For non-linear topology, such as
+
@@ Documentation/git-format-patch.adoc: EXAMPLES
--------
3: 723450c5a0 = 3: 94751ae58b doc: convert git-send-email synopsis and options to new style
4: 5b6e9bd3f3 ! 4: 740b24631d doc: convert git-request-pull synopsis and options to new style
@@ Documentation/git-request-pull.adoc: the `v1.0` release, and want it to be integ
see:
- git push https://git.ko.xz/project master
-+-----
++----
+git push https://git.ko.xz/project master
-+-----
++----
Then, you run this command:
- git request-pull v1.0 https://git.ko.xz/project master
-+------
++----
+git request-pull v1.0 https://git.ko.xz/project master
-+------
++----
which will produce a request to the upstream, summarizing the
changes between the `v1.0` release and your `master`, to pull it
@@ Documentation/git-request-pull.adoc: from your public repository.
the one you have locally, e.g.
- git push https://git.ko.xz/project master:for-linus
-+-----
++----
+git push https://git.ko.xz/project master:for-linus
-+-----
++----
then you can ask that to be pulled with
- git request-pull v1.0 https://git.ko.xz/project master:for-linus
-+-----
++----
+git request-pull v1.0 https://git.ko.xz/project master:for-linus
-+-----
++----
GITSignature · 1 line
gitgitgadget
PATCH v2 1/4 doc: convert git-imap-send synopsis and options to new style
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Convert git-imap-send from [verse]/single-quote style to the modern synopsis-block style:
- Replace [verse] with [synopsis] in SYNOPSIS block
- Backtick-quote all OPTIONS terms
- Backtick-quote all config keys in config/imap.adoc
- Backtick-quote bare config key references in prose
--- Documentation/config/imap.adoc | 2 +- Documentation/git-imap-send.adoc | 22 ++++++++++++---------- 2 files changed, 13 insertions(+), 11 deletions(-)
Documentation/config/imap.adoc +1 -1
@@ -41,7 +41,7 @@ `imap.authMethod`:: Specify the authentication method for authenticating with the IMAP server. If Git was built with the NO_CURL option, or if your curl version is older - than 7.34.0, or if you're running git-imap-send with the `--no-curl` + than 7.34.0, or if you're running `git-imap-send` with the `--no-curl` option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER` and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP plaintext `LOGIN` command.
Documentation/git-imap-send.adoc +12 -10
@@ -24,9 +24,9 @@ that order. Typical usage is something like: ------- +---- $ git format-patch --signoff --stdout --attach origin | git imap-send ------- +---- OPTIONS
@@ -138,13 +138,13 @@ have set up) may not be verified correctly. Using Gmail's IMAP interface: ---------- +---- [imap] folder = "[Gmail]/Drafts" host = imaps://imap.gmail.com user = [email protected] port = 993 ---------- +---- Gmail does not allow using your regular password for `git imap-send`. If you have multi-factor authentication set up on your Gmail account, you
@@ -167,32 +167,34 @@ than using app-specific passwords, and also does not enforce the need of having multi-factor authentication. You will have to use an OAuth2.0 access token in place of your password when using this authentication. ---------- +---- [imap] folder = "[Gmail]/Drafts" host = imaps://imap.gmail.com user = [email protected] port = 993 authmethod = OAUTHBEARER ---------- +---- Using Outlook's IMAP interface: Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it supports only `XOAUTH2` as the mechanism. ---------- +---- [imap] folder = "Drafts" host = imaps://outlook.office365.com user = [email protected] port = 993 authmethod = XOAUTH2 ---------- +---- Once the commits are ready to be sent, run the following command: - $ git format-patch --cover-letter -M --stdout origin/master | git imap-send +---- +$ git format-patch --cover-letter -M --stdout origin/master | git imap-send +---- Just make sure to disable line wrapping in the email client (Gmail's web interface will wrap lines no matter what, so you need to use a real
@@ -217,7 +219,7 @@ users may wish to visit this web page for more information: SEE ALSO -------- -linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5) +linkgit:git-format-patch[1], linkgit:git-send-email[1], `mbox`(5) GIT ---
Signature · 1 line
gitgitgadget
PATCH v2 2/4 doc: convert git-format-patch synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.
Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.
Also update the included files:
- diff-options.adoc: backtick-quote the git-format-patch-specific option terms (-p, --no-stat, --max-depth=<depth>)
- format-patch-caveats.adoc: convert patch(1) to patch(1)
--- Documentation/diff-options.adoc | 8 +- Documentation/git-format-patch.adoc | 289 ++++++++++++++-------------- 2 files changed, 148 insertions(+), 149 deletions(-)
Documentation/diff-options.adoc +4 -4
@@ -13,8 +13,8 @@ endif::git-diff[] endif::git-format-patch[] ifdef::git-format-patch[] --p:: ---no-stat:: +`-p`:: +`--no-stat`:: Generate plain patches without any diffstats. endif::git-format-patch[]
@@ -893,8 +893,8 @@ endif::git-format-patch[] reverted with `--ita-visible-in-index`. Both options are experimental and could be removed in future. ---max-depth=<depth>:: - For each pathspec given on command line, descend at most `<depth>` +`--max-depth=<depth>`:: + For each pathspec given on command line, descend at most _<depth>_ levels of directories. A value of `-1` means no limit. Cannot be combined with wildcards in the pathspec. Given a tree containing `foo/bar/baz`, the following list shows the
Documentation/git-format-patch.adoc +144 -145
673 lines not on this page · raw message
Signature · 1 line
gitgitgadget
PATCH v2 3/4 doc: convert git-send-email synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.
Backtick-quote all option terms in the OPTIONS section, convert the standalone placeholder _<encoding>_ in prose, fix single-quoted server names to backtick form, and convert mbox(5) to mbox(5).
Also update config/sendemail.adoc: backtick-quote all configuration key terms and fix a bare sendemail.aliasesFile reference in prose.
--- Documentation/config/sendemail.adoc | 92 ++++++++-------- Documentation/git-send-email.adoc | 162 ++++++++++++++-------------- 2 files changed, 127 insertions(+), 127 deletions(-)
Documentation/config/sendemail.adoc +46 -46
@@ -1,25 +1,25 @@ -sendemail.identity:: +`sendemail.identity`:: A configuration identity. When given, causes values in the `sendemail.<identity>` subsection to take precedence over values in the `sendemail` section. The default identity is the value of `sendemail.identity`. -sendemail.smtpEncryption:: +`sendemail.smtpEncryption`:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the `identity` mechanism. -sendemail.smtpSSLCertPath:: +`sendemail.smtpSSLCertPath`:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. -sendemail.smtpSSLClientCert:: +`sendemail.smtpSSLClientCert`:: Path to the client certificate file to present if requested by the server. This is required when the server is set up to verify client certificates. If the corresponding private key is not included in the file, it must be supplied using `sendemail.smtpSSLClientKey` or the `--smtp-ssl-client-key` option. -sendemail.smtpSSLClientKey:: +`sendemail.smtpSSLClientKey`:: Path to the client private key file that corresponds to the client certificate. To avoid misconfiguration, this configuration must be used in conjunction with `sendemail.smtpSSLClientCert` or the
@@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey:: the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more details. -sendemail.<identity>.*:: - Identity-specific versions of the `sendemail.*` parameters +`sendemail.<identity>.<config>`:: + Identity-specific versions of the `sendemail.<config>` parameters found below, taking precedence over those when this identity is selected, through either the command-line or `sendemail.identity`. -sendemail.multiEdit:: +`sendemail.multiEdit`:: If `true` (default), a single editor instance will be spawned to edit files you have to edit (patches when `--annotate` is used, and the summary when `--compose` is used). If `false`, files will be edited one after the other, spawning a new editor each time. -sendemail.confirm:: +`sendemail.confirm`:: Sets the default for whether to confirm before sending. Must be one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm` in the linkgit:git-send-email[1] documentation for the meaning of these values. -sendemail.mailmap:: +`sendemail.mailmap`:: If `true`, makes linkgit:git-send-email[1] assume `--mailmap`, otherwise assume `--no-mailmap`. `False` by default. -sendemail.mailmap.file:: +`sendemail.mailmap.file`:: The location of a linkgit:git-send-email[1] specific augmenting mailmap file. The default mailmap and `mailmap.file` are loaded first. Thus, entries in this file take precedence over entries in the default mailmap locations. See linkgit:gitmailmap[5]. -sendemail.mailmap.blob:: +`sendemail.mailmap.blob`:: Like `sendemail.mailmap.file`, but consider the value as a reference to a blob in the repository. Entries in `sendemail.mailmap.file` take precedence over entries here. See linkgit:gitmailmap[5]. -sendemail.aliasesFile:: +`sendemail.aliasesFile`:: To avoid typing long email addresses, point this to one or more email aliases files. You must also supply `sendemail.aliasFileType`. -sendemail.aliasFileType:: - Format of the file(s) specified in sendemail.aliasesFile. Must be +`sendemail.aliasFileType`:: + Format of the file(s) specified in `sendemail.aliasesFile`. Must be one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`. + What an alias file in each format looks like can be found in
@@ -75,7 +75,7 @@ differences and limitations from the standard formats are described below: + -- -sendmail;; +`sendmail`;; * Quoted aliases and quoted addresses are not supported: lines that contain a `"` symbol are ignored. * Redirection to a file (`/path/name`) or pipe (`|command`) is not
@@ -85,54 +85,54 @@ sendmail;; explicitly unsupported constructs, and any other lines that are not recognized by the parser. -- -sendemail.annotate:: -sendemail.bcc:: -sendemail.cc:: -sendemail.ccCmd:: -sendemail.chainReplyTo:: -sendemail.envelopeSender:: -sendemail.from:: -sendemail.headerCmd:: -sendemail.signedOffByCc:: -sendemail.smtpPass:: -sendemail.suppressCc:: -sendemail.suppressFrom:: -sendemail.to:: -sendemail.toCmd:: -sendemail.smtpDomain:: -sendemail.smtpServer:: -sendemail.smtpServerPort:: -sendemail.smtpServerOption:: -sendemail.smtpUser:: -sendemail.imapSentFolder:: -sendemail.useImapOnly:: -sendemail.thread:: -sendemail.transferEncoding:: -sendemail.validate:: -sendemail.xmailer:: +`sendemail.annotate`:: +`sendemail.bcc`:: +`sendemail.cc`:: +`sendemail.ccCmd`:: +`sendemail.chainReplyTo`:: +`sendemail.envelopeSender`:: +`sendemail.from`:: +`sendemail.headerCmd`:: +`sendemail.signedOffByCc`:: +`sendemail.smtpPass`:: +`sendemail.suppressCc`:: +`sendemail.suppressFrom`:: +`sendemail.to`:: +`sendemail.toCmd`:: +`sendemail.smtpDomain`:: +`sendemail.smtpServer`:: +`sendemail.smtpServerPort`:: +`sendemail.smtpServerOption`:: +`sendemail.smtpUser`:: +`sendemail.imapSentFolder`:: +`sendemail.useImapOnly`:: +`sendemail.thread`:: +`sendemail.transferEncoding`:: +`sendemail.validate`:: +`sendemail.xmailer`:: These configuration variables all provide a default for linkgit:git-send-email[1] command-line options. See its documentation for details. -sendemail.outlookidfix:: +`sendemail.outlookidfix`:: If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`, and if `false` assume `--no-outlook-id-fix`. If not specified, it will behave the same way as if `--outlook-id-fix` is not specified. -sendemail.signedOffCc (deprecated):: +`sendemail.signedOffCc` (deprecated):: Deprecated alias for `sendemail.signedOffByCc`. -sendemail.smtpBatchSize:: +`sendemail.smtpBatchSize`:: Number of messages to be sent per connection, after that a relogin will happen. If the value is `0` or undefined, send all messages in one connection. See also the `--batch-size` option of linkgit:git-send-email[1]. -sendemail.smtpReloginDelay:: +`sendemail.smtpReloginDelay`:: Seconds to wait before reconnecting to the smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. -sendemail.forbidSendmailVariables:: +`sendemail.forbidSendmailVariables`:: To avoid common misconfiguration mistakes, linkgit:git-send-email[1] will abort with a warning if any configuration options for `sendmail` exist. Set this variable to bypass the check.
Documentation/git-send-email.adoc +81 -81
473 lines not on this page · raw message
Signature · 1 line
gitgitgadget
PATCH v2 4/4 doc: convert git-request-pull synopsis and options to new style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
* Replace [verse] with [synopsis] in the SYNOPSIS block
* remove single-quote formatting from the command name
* backtick-quote the flag
* use _<placeholder>_ form for positional parameter terms
--- Documentation/git-request-pull.adoc | 38 +++++++++++++++++------------ 1 file changed, 23 insertions(+), 15 deletions(-)
Documentation/git-request-pull.adoc +23 -15
@@ -7,8 +7,8 @@ git-request-pull - Generates a summary of pending changes SYNOPSIS -------- -[verse] -'git request-pull' [-p] <start> <URL> [<end>] +[synopsis] +git request-pull [-p] <start> <URL> [<end>] DESCRIPTION -----------
@@ -19,28 +19,28 @@ begins with the branch description, summarizes the changes, and indicates from where they can be pulled. The upstream project is expected to have the commit named by -`<start>` and the output asks it to integrate the changes you made -since that commit, up to the commit named by `<end>`, by visiting -the repository named by `<URL>`. +_<start>_ and the output asks it to integrate the changes you made +since that commit, up to the commit named by _<end>_, by visiting +the repository named by _<URL>_. OPTIONS ------- --p:: +`-p`:: Include patch text in the output. -<start>:: +_<start>_:: Commit to start at. This names a commit that is already in the upstream history. -<URL>:: +_<URL>_:: The repository URL to be pulled from. -<end>:: - Commit to end at (defaults to HEAD). This names the commit +_<end>_:: + Commit to end at (defaults to `HEAD`). This names the commit at the tip of the history you are asking to be pulled. + -When the repository named by `<URL>` has the commit at a tip of a +When the repository named by _<URL>_ has the commit at a tip of a ref that is different from the ref you have locally, you can use the `<local>:<remote>` syntax, to have its local name, a colon `:`, and its remote name.
@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project. First you push that change to your public repository for others to see: - git push https://git.ko.xz/project master +---- +git push https://git.ko.xz/project master +---- Then, you run this command: - git request-pull v1.0 https://git.ko.xz/project master +---- +git request-pull v1.0 https://git.ko.xz/project master +---- which will produce a request to the upstream, summarizing the changes between the `v1.0` release and your `master`, to pull it
@@ -67,11 +71,15 @@ from your public repository. If you pushed your change to a branch whose name is different from the one you have locally, e.g. - git push https://git.ko.xz/project master:for-linus +---- +git push https://git.ko.xz/project master:for-linus +---- then you can ask that to be pulled with - git request-pull v1.0 https://git.ko.xz/project master:for-linus +---- +git request-pull v1.0 https://git.ko.xz/project master:for-linus +---- GIT
Signature · 1 line
gitgitgadget
Quoted 7 lines · Jean-Noël Avila via GitGitGadget
The conversion to synopsis continues. Now the commands are less common, so I may propose larger PRs if it's ok.
Changes since v1:
* swap formats following comments
* switch all listing blocks to 4 dash fences
All of these changes look as expected.
Shall we mark the topic for 'next'?
Thanks.