From: Jean-Noël Avila via GitGitGadget Date: Thu, 23 Jul 2026 21:19:22 GMT Subject: [PATCH v2 0/4] A new batch of synopsis conversion Message-ID: In-Reply-To: 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 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 = user@gmail.com + 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 = user@gmail.com + 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 = user@outlook.com + 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 + 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 -+----- ++---- GIT -- gitgitgadget