[PATCH v2 2/3] docs: improve send-email documentation
This commit does the following changes to the send email doc:
1. Added examples to use OAuth2.0 with Gmail and Outlook.
2. Improved examples to send patches using git send-email
3. Added links of credential helpers for Gmail and Outlook
Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
Documentation/git-send-email.adoc | 106 ++++++++++++++++++++++++++----
1 file changed, 93 insertions(+), 13 deletions(-)
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 92389036fa..af29e61299 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -509,12 +509,12 @@ include::includes/cmd-config-section-all.adoc[]
include::config/sendemail.adoc[]
-EXAMPLES
---------
-Use gmail as the smtp server
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To use 'git send-email' to send your patches through the GMail SMTP server,
-edit ~/.gitconfig to specify your account settings:
+To use 'git send-email' to send your patches through the Gmail SMTP server,
+edit '~/.gitconfig' to specify your account settings:
----
[sendemail]
@@ -528,17 +528,97 @@ If you have multi-factor authentication set up on your Gmail account, you can
generate an app-specific password for use with 'git send-email'. Visit
https://security.google.com/settings/security/apppasswords to create it.
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
+You can also use OAuth2.0 authentication with Gmail. To do this, edit your
+`~/.gitconfig` file and add `smtpAuth = OAUTHBEARER` to your account settings:
+
+----
+[sendemail]
+ smtpEncryption = tls
+ smtpServer = smtp.gmail.com
+ smtpUser = yourname@gmail.com
+ smtpServerPort = 587
+ smtpAuth = OAUTHBEARER
+----
+
+Use Microsoft Outlook as the SMTP Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords.
+Therefore, OAuth2.0 authentication must be used for Outlook.
+
+Edit '~/.gitconfig' to specify your account settings for Outlook and use its
+SMTP server with 'git send-email':
+
+----
+[sendemail]
+ smtpEncryption = tls
+ smtpServer = smtp.office365.com
+ smtpUser = yourname@outlook.com
+ smtpServerPort = 587
+ smtpAuth = XOAUTH2
+----
+
+SENDING PATCHES
+---------------
+The following examples can be used to have a basic idea on how to send patches
+to a mailing list:
+
+If you want to send a single patch, run:
+
+ $ git send-email --to="mailinglist@example.org" HEAD~1
+
+You can also add `--annotate` to edit the patches before sending:
+
+ $ git send-email --annotate --to="mailinglist@example.org" HEAD~1
+
+Multiple patches can also be sent. For example, if you want to send the last 3
+commits as patches, run:
+
+ $ git send-email --to="mailinglist@example.org" HEAD~3
+
+You can also add a cover letter. It is useful especially in case of multiple
+patches. Note the use of `--annotate` here since we have to edit the cover letter
+before sending it:
+
+ $ git send-email --annotate --cover-letter --to="mailinglist@example.org" HEAD~3
+
+Versions of a patch series can also be specified. For example to send a version 2:
+
+ $ git send-email --to="mailinglist@example.org" -v2 HEAD~1
+
+You can also specify custom subject prefixes. For example, to have '[PATCH RESEND]'
+as a prefix, run:
+
+ $ git send-email --to="mailinglist@example.org" --subject-prefix='PATCH RESEND' HEAD~1
+
+You can also Cc someone like this:
+
+ $ git send-email --to="mailinglist@example.org" --cc="someone@example.com" HEAD~1
+
+Multiple `--to` can also be specified:
+
+ $ git send-email --to="list1@example.org" --to="list2@example.com" HEAD~1
+
+Similarly you can specify multiple `--cc` as well.
- $ git format-patch --cover-letter -M origin/master -o outgoing/
- $ edit outgoing/0000-*
- $ git send-email outgoing/*
The first time you run it, you will be prompted for your credentials. Enter the
-app-specific or your regular password as appropriate. If you have credential
-helper configured (see linkgit:git-credential[1]), the password will be saved in
-the credential store so you won't have to type it the next time.
+app-specific or your regular password as appropriate.
+
+If you have credential helper configured (see linkgit:git-credential[1]), the
+password will be saved in the credential store so you won't have to type it the
+next time.
+
+If you are using OAuth2.0 authentication, you need to use an access token in
+place of a password when prompted. Various OAuth2.0 token generators are
+available online. Community maintained credential helpers for Gmail and Outlook
+are also available:
+
+ - https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-gmail] (cross platform, dedicated helper for authenticating Gmail accounts)
+
+ - https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-outlook] (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
Note: the following core Perl modules that may be installed with your
distribution of Perl are required:
--
2.49.0
Aditya Garg <gargaditya08@live.com>