[PATCH v7 4/4] docs: make the purpose of using app password for Gmail more clear in send-email

From: Aditya Garg <gargaditya08@live.com>
Date: May 30, 2025, 15:50 UTC
Message-ID: <20250530154934.10077-5-gargaditya08@live.com>
In-Reply-To: <20250530154934.10077-1-gargaditya08@live.com>

The current example for Gmail suggests using app passwords for send-email if user has multi-factor authentication set up for their account. However, it does not clarify that the user cannot use their normal password in case they do not have multi-factor authentication enabled. Most likely the example was written in the days when Google allowed using normal passwords without multi-factor authentication.

Clarify that regular passwords do not work for Gmail and app-passwords are the only way for basic authentication. Also encourage users to use OAuth2.0 as a more secure alternative.

While at it, also prefer using the word "mechanism" over "method" for `OAUTHBEARER` and `XOAUTH2` since that is what official docs use.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 5d13a856a7..7bd09c254b 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -525,15 +525,18 @@ edit `~/.gitconfig` to specify your account settings:
 	smtpServerPort = 587
 ----
 
+Gmail does not allow using your regular password for `git send-email`.
 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. `OAUTHBEARER` and
-`XOAUTH2` are common methods used for this type of authentication. Gmail
-supports both of them. As an example, if you want to use `OAUTHBEARER`, edit
-your `~/.gitconfig` file and add `smtpAuth = OAUTHBEARER` to your account
-settings:
+Alternatively, instead of using an app-specific password, you can use
+OAuth2.0 authentication with Gmail. OAuth2.0 is more secure than
+app-specific passwords, and works regardless of whether you have multi-factor
+authentication set up. `OAUTHBEARER` and `XOAUTH2` are common mechanisms used
+for this type of authentication. Gmail supports both of them. As an example,
+if you want to use `OAUTHBEARER`, edit your `~/.gitconfig` file and add
+`smtpAuth = OAUTHBEARER` to your account settings:
 
 ----
 [sendemail]
@@ -544,7 +547,7 @@ settings:
 	smtpAuth = OAUTHBEARER
 ----
 
-Alternatively, you can use a tool developed by Google known as
+Another alternative is using a tool developed by Google known as
 https://github.com/google/gmail-oauth2-tools/tree/master/go/sendgmail[sendgmail]
 to send emails using `git send-email`.
 
@@ -552,7 +555,7 @@ 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. Also, it only
-supports `XOAUTH2` authentication method.
+supports `XOAUTH2` authentication mechanism.
 
 Edit `~/.gitconfig` to specify your account settings for Outlook and use its
 SMTP server with `git send-email`:

-- 
2.49.0.639.ge2dd5d9d81