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@xxxxxxxx> --- 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..ada883289a 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. For that edit ~/.gitconfig +and add `smtpAuth = OAUTHBEARER` to your account settings: + +---- +[sendemail] + smtpEncryption = tls + smtpServer = smtp.gmail.com + smtpUser = yourname@xxxxxxxxx + smtpServerPort = 587 + smtpAuth = OAUTHBEARER +---- + +Use Microsoft Outlook as the SMTP server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords. +Therefore, we have to use OAuth2.0 authentication 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@xxxxxxxxxxx + 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@xxxxxxxxxxx" HEAD~1 + +You can also add `--annotate` to edit the patches before sending: + + $ git send-email --annotate --to="mailinglist@xxxxxxxxxxx" 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@xxxxxxxxxxx" 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@xxxxxxxxxxx" HEAD~3 + +Versions of a patch series can also be specified. For example to send a version 2: + + $ git send-email --to="mailinglist@xxxxxxxxxxx" -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@xxxxxxxxxxx" --subject-prefix='PATCH RESEND' HEAD~1 + +You can also Cc someone like this: + + $ git send-email --to="mailinglist@xxxxxxxxxxx" --cc="someone@xxxxxxxxxxx HEAD~1 + +Multiple `--to` can also be specified: + + $ git send-email --to="list1@xxxxxxxxxxx" --to="list2@xxxxxxxxxxx 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 with OAuth2.0 support +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
