docs: make the purpose of using app password for Gmail more clear in send-email

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 5d13a856a7047ac6287e9881fe45d194edff4e80..7bd09c254b271e41ac73b0aeea01f7477faa97ca 100644 (file)
--- 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`: