[PATCH v5 2/3] docs: improve send-email documentation
- From
Aditya Garg <gargaditya08@live.com>
- Date
- May 8, 2025, 10:31 UTC
- Message-ID
- <PN3PR01MB9597FB82424820EAB5D4D2EAB88BA@PN3PR01MB9597.INDPRD01.PROD.OUTLOOK.COM>
- In-Reply-To
- <PN3PR01MB95974932FF37D9F24A7633C6B88BA@PN3PR01MB9597.INDPRD01.PROD.OUTLOOK.COM>
OAuth2.0 is a new authentication method that is being used by many email providers, including Outlook and Gmail. Recently, the Authen::SASL perl module has been updated to support OAuth2.0 authentication, thus making the git-send-email script be able to use this authentication method as well. So lets improve the documentation to reflect this change.
I also had a hard time finding a reliable OAuth2.0 access token generator for Outlook and Gmail. So I added a link to the such generators which I developed myself after seaching through lots of code and API documentation to make things easier for others.
Signed-off-by: Aditya Garg <gargaditya08@live.com> --- Documentation/git-send-email.adoc | 63 +++++++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc index 92389036fa..d232e109a1 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,6 +528,37 @@ 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. +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 +--------------- Once your commits are ready to be sent to the mailing list, run the following commands: @@ -536,9 +567,25 @@ following commands: $ 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 a 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-email[git-credential-gmail] + (cross platform, dedicated helper for authenticating Gmail accounts) + + - https://github.com/AdityaGarg8/git-credential-email[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