Re: [PATCH v4 2/3] docs: improve send-email documentation

From: Junio C Hamano <gitster@pobox.com>
Date: May 8, 2025, 16:23 UTC
Message-ID: <xmqq7c2r6phg.fsf@gitster.g>
In-Reply-To: <PN3PR01MB95972BB022C2297D3E52DE78B88BA@PN3PR01MB9597.INDPRD01.PROD.OUTLOOK.COM>

Aditya Garg <gargaditya08@live.com> writes:

Show 6 quoted lines

>> "Is this something the end-user would type verbatim?" is the criteria,
>
> So the end user won't type it. It's just a path of a file to be edited.
> If you still want to change it to backticks, I'll change it. Do confirm the same btw.
>
>> not "Is this a command name?".

Then perhaps 'type' -> 'use'; the idea is the same. Are we showing the exact concrete thing (e.g. "file at this path, which you would spell `like so`") or a concept (e.g. "per-user configuration file")? The `literal` mark-up is for the former.

> git send email can use any smtpAuth method that is supported by Authen::SASL
> and the server. So using XOAUTH2 with gmail will also work just fine.

OK.

> As far as giving information about supported authentication methods is concerned,
> we are writing an example, not giving a detailed guide with the providers docs.

Yes, but giving a passing mention, like

	You can also use OAuth2.0 authentication with Gmail.  Edit
	`~/.gitconfig` and set `sendemail.smtpAuth = OAUTHBEARER`
	there (they support both XOAUTH2 and OAUTHBEARER, but the
	latter is more recent and in the standard):

	---
	... example here ...
	---

would make it easier to see to those who learn from elsewhere that they can use their e-mail client (not `git send-email`) with Gmail with OAuth, come here because they want to use the same account with `git send-email` too. If that 'elsewhere' only mentioned XOAUTH2, writing something like the above would be more helpful than using OAUTHBEARER without mentioning XOAUTH2 at all, no?

> Also, by this logic, Gmail also supports smtpAuth=LOGIN with app passwords.

But the question we need to answer is: does talking about it help when people want to learn how to use OAuth2.0 instead of plain vanilla password login? I think talking about smtpAuth=OAUTHBEARER and smtpAuth=XOAUTH2 does help; does talking about smtpAuth=LOGIN help?

So, no, LOGIN is irrelevant, and I do not quite see the above as making a meaningful analogy "by this logic".

> Plus, anyone reading this guide would most likely be a newbie, who will be more
> interested in "how to get this thing working" than knowing "oh, I can use XOAUTH2
> as well in gmail".

I am suggeting that you can cater to both of them with minimum effort. A newbie can fall into the latter class; those who used XOAUTH2 when setting up other software (hence they know XOAUTH2 works with Gmail) but did not know that OAUTHBEARER also worked as well.

Thanks.