docs: improve send-email documentation
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Aditya Garg committed
May 8, 2025 at 17:14 UTC
d6c63a798f333821c4dc08cf45b7628f77d7ab93
1 file changed
+59
-8
Documentation/git-send-email.adoc
+59
-8
@@ -496,12 +496,12 @@ include::includes/cmd-config-section-all.adoc[]
496
497
include::config/sendemail.adoc[]
498
499
-EXAMPLES
500
---------
501
-Use gmail as the smtp server
499
+EXAMPLES OF SMTP SERVERS
500
+------------------------
501
+Use Gmail as the SMTP Server
502
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
503
-To use 'git send-email' to send your patches through the GMail SMTP server,
504
-edit ~/.gitconfig to specify your account settings:
503
+To use `git send-email` to send your patches through the Gmail SMTP server,
504
+edit `~/.gitconfig` to specify your account settings:
505
506
----
507
[sendemail]
@@ -515,6 +515,41 @@ If you have multi-factor authentication set up on your Gmail account, you can
515
generate an app-specific password for use with 'git send-email'. Visit
516
https://security.google.com/settings/security/apppasswords to create it.
517
518
+You can also use OAuth2.0 authentication with Gmail. `OAUTHBEARER` and
519
+`XOAUTH2` are common methods used for this type of authentication. Gmail
520
+supports both of them. As an example, if you want to use `OAUTHBEARER`, edit
521
+your `~/.gitconfig` file and add `smtpAuth = OAUTHBEARER` to your account
522
+settings:
523
+
524
+----
525
+[sendemail]
526
+ smtpEncryption = tls
527
+ smtpServer = smtp.gmail.com
528
+ smtpUser = yourname@gmail.com
529
+ smtpServerPort = 587
530
+ smtpAuth = OAUTHBEARER
531
+----
532
+
533
+Use Microsoft Outlook as the SMTP Server
534
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
535
+Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords.
536
+Therefore, OAuth2.0 authentication must be used for Outlook. Also, it only
537
+supports `XOAUTH2` authentication method.
538
+
539
+Edit `~/.gitconfig` to specify your account settings for Outlook and use its
540
+SMTP server with `git send-email`:
541
+
542
+----
543
+[sendemail]
544
+ smtpEncryption = tls
545
+ smtpServer = smtp.office365.com
546
+ smtpUser = yourname@outlook.com
547
+ smtpServerPort = 587
548
+ smtpAuth = XOAUTH2
549
+----
550
+
551
+SENDING PATCHES
552
+---------------
553
Once your commits are ready to be sent to the mailing list, run the
554
following commands:
555
@@ -523,9 +558,25 @@ following commands:
558
$ git send-email outgoing/*
559
560
The first time you run it, you will be prompted for your credentials. Enter the
526
-app-specific or your regular password as appropriate. If you have credential
527
-helper configured (see linkgit:git-credential[1]), the password will be saved in
528
-the credential store so you won't have to type it the next time.
561
+app-specific or your regular password as appropriate.
562
+
563
+If you have a credential helper configured (see linkgit:git-credential[1]), the
564
+password will be saved in the credential store so you won't have to type it the
565
+next time.
566
+
567
+If you are using OAuth2.0 authentication, you need to use an access token in
568
+place of a password when prompted. Various OAuth2.0 token generators are
569
+available online. Community maintained credential helpers for Gmail and Outlook
570
+are also available:
571
+
572
+ - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail]
573
+ (cross platform, dedicated helper for authenticating Gmail accounts)
574
+
575
+ - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook]
576
+ (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)
577
+
578
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
579
+helpers.
580
581
Note: the following core Perl modules that may be installed with your
582
distribution of Perl are required: