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

> On 8 May 2025, at 3:51 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> 
>> 
>> -EXAMPLES
>> ---------
>> -Use gmail as the smtp server
>> +EXAMPLES OF SMTP SERVERS
>> +------------------------
>> +Use Gmail as the SMTP Server
> 
> Nice to see that you got the capitalization got right while at it.
> 
>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> -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.

> 
>> @@ -528,6 +528,37 @@ 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. To do this, edit your
>> +`~/.gitconfig` file and add `smtpAuth = OAUTHBEARER` to your account settings:
>> +
>> +----
>> +[sendemail]
>> +    smtpEncryption = tls
>> +    smtpServer = smtp.gmail.com
>> +    smtpUser = yourname@gmail.com
>> +    smtpServerPort = 587
>> +    smtpAuth = OAUTHBEARER
>> +----
>> +
>> +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.
>> +
>> +Edit '~/.gitconfig' to specify your account settings for Outlook and use its
>> +SMTP server with 'git send-email':
>> +
>> +----
>> +[sendemail]
>> +    smtpEncryption = tls
>> +    smtpServer = smtp.office365.com
>> +    smtpUser = yourname@outlook.com
>> +    smtpServerPort = 587
>> +    smtpAuth = XOAUTH2
>> +----
> 
> Just for my education, the above description does say why Outlook
> needs to use OAuth2.0, but does not hint the reason for the
> difference between the two example, OAUTHBEARER vs XOAUTH2.  Do
> these two services support both, or does Gmail support only
> OAUTHBEARER while Outlook supports only XOAUTH2?  

> 
> Given that the former is described in RFC and the latter sometimes
> described as "Proprietary Google extension, not a standard", it is
> somewhat funny to see that Gmail example uses OAUTHBEARER while
> Outlook example uses XOAUTH2.
> 
>> +SENDING PATCHES
>> +---------------
>> Once your commits are ready to be sent to the mailing list, run the
>> following commands:
>> 
>> @@ -536,9 +567,23 @@ following commands:
>>    $ git send-email outgoing/*
>> 
>> The first time you run it, you will be prompted for your credentials.  Enter the
>> -app-specific or your regular password as appropriate.  If you have credential
>> -helper configured (see linkgit:git-credential[1]), the password will be saved in
>> -the credential store so you won't have to type it the next time.
>> +app-specific or your regular password as appropriate.
>> +
>> +If you have a credential helper configured (see linkgit:git-credential[1]), the
>> +password will be saved in the credential store so you won't have to type it the
>> +next time.
>> +
>> +If you are using OAuth2.0 authentication, you need to use an access token in
>> +place of a password when prompted. Various OAuth2.0 token generators are
>> +available online. Community maintained credential helpers for Gmail and Outlook
>> +are also available:
>> +
>> +    - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] (cross platform, dedicated helper for authenticating Gmail accounts)
>> +
>> +    - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)
> 
> Given that this will be formatted via AsciiDoc (or asciidoctor),
> would it make sense to make it easier for readers of the source
> document by folding lines, like:
> 
>    - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail]
>      (cross platform, dedicated helper for authenticating Gmail accounts)
> 
>    - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook]
>      (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)
> 
> or something?
> 
> Other than that, very nicely done.  Thanks.