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

From: Aditya Garg <gargaditya08@live.com>
Date: May 8, 2025, 13:52 UTC
Message-ID: <PN3PR01MB95972BB022C2297D3E52DE78B88BA@PN3PR01MB9597.INDPRD01.PROD.OUTLOOK.COM>
In-Reply-To: <xmqqwmar8bw9.fsf@gitster.g>

Show 15 quoted lines

> On 8 May 2025, at 7:04 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>>>> -To use 'git send-email' to send your patches through the GMail SMTP server,
>>>> -edit ~/.gitconfig to specify your account settings:
>>>> +To use 'git send-email' to send your patches through the Gmail SMTP server,
>>>> +edit '~/.gitconfig' to specify your account settings:
>>> 
>>> The four single quotes above should probably be changed to back
>>> quotes, to match the "You can also use OAuth2.0..." below.
>> 
>> I think ~/.gitconfig should be in single quotes, its not a command.
> 
> "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.

Show 14 quoted lines

> not "Is this a command name?".
> 
>> Gmail supports for OAUTHBEARER and XOAUTH2. I added OAUTHBEARER
>> just for the sake of a different example. I think adding a choice
>> between two will just cause confusion among people.
>> 
>> Outlook supports only XOAUTH2 (which is surprising since OAUTHBEARER
>> is described in RFC, and XOAUTH2 is Google's).
> 
> Your examples that show that smtpAuth can take these different
> values are certainly good.  As we know what these two services
> support, it is worth saying, no?  Unless it is like Gmail supports
> both but git-send-email for whatever reason can use only one of them
> to talk to Gmail, that is.

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.

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. Also, by this logic, Gmail also supports smtpAuth=LOGIN with app passwords. 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". Infact mentioning both options will just make him wonder on what option is better, XOAUTH2 or OAUTHBEARER, which practically are the same in terms of access tokens and other stuff. The only difference is "how is the access token formatted and sent to the server", which is done at a lower level by Authen::SASL, and isn't really a concern for users. In short, the same access token works for both XOAUTH2 and OAUTHBEARER. As far as "what actually is supported by my email provider", is concerned, just consult their docs. That's what a curious advanced user would want to know and I belive he is very capable to figure that out.