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

From: Junio C Hamano <gitster@pobox.com>
Date: May 29, 2025, 18:50 UTC
Message-ID: <xmqq5xhjl09q.fsf@gitster.g>
In-Reply-To: <20250528070521.17379-5-gargaditya08@live.com>

Aditya Garg <gargaditya08@live.com> writes:

Show 5 quoted lines

> 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.

Correct, and the clarification looks good.

> This commit clarifies that app passwords are required and suggests using
> OAuth2 if the user does not want to enable multi-factor authentication.

Dubious. If the user does want to use 2FA (or already does use it), there may be reasons why they still want to go the oauth route, no?

> ---
>  Documentation/git-send-email.adoc | 3 +++
>  1 file changed, 3 insertions(+)

Not signed off.

Show 15 quoted lines

>
> diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
> index aff0861d29..99c126cd5a 100644
> --- a/Documentation/git-send-email.adoc
> +++ b/Documentation/git-send-email.adoc
> @@ -524,9 +524,12 @@ edit `~/.gitconfig` to specify your account settings:
>  	smtpServerPort = 587
>  ----
>  
> +Gmail does not allow using your account 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.
> +If you do not want to enable multi-factor authentication, you can use OAuth2.0
> +authentication as described below.

How about phrasing it more neutrally like ...

    "Alternatively, instead of using app-specific password, you can use ..."

The original somehow makes it sound like using 2FA + app_password is the golden way, and short of that you could fall back to OAUTH, but that is not the impression you would want to give to your readers, I think.

>  You can also use OAuth2.0 authentication with Gmail. `OAUTHBEARER` and
>  `XOAUTH2` are common methods used for this type of authentication. Gmail

Whether you take my suggestion or not, I think the first sentence here is now redundant and can be safely removed.