[PATCH 0/3] Improve checks for valid_fqdn in send-email and update documentation

[PATCH 0/3] Improve checks for valid_fqdn in send-email and update documentation

[Aditya Garg]

Hi all

This series of patches mainly has two changes:

1. Improve the checks for valid_fqdn in send-email to be more strict and
   compliant with RFC1035.
2. Update the documentation for send-email to include examples of using
   OAuth2.0 with Gmail and Outlook, as well as links to the credential
   helpers for these services.

Aditya Garg (3):
  send-mail: improve checks for valid_fqdn
  docs: improve send-email documentation
  docs: add credential helper for outlook and gmail in OAuth list of
    helpers

 Documentation/git-send-email.adoc | 106 ++++++++++++++++++++++++++----
 Documentation/gitcredentials.adoc |   4 ++
 git-send-email.perl               |   3 +-
 3 files changed, 99 insertions(+), 14 deletions(-)

-- 
2.49.0

[PATCH 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

The current implementation of a valid Fully Qualified Domain Name
is not that strict. It just checks whether it has a dot (.) and
if using macOS, it should not end with .local. As per RFC1035[1],
from what I understood, the following checks need to be done:

- The domain must contain atleast one dot
- Each label (separated by dots) must be 1-63 characters long
- Labels must start and end with an alphanumeric character
- Labels can contain alphanumeric characters and hyphens

Here are some examples of valid and invalid labels:

'example.com',          # Valid
'sub.example.com',      # Valid
'my-domain.org',        # Valid
'localhost',            # Invalid (no dot)
'MacBook..',            # Invalid (double dots)
'-example.com',         # Invalid (starts with a hyphen)
'example-.com',         # Invalid (ends with a hyphen)
'example..com',         # Invalid (double dots)
'example',              # Invalid (no TLD)
'example.local',        # Invalid on macOS
'valid-domain.co.uk',   # Valid
'123.example.com',      # Valid
'example.com.',         # Invalid (trailing dot)
'toolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabel.com', # Invalid (label > 63 chars)

Due to current implementation, I was not able to send emails from
Ubuntu. Upon debugging, I found that the SMTP domain was coming out
to be "MacBook.." and was being considered as valid. As a result
the script was failing. The debug logs with the failed script are
below:

Net::SMTP>>> Net::SMTP(3.15)
Net::SMTP>>>   Net::Cmd(3.15)
Net::SMTP>>>     Exporter(5.77)
Net::SMTP>>>   IO::Socket::IP(0.4101)
Net::SMTP>>>     IO::Socket(1.52)
Net::SMTP>>>       IO::Handle(1.52)
Net::SMTP=GLOB(0x5db4351225f8)<<< 220 BMXPR01CA0083.outlook.office365.com Microsoft ESMTP MAIL Service ready at Sat, 26 Apr 2025 18:06:30 +0000 [08DD842467C8274D]
Net::SMTP=GLOB(0x5db4351225f8)>>> EHLO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name [BMXPR01CA0083.INDPRD01.PROD.OUTLOOK.COM 2025-04-26T18:06:35.781Z 08DD842467C8274D]
Net::SMTP=GLOB(0x5db4351225f8)>>> HELO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name [BMXPR01CA0083.INDPRD01.PROD.OUTLOOK.COM 2025-04-26T18:06:40.828Z 08DD842467C8274D]
Unable to initialize SMTP properly. Check config and use --smtp-debug. VALUES: server=smtp.office365.com encryption=tls hello=MacBook.. port=587 at ../git-send-email.perl line 1727.

With this patch, it was fixed and was being considered as an invalid
domain. Logs after this patch:

Net::SMTP>>> Net::SMTP(3.15)
Net::SMTP>>>   Net::Cmd(3.15)
Net::SMTP>>>     Exporter(5.77)
Net::SMTP>>>   IO::Socket::IP(0.4101)
Net::SMTP>>>     IO::Socket(1.52)
Net::SMTP>>>       IO::Handle(1.52)
Net::SMTP=GLOB(0x58c8af71e930)<<< 220 PN4P287CA0064.outlook.office365.com Microsoft ESMTP MAIL Service ready at Sat, 26 Apr 2025 18:08:13 +0000 [08DD84B323498C1A]
Net::SMTP=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-STARTTLS
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP=GLOB(0x58c8af71e930)>>> STARTTLS
Net::SMTP=GLOB(0x58c8af71e930)<<< 220 2.0.0 SMTP server ready
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-AUTH LOGIN XOAUTH2
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-AUTH LOGIN XOAUTH2
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> AUTH XOAUTH2 (OAuth2 access token removed for security)
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 235 2.7.0 Authentication successful

[1]: https://datatracker.ietf.org/doc/html/rfc1035
Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 4215f8f7e9..4c143e24bf 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1359,7 +1359,8 @@ sub process_address_list {
 
 sub valid_fqdn {
 	my $domain = shift;
-	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
+	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
+		&& $domain  =~ /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})+$/;
 }
 
 sub maildomain_net {
-- 
2.49.0

Re: [PATCH 1/3] send-mail: improve checks for valid_fqdn

[Kristoffer Haugsbakk]

On Sun, May 4, 2025, at 15:54, Aditya Garg wrote:
> [1]: https://datatracker.ietf.org/doc/html/rfc1035
> Signed-off-by: Aditya Garg <gargaditya08@live.com>

Finding the s-o-b here works fine since only 25% of the trailer block
must be valid trailers, but it’s probably best in general to separate
footnotes and the trailer block with a blank line.

> ---
>  git-send-email.perl | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/git-send-email.perl b/git-send-email.perl
> index 4215f8f7e9..4c143e24bf 100755
> --- a/git-send-email.perl
> +++ b/git-send-email.perl
> @@ -1359,7 +1359,8 @@ sub process_address_list {
>
>  sub valid_fqdn {
>  	my $domain = shift;
> -	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
> && $domain =~ /\./;
> +	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
> +		&& $domain  =~
> /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})+$/;
>  }
>
>  sub maildomain_net {
> --
> 2.49.0

Re: [PATCH 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

> On 4 May 2025, at 7:53 PM, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote:
> 
> On Sun, May 4, 2025, at 15:54, Aditya Garg wrote:
>> [1]: https://datatracker.ietf.org/doc/html/rfc1035
>> Signed-off-by: Aditya Garg <gargaditya08@live.com>
> 
> Finding the s-o-b here works fine since only 25% of the trailer block
> must be valid trailers, but it’s probably best in general to separate
> footnotes and the trailer block with a blank line.

Sure. I'll wait for some more reviews and send a v2 tomorrow.

Re: [PATCH 1/3] send-mail: improve checks for valid_fqdn

[Kristoffer Haugsbakk]

On Sun, May 4, 2025, at 17:26, Aditya Garg wrote:
>> On 4 May 2025, at 7:53 PM, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote:
>>
>> On Sun, May 4, 2025, at 15:54, Aditya Garg wrote:
>>> [1]: https://datatracker.ietf.org/doc/html/rfc1035
>>> Signed-off-by: Aditya Garg <gargaditya08@live.com>
>>
>> Finding the s-o-b here works fine since only 25% of the trailer block
>> must be valid trailers, but it’s probably best in general to separate
>> footnotes and the trailer block with a blank line.
>
> Sure. I'll wait for some more reviews and send a v2 tomorrow.

If there are no other comments then that’s just a nitpick. :) Maybe a v2
won’t be needed.

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

[Aditya Garg]

This commit does the following changes to the send email doc:

1. Added examples to use OAuth2.0 with Gmail and Outlook.
2. Improved examples to send patches using git send-email
3. Added links of credential helpers for Gmail and Outlook

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 106 ++++++++++++++++++++++++++----
 1 file changed, 93 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 92389036fa..ada883289a 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -509,12 +509,12 @@ include::includes/cmd-config-section-all.adoc[]
 
 include::config/sendemail.adoc[]
 
-EXAMPLES
---------
-Use gmail as the smtp server
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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:
 
 ----
 [sendemail]
@@ -528,17 +528,97 @@ 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.
 
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
+You can also use OAuth2.0 authentication with Gmail. For that edit ~/.gitconfig
+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, we have to use OAuth2.0 authentication 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
+----
+
+SENDING PATCHES
+---------------
+The following examples can be used to have a basic idea on how to send patches
+to a mailing list:
+
+If you want to send a single patch, run:
+
+	$ git send-email --to="mailinglist@example.org" HEAD~1
+
+You can also add `--annotate` to edit the patches before sending:
+
+	$ git send-email --annotate --to="mailinglist@example.org" HEAD~1
+
+Multiple patches can also be sent. For example, if you want to send the last 3
+commits as patches, run:
+
+	$ git send-email --to="mailinglist@example.org" HEAD~3
+
+You can also add a cover letter. It is useful especially in case of multiple
+patches. Note the use of `--annotate` here since we have to edit the cover letter
+before sending it:
+
+	$ git send-email --annotate --cover-letter --to="mailinglist@example.org" HEAD~3
+
+Versions of a patch series can also be specified. For example to send a version 2:
+
+	$ git send-email --to="mailinglist@example.org" -v2 HEAD~1
+
+You can also specify custom subject prefixes. For example, to have '[PATCH RESEND]'
+as a prefix, run:
+
+	$ git send-email --to="mailinglist@example.org" --subject-prefix='PATCH RESEND' HEAD~1
+
+You can also Cc someone like this:
+
+	$ git send-email --to="mailinglist@example.org" --cc="someone@example.com HEAD~1
+
+Multiple `--to` can also be specified:
+
+	$ git send-email --to="list1@example.org" --to="list2@example.com HEAD~1
+
+Similarly you can specify multiple `--cc` as well.
 
-	$ git format-patch --cover-letter -M origin/master -o outgoing/
-	$ edit outgoing/0000-*
-	$ 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 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 with OAuth2.0 support
+for Gmail and Outlook are also available:
+
+	- https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-gmail] (cross platform, dedicated helper for authenticating Gmail accounts)
+
+	- https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-outlook] (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
 
 Note: the following core Perl modules that may be installed with your
 distribution of Perl are required:
-- 
2.49.0

[PATCH 3/3] docs: add credential helper for outlook and gmail in OAuth list of helpers

[Aditya Garg]

This commit adds the `git-credential-outlook` and `git-credential-gmail`
helpers to the list of OAuth helpers.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/gitcredentials.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gitcredentials.adoc b/Documentation/gitcredentials.adoc
index 3337bb475d..62718a0422 100644
--- a/Documentation/gitcredentials.adoc
+++ b/Documentation/gitcredentials.adoc
@@ -133,6 +133,10 @@ Popular helpers with OAuth support include:
 
     - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
 
+    - https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-gmail] (cross platform, dedicated helper to authenticate Gmail accounts for linkgit:git-send-email[1])
+
+    - https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-outlook] (cross platform, dedicated helper to authenticate Microsoft Outlook accounts for linkgit:git-send-email[1])
+
 CREDENTIAL CONTEXTS
 -------------------
 
-- 
2.49.0

[PATCH v2 0/3] Improve checks for valid_fqdn in send-email and update documentation

[Aditya Garg]

Hi all

This series of patches mainly has two changes:

1. Improve the checks for valid_fqdn in send-email to be more strict and
   compliant with RFC1035.
2. Update the documentation for send-email to include examples of using
   OAuth2.0 with Gmail and Outlook, as well as links to the credential
   helpers for these services.

v2: - Improve grammar and add missing "" in second patch.
    - Separate footnotes and the trailer block with a blank line in the first patch.

Aditya Garg (3):
  send-mail: improve checks for valid_fqdn
  docs: improve send-email documentation
  docs: add credential helper for outlook and gmail in OAuth list of
    helpers

 Documentation/git-send-email.adoc | 106 ++++++++++++++++++++++++++----
 Documentation/gitcredentials.adoc |   4 ++
 git-send-email.perl               |   3 +-
 3 files changed, 99 insertions(+), 14 deletions(-)

-- 
2.49.0

[PATCH v2 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

The current implementation of a valid Fully Qualified Domain Name
is not that strict. It just checks whether it has a dot (.) and
if using macOS, it should not end with .local. As per RFC1035[1],
from what I understood, the following checks need to be done:

- The domain must contain atleast one dot
- Each label (separated by dots) must be 1-63 characters long
- Labels must start and end with an alphanumeric character
- Labels can contain alphanumeric characters and hyphens

Here are some examples of valid and invalid labels:

'example.com',          # Valid
'sub.example.com',      # Valid
'my-domain.org',        # Valid
'localhost',            # Invalid (no dot)
'MacBook..',            # Invalid (double dots)
'-example.com',         # Invalid (starts with a hyphen)
'example-.com',         # Invalid (ends with a hyphen)
'example..com',         # Invalid (double dots)
'example',              # Invalid (no TLD)
'example.local',        # Invalid on macOS
'valid-domain.co.uk',   # Valid
'123.example.com',      # Valid
'example.com.',         # Invalid (trailing dot)
'toolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabel.com', # Invalid (label > 63 chars)

Due to current implementation, I was not able to send emails from
Ubuntu. Upon debugging, I found that the SMTP domain was coming out
to be "MacBook.." and was being considered as valid. As a result
the script was failing. The debug logs with the failed script are
below:

Net::SMTP>>> Net::SMTP(3.15)
Net::SMTP>>>   Net::Cmd(3.15)
Net::SMTP>>>     Exporter(5.77)
Net::SMTP>>>   IO::Socket::IP(0.4101)
Net::SMTP>>>     IO::Socket(1.52)
Net::SMTP>>>       IO::Handle(1.52)
Net::SMTP=GLOB(0x5db4351225f8)<<< 220 BMXPR01CA0083.outlook.office365.com Microsoft ESMTP MAIL Service ready at Sat, 26 Apr 2025 18:06:30 +0000 [08DD842467C8274D]
Net::SMTP=GLOB(0x5db4351225f8)>>> EHLO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name [BMXPR01CA0083.INDPRD01.PROD.OUTLOOK.COM 2025-04-26T18:06:35.781Z 08DD842467C8274D]
Net::SMTP=GLOB(0x5db4351225f8)>>> HELO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name [BMXPR01CA0083.INDPRD01.PROD.OUTLOOK.COM 2025-04-26T18:06:40.828Z 08DD842467C8274D]
Unable to initialize SMTP properly. Check config and use --smtp-debug. VALUES: server=smtp.office365.com encryption=tls hello=MacBook.. port=587 at ../git-send-email.perl line 1727.

With this patch, it was fixed and was being considered as an invalid
domain. Logs after this patch:

Net::SMTP>>> Net::SMTP(3.15)
Net::SMTP>>>   Net::Cmd(3.15)
Net::SMTP>>>     Exporter(5.77)
Net::SMTP>>>   IO::Socket::IP(0.4101)
Net::SMTP>>>     IO::Socket(1.52)
Net::SMTP>>>       IO::Handle(1.52)
Net::SMTP=GLOB(0x58c8af71e930)<<< 220 PN4P287CA0064.outlook.office365.com Microsoft ESMTP MAIL Service ready at Sat, 26 Apr 2025 18:08:13 +0000 [08DD84B323498C1A]
Net::SMTP=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-STARTTLS
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP=GLOB(0x58c8af71e930)>>> STARTTLS
Net::SMTP=GLOB(0x58c8af71e930)<<< 220 2.0.0 SMTP server ready
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-AUTH LOGIN XOAUTH2
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-AUTH LOGIN XOAUTH2
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> AUTH XOAUTH2 (OAuth2 access token removed for security)
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 235 2.7.0 Authentication successful

[1]: https://datatracker.ietf.org/doc/html/rfc1035

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 4215f8f7e9..4c143e24bf 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1359,7 +1359,8 @@ sub process_address_list {
 
 sub valid_fqdn {
 	my $domain = shift;
-	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
+	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
+		&& $domain  =~ /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})+$/;
 }
 
 sub maildomain_net {
-- 
2.49.0

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

[Aditya Garg]

This commit does the following changes to the send email doc:

1. Added examples to use OAuth2.0 with Gmail and Outlook.
2. Improved examples to send patches using git send-email
3. Added links of credential helpers for Gmail and Outlook

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 106 ++++++++++++++++++++++++++----
 1 file changed, 93 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 92389036fa..af29e61299 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -509,12 +509,12 @@ include::includes/cmd-config-section-all.adoc[]
 
 include::config/sendemail.adoc[]
 
-EXAMPLES
---------
-Use gmail as the smtp server
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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:
 
 ----
 [sendemail]
@@ -528,17 +528,97 @@ 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.
 
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
+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
+----
+
+SENDING PATCHES
+---------------
+The following examples can be used to have a basic idea on how to send patches
+to a mailing list:
+
+If you want to send a single patch, run:
+
+	$ git send-email --to="mailinglist@example.org" HEAD~1
+
+You can also add `--annotate` to edit the patches before sending:
+
+	$ git send-email --annotate --to="mailinglist@example.org" HEAD~1
+
+Multiple patches can also be sent. For example, if you want to send the last 3
+commits as patches, run:
+
+	$ git send-email --to="mailinglist@example.org" HEAD~3
+
+You can also add a cover letter. It is useful especially in case of multiple
+patches. Note the use of `--annotate` here since we have to edit the cover letter
+before sending it:
+
+	$ git send-email --annotate --cover-letter --to="mailinglist@example.org" HEAD~3
+
+Versions of a patch series can also be specified. For example to send a version 2:
+
+	$ git send-email --to="mailinglist@example.org" -v2 HEAD~1
+
+You can also specify custom subject prefixes. For example, to have '[PATCH RESEND]'
+as a prefix, run:
+
+	$ git send-email --to="mailinglist@example.org" --subject-prefix='PATCH RESEND' HEAD~1
+
+You can also Cc someone like this:
+
+	$ git send-email --to="mailinglist@example.org" --cc="someone@example.com" HEAD~1
+
+Multiple `--to` can also be specified:
+
+	$ git send-email --to="list1@example.org" --to="list2@example.com" HEAD~1
+
+Similarly you can specify multiple `--cc` as well.
 
-	$ git format-patch --cover-letter -M origin/master -o outgoing/
-	$ edit outgoing/0000-*
-	$ 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 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-outlook-and-gmail[git-credential-gmail] (cross platform, dedicated helper for authenticating Gmail accounts)
+
+	- https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-outlook] (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
 
 Note: the following core Perl modules that may be installed with your
 distribution of Perl are required:
-- 
2.49.0

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

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> This commit does the following changes to the send email doc:
>
> 1. Added examples to use OAuth2.0 with Gmail and Outlook.
> 2. Improved examples to send patches using git send-email
> 3. Added links of credential helpers for Gmail and Outlook

The usual way to compose a log message of this project is to

 - Give an observation on how the current system works in the present
   tense (so no need to say "Currently X is Y", just "X is Y"), and
   discuss what you perceive as a problem in it.

 - Propose a solution (optional---often, problem description
   trivially leads to an obvious solution in reader's minds).

 - Give commands to the codebase to "become like so".

in this order.  Don't throw a bulleted list at readers without
preparing them by explaining what problem you are solving and why
such a solution is needed.

> +SENDING PATCHES
> +---------------
> +The following examples can be used to have a basic idea on how to send patches
> +to a mailing list:
> +
> +If you want to send a single patch, run:
> +
> +	$ git send-email --to="mailinglist@example.org" HEAD~1
> ...
> -	$ git format-patch --cover-letter -M origin/master -o outgoing/
> -	$ edit outgoing/0000-*
> -	$ git send-email outgoing/*

All good intentions to improve the documentation, but loss of these
lines is very much lamentable, especially the fact that these
original instructions were written to encourage to run format-patch
and send-email as separate steps, with proofreading and final
copy-editing step in between.

It means the author has a chance to spend more time and care to help
recipients read their patches more smoothly with fewer typoes and
improved explanations.

Running "git send-email" with the revision range to run the "git
format-patch" command is often an anti-pattern, especially for
unexperienced people who are still learning from the examples in the
documentation.  Please do not unnecessarily promote the use of it.

Thanks.

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

[Aditya Garg]

> On 6 May 2025, at 12:50 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>> This commit does the following changes to the send email doc:
>> 
>> 1. Added examples to use OAuth2.0 with Gmail and Outlook.
>> 2. Improved examples to send patches using git send-email
>> 3. Added links of credential helpers for Gmail and Outlook
> 
> The usual way to compose a log message of this project is to
> 
> - Give an observation on how the current system works in the present
>   tense (so no need to say "Currently X is Y", just "X is Y"), and
>   discuss what you perceive as a problem in it.
> 
> - Propose a solution (optional---often, problem description
>   trivially leads to an obvious solution in reader's minds).
> 
> - Give commands to the codebase to "become like so".
> 
> in this order.  Don't throw a bulleted list at readers without
> preparing them by explaining what problem you are solving and why
> such a solution is needed.
> 
>> +SENDING PATCHES
>> +---------------
>> +The following examples can be used to have a basic idea on how to send patches
>> +to a mailing list:
>> +
>> +If you want to send a single patch, run:
>> +
>> +    $ git send-email --to="mailinglist@example.org" HEAD~1
>> ...
>> -    $ git format-patch --cover-letter -M origin/master -o outgoing/
>> -    $ edit outgoing/0000-*
>> -    $ git send-email outgoing/*
> 
> All good intentions to improve the documentation, but loss of these
> lines is very much lamentable, especially the fact that these
> original instructions were written to encourage to run format-patch
> and send-email as separate steps, with proofreading and final
> copy-editing step in between.
> 
> It means the author has a chance to spend more time and care to help
> recipients read their patches more smoothly with fewer typoes and
> improved explanations.
> 
> Running "git send-email" with the revision range to run the "git
> format-patch" command is often an anti-pattern, especially for
> unexperienced people who are still learning from the examples in the
> documentation.  Please do not unnecessarily promote the use of it.

Fair. I'll revert that section. You want me to revert the OAuth2.0 examples
as well?

[PATCH v2 3/3] docs: add credential helper for outlook and gmail in OAuth list of helpers

[Aditya Garg]

This commit adds the `git-credential-outlook` and `git-credential-gmail`
helpers to the list of OAuth helpers.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/gitcredentials.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gitcredentials.adoc b/Documentation/gitcredentials.adoc
index 3337bb475d..62718a0422 100644
--- a/Documentation/gitcredentials.adoc
+++ b/Documentation/gitcredentials.adoc
@@ -133,6 +133,10 @@ Popular helpers with OAuth support include:
 
     - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
 
+    - https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-gmail] (cross platform, dedicated helper to authenticate Gmail accounts for linkgit:git-send-email[1])
+
+    - https://github.com/AdityaGarg8/git-credential-outlook-and-gmail[git-credential-outlook] (cross platform, dedicated helper to authenticate Microsoft Outlook accounts for linkgit:git-send-email[1])
+
 CREDENTIAL CONTEXTS
 -------------------
 
-- 
2.49.0

[PATCH v3 0/3] Improve checks for valid_fqdn in send-email and update documentation

[Aditya Garg]

Hi all

This series of patches mainly has two changes:

1. Improve the checks for valid_fqdn in send-email to be more strict and
   compliant with RFC1035.
2. Update the documentation for send-email to include examples of using
   OAuth2.0 with Gmail and Outlook, as well as links to the credential
   helpers for these services.

P.S. I have used `git-credential-outlook` linked in the second and third
patch for this email!

v2: - Improve grammar and add missing "" in second patch.
    - Separate footnotes and the trailer block with a blank line in the first patch.

v3: - Change link for email helpers since old one was too long.

Aditya Garg (3):
  send-mail: improve checks for valid_fqdn
  docs: improve send-email documentation
  docs: add credential helper for outlook and gmail in OAuth list of
    helpers

 Documentation/git-send-email.adoc | 106 ++++++++++++++++++++++++++----
 Documentation/gitcredentials.adoc |   4 ++
 git-send-email.perl               |   3 +-
 3 files changed, 99 insertions(+), 14 deletions(-)

-- 
2.49.0

[PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

The current implementation of a valid Fully Qualified Domain Name
is not that strict. It just checks whether it has a dot (.) and
if using macOS, it should not end with .local. As per RFC1035[1],
from what I understood, the following checks need to be done:

- The domain must contain atleast one dot
- Each label (separated by dots) must be 1-63 characters long
- Labels must start and end with an alphanumeric character
- Labels can contain alphanumeric characters and hyphens

Here are some examples of valid and invalid labels:

'example.com',          # Valid
'sub.example.com',      # Valid
'my-domain.org',        # Valid
'localhost',            # Invalid (no dot)
'MacBook..',            # Invalid (double dots)
'-example.com',         # Invalid (starts with a hyphen)
'example-.com',         # Invalid (ends with a hyphen)
'example..com',         # Invalid (double dots)
'example',              # Invalid (no TLD)
'example.local',        # Invalid on macOS
'valid-domain.co.uk',   # Valid
'123.example.com',      # Valid
'example.com.',         # Invalid (trailing dot)
'toolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabel.com', # Invalid (label > 63 chars)

Due to current implementation, I was not able to send emails from
Ubuntu. Upon debugging, I found that the SMTP domain was coming out
to be "MacBook.." and was being considered as valid. As a result
the script was failing. The debug logs with the failed script are
below:

Net::SMTP>>> Net::SMTP(3.15)
Net::SMTP>>>   Net::Cmd(3.15)
Net::SMTP>>>     Exporter(5.77)
Net::SMTP>>>   IO::Socket::IP(0.4101)
Net::SMTP>>>     IO::Socket(1.52)
Net::SMTP>>>       IO::Handle(1.52)
Net::SMTP=GLOB(0x5db4351225f8)<<< 220 BMXPR01CA0083.outlook.office365.com Microsoft ESMTP MAIL Service ready at Sat, 26 Apr 2025 18:06:30 +0000 [08DD842467C8274D]
Net::SMTP=GLOB(0x5db4351225f8)>>> EHLO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name [BMXPR01CA0083.INDPRD01.PROD.OUTLOOK.COM 2025-04-26T18:06:35.781Z 08DD842467C8274D]
Net::SMTP=GLOB(0x5db4351225f8)>>> HELO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name [BMXPR01CA0083.INDPRD01.PROD.OUTLOOK.COM 2025-04-26T18:06:40.828Z 08DD842467C8274D]
Unable to initialize SMTP properly. Check config and use --smtp-debug. VALUES: server=smtp.office365.com encryption=tls hello=MacBook.. port=587 at ../git-send-email.perl line 1727.

With this patch, it was fixed and was being considered as an invalid
domain. Logs after this patch:

Net::SMTP>>> Net::SMTP(3.15)
Net::SMTP>>>   Net::Cmd(3.15)
Net::SMTP>>>     Exporter(5.77)
Net::SMTP>>>   IO::Socket::IP(0.4101)
Net::SMTP>>>     IO::Socket(1.52)
Net::SMTP>>>       IO::Handle(1.52)
Net::SMTP=GLOB(0x58c8af71e930)<<< 220 PN4P287CA0064.outlook.office365.com Microsoft ESMTP MAIL Service ready at Sat, 26 Apr 2025 18:08:13 +0000 [08DD84B323498C1A]
Net::SMTP=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-STARTTLS
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP=GLOB(0x58c8af71e930)>>> STARTTLS
Net::SMTP=GLOB(0x58c8af71e930)<<< 220 2.0.0 SMTP server ready
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-AUTH LOGIN XOAUTH2
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello [2401:4900:a052:31f0:9beb:e613:56e8:f897]
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-SIZE 157286400
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-PIPELINING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-DSN
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-ENHANCEDSTATUSCODES
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-AUTH LOGIN XOAUTH2
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-8BITMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-BINARYMIME
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250-CHUNKING
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 250 SMTPUTF8
Net::SMTP::_SSL=GLOB(0x58c8af71e930)>>> AUTH XOAUTH2 (OAuth2 access token removed for security)
Net::SMTP::_SSL=GLOB(0x58c8af71e930)<<< 235 2.7.0 Authentication successful

[1]: https://datatracker.ietf.org/doc/html/rfc1035

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 4215f8f7e9..4c143e24bf 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1359,7 +1359,8 @@ sub process_address_list {
 
 sub valid_fqdn {
 	my $domain = shift;
-	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
+	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
+		&& $domain  =~ /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})+$/;
 }
 
 sub maildomain_net {
-- 
2.49.0

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> Due to current implementation, I was not able to send emails from
> Ubuntu.

It may be that send-email did not complain, but I have a suspicion
that it the above is only half truth.  We do have an ugly last-ditch
fallback to claim that we are localhost.localdomain, instead of
using a misconfigured maildomain name that servers would not like,
but that name is a meaningless name; from the point of view of the
server, if everybody uses that name, the name loses the meaning as
an identifier.

It is more like due to misconfiguration you couldn't send e-mails,
and by tightening the condition to tell an invalid maildomain name
and have the misconfigured maildomain name that is invalid replaced
with "localhost.localdomain" fallback, you managed to send things
out.

The real fix for individual users may probably be to see how
maildomain_net() and/or maildomain_mta() gives you a bogus
"Macbook.." and fix _that_.  Until that gets fixed, trying to use
"localhost.localdomain" fallback might be a good workaround, but
that is a workaround, not a real solution, isn't it?

When using this fallback, we are at server's mercy; if a server
checks the name you give it against your IP address, for example,
the "localhost.localdomain" fallback may be rejected and you would
need to figure out the real maildomain name the server wants you to
identify as.  What I am worried about this patch the most is if it
is tightening valid_fqdn too much to make a good maildomain name
that real users are currently using to cause them to instead use the
"localhost.localdomain" fallback, and their SMTP servers are not
as lenient as your case and start rejecting their requests.

With a cursory read of this patch, I think basic "at most 63 Alnum
or dash" DNS label defined in the ASCII-only era may be sufficient
for 99% of the users, so I am not too worried by this particular
change (I do not think anybody uses those UUCP!style!addresses
anymore these days), but this patch is an example why we always
want to be careful not to introduce unintended regressions.

> Upon debugging, I found that the SMTP domain was coming out
> to be "MacBook.." and was being considered as valid.

"as valid." -> "as valid, which prevented the fallback
localhost.localdomain from being used."

> As a result
> the script was failing. The debug logs with the failed script are
> below:

Don't give overly long and irrelevant details.  Say something like

	The SMTP exchange started like this:

	<<< 220 ...outlook.office365.com Microsoft ...
	>>> EHLO MacBook..
	<<< 501 5.5.4 Invalid domain name ...

	Notice that an invalid domain name "MacBook.." is sent by
	git-send-email.  We have a fallback code that checks output
	from Net::Domain::domainname() or asking domain method of an
	Net::SMTP instance to detect a misconfigured hostname and
	replace it with fallback "localhost.localdomain", but
	the valid_fqdn apparently is failing to say "MacBook.." is
	not a valid_fqdn.

	With this patch, the rule used in valid_fqdn is tightened,
	the beginning part of the SMTP exchange looked like this:

	<<< 220 ...outlook.office365.com Microsoft ...
	>>> EHLO localhost.localdomain
	<<< 250-250-PN4P287CA0064.outlook.office365.com Hello ...
	<<< 250 ...

	and the server I was using to test this patch was happy with
	the fallback "localhost.localdomain":

perhaps?

Thanks.

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

> On 6 May 2025, at 5:19 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>> Due to current implementation, I was not able to send emails from
>> Ubuntu.
> 
> It may be that send-email did not complain, but I have a suspicion
> that it the above is only half truth.  We do have an ugly last-ditch
> fallback to claim that we are localhost.localdomain, instead of
> using a misconfigured maildomain name that servers would not like,
> but that name is a meaningless name; from the point of view of the
> server, if everybody uses that name, the name loses the meaning as
> an identifier.
> 
> It is more like due to misconfiguration you couldn't send e-mails,
> and by tightening the condition to tell an invalid maildomain name
> and have the misconfigured maildomain name that is invalid replaced
> with "localhost.localdomain" fallback, you managed to send things
> out.
> 
> The real fix for individual users may probably be to see how
> maildomain_net() and/or maildomain_mta() gives you a bogus
> "Macbook.." and fix _that_.  Until that gets fixed, trying to use
> "localhost.localdomain" fallback might be a good workaround, but
> that is a workaround, not a real solution, isn't it?

I think I should dig deeper on how the domain name is being assigned.

Maybe its time to fix another perl module after Authen::SASL?

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

> On 6 May 2025, at 11:08 AM, Aditya Garg <gargaditya08@live.com> wrote:
> 
> 
> 
>> On 6 May 2025, at 5:19 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> 
>> Aditya Garg <gargaditya08@live.com> writes:
>> 
>>> Due to current implementation, I was not able to send emails from
>>> Ubuntu.
>> 
>> It may be that send-email did not complain, but I have a suspicion
>> that it the above is only half truth.  We do have an ugly last-ditch
>> fallback to claim that we are localhost.localdomain, instead of
>> using a misconfigured maildomain name that servers would not like,
>> but that name is a meaningless name; from the point of view of the
>> server, if everybody uses that name, the name loses the meaning as
>> an identifier.
>> 
>> It is more like due to misconfiguration you couldn't send e-mails,
>> and by tightening the condition to tell an invalid maildomain name
>> and have the misconfigured maildomain name that is invalid replaced
>> with "localhost.localdomain" fallback, you managed to send things
>> out.
>> 
>> The real fix for individual users may probably be to see how
>> maildomain_net() and/or maildomain_mta() gives you a bogus
>> "Macbook.." and fix _that_.  Until that gets fixed, trying to use
>> "localhost.localdomain" fallback might be a good workaround, but
>> that is a workaround, not a real solution, isn't it?
> 
> I think I should dig deeper on how the domain name is being assigned.
> 
> Maybe its time to fix another perl module after Authen::SASL?

I've noticed bug reports regarding this in Net::Domain perl library.
Most reports seem to be not addressed. Maybe its no longer maintained?

I think we can add a minimal check to ensure that there are no two dots together.
Does that sound fair?

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

On 06/05/25 3:05 pm, Aditya Garg wrote:
> 
> 
>> On 6 May 2025, at 11:08 AM, Aditya Garg <gargaditya08@live.com> wrote:
>>
>> 
>>
>>> On 6 May 2025, at 5:19 AM, Junio C Hamano <gitster@pobox.com> wrote:
>>>
>>> Aditya Garg <gargaditya08@live.com> writes:
>>>
>>>> Due to current implementation, I was not able to send emails from
>>>> Ubuntu.
>>>
>>> It may be that send-email did not complain, but I have a suspicion
>>> that it the above is only half truth.  We do have an ugly last-ditch
>>> fallback to claim that we are localhost.localdomain, instead of
>>> using a misconfigured maildomain name that servers would not like,
>>> but that name is a meaningless name; from the point of view of the
>>> server, if everybody uses that name, the name loses the meaning as
>>> an identifier.
>>>
>>> It is more like due to misconfiguration you couldn't send e-mails,
>>> and by tightening the condition to tell an invalid maildomain name
>>> and have the misconfigured maildomain name that is invalid replaced
>>> with "localhost.localdomain" fallback, you managed to send things
>>> out.
>>>
>>> The real fix for individual users may probably be to see how
>>> maildomain_net() and/or maildomain_mta() gives you a bogus
>>> "Macbook.." and fix _that_.  Until that gets fixed, trying to use
>>> "localhost.localdomain" fallback might be a good workaround, but
>>> that is a workaround, not a real solution, isn't it?
>>
>> I think I should dig deeper on how the domain name is being assigned.
>>
>> Maybe its time to fix another perl module after Authen::SASL?
> 
> I've noticed bug reports regarding this in Net::Domain perl library.
> Most reports seem to be not addressed. Maybe its no longer maintained?
> 
> I think we can add a minimal check to ensure that there are no two dots together.
> Does that sound fair?

I have opened a PR here to fix the Net::Domain library:

https://github.com/steve-m-hay/perl-libnet/pull/47


Although, this library is still seems quite unreliable. See:

1. https://github.com/Perl/perl5/issues/17135
2. https://github.com/glpi-project/glpi-agent/discussions/345

I really doubt the maintainer still maintains this. I have added them to the Cc though.

As far as the script is concerned,

- The script currently checks the presence of a period in the fqdn.
- At the same time, the script does NOT check whether the fqdn starts or ends with a period.
- Also, it does NOT check if 2 periods are together or not.

a fqdn without a dot at all gets accepted by my Outlook server, but the next 2 cases are a big
no. I think adding checks for these cases should make sense, afterall no FQDN would have these
things.

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> As far as the script is concerned,
>
> - The script currently checks the presence of a period in the fqdn.

I suspect that this is overly strict in a strictly local settings.

> - At the same time, the script does NOT check whether the fqdn
> starts or ends with a period.

As a DNS domainname, starting with is problematic, but ending with a
period (e.g., "example.com.") should be OK, as long as the last
label is truly a top-level domain name.  I however think 

> - Also, it does NOT check if 2 periods are together or not.

That does sound problematic.

> a fqdn without a dot at all gets accepted by my Outlook server, ...
> ... afterall no FQDN would have these things.

True; we need to be careful here, though---after all the world is
not necessarily RFC 5321 compliant, as your Outlook server shows, if
accepts a name without any dot and is not a top-level domain.

So I think "one or more <upto 63 octet run of alnum or hyphen that
does not begin or end with hyphen>, separated by a single dot in
between each" (which is probably what you wanted to say in your
regexp, even though it wasn't clear to me if you restricted the
second and subsequent labels like you did the first one correctly)
would be a reasonable check to have.

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> I think we can add a minimal check to ensure that there are no two dots together.
> Does that sound fair?

Is it a common misconfiguration in the first place that singling out
a name ending with double dots (which indeed is very likely that
nobody should be relying on getting accepted by sensible SMTP
servers, hence very safe tightening) is worth doing?  If MacBooks as
shipped would by default claim to be "MacBook.." like your example
had (I do not know if that is the case, as I do not live in Apple
ecosystem), it may give us a reason to special case the trailing
double-dots, for example.

I personally feel that "run of at most 63 alnum or dash separated by
a single dot in between" is easy enough to explain, so if I were
doing this change, I would just use the regexp used in posted patch
[*] and if nobody complains, stop right there.  If we get any
complaint, then I'd detect and reject the case where the string ends
with double-dots.

[Footnote]

 * ... but I don't know if your use of negative lookaround
   assersions is correct.  Shouldn't the "a label cannot begin or
   end with dash" be applied not just to the first label but
   consistently to all of the dot-separated labels?

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

On 06/05/25 10:41 pm, Junio C Hamano wrote:
> Aditya Garg <gargaditya08@live.com> writes:
> 
>> I think we can add a minimal check to ensure that there are no two dots together.
>> Does that sound fair?
> 
> Is it a common misconfiguration in the first place that singling out
> a name ending with double dots (which indeed is very likely that
> nobody should be relying on getting accepted by sensible SMTP
> servers, hence very safe tightening) is worth doing?  If MacBooks as
> shipped would by default claim to be "MacBook.." like your example
> had (I do not know if that is the case, as I do not live in Apple
> ecosystem), it may give us a reason to special case the trailing
> double-dots, for example.

Its not an Apple thing. I am not even using macOS at the first place
when I tested this, I was on Ubuntu running on my Mac.

Its a problem with Net::Domain. In systems without a domainname, and
without a period in the hostname, Net::Domain will always output
"hostname..". You probably should check your machine with smtp-debug?
Btw, the output of `hostname -f` on these machines will be "hostname".

Now gmail does not reject this, probably the reason it is unnoticed?
Since Outlook support is new, such problems are being observed.


> 
> I personally feel that "run of at most 63 alnum or dash separated by
> a single dot in between" is easy enough to explain, so if I were
> doing this change, I would just use the regexp used in posted patch
> [*] and if nobody complains, stop right there.  If we get any
> complaint, then I'd detect and reject the case where the string ends
> with double-dots.

The regexp used in the original patch covers the double dots case as well.
Its basically following the RFC guidelines, which a sensible SMTP server
should follow, and so must a user.

> 
> [Footnote]
> 
>  * ... but I don't know if your use of negative lookaround
>    assersions is correct.  Shouldn't the "a label cannot begin or
>    end with dash" be applied not just to the first label but
>    consistently to all of the dot-separated labels?

I think you are talking about this case:

someone.-example.com

No, its not valid.a

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

> On 6 May 2025, at 10:53 PM, Aditya Garg <gargaditya08@live.com> wrote:
> 
> 
> 
>> On 06/05/25 10:41 pm, Junio C Hamano wrote:
>> Aditya Garg <gargaditya08@live.com> writes:
>> 
>>> I think we can add a minimal check to ensure that there are no two dots together.
>>> Does that sound fair?
>> 
>> Is it a common misconfiguration in the first place that singling out
>> a name ending with double dots (which indeed is very likely that
>> nobody should be relying on getting accepted by sensible SMTP
>> servers, hence very safe tightening) is worth doing?  If MacBooks as
>> shipped would by default claim to be "MacBook.." like your example
>> had (I do not know if that is the case, as I do not live in Apple
>> ecosystem), it may give us a reason to special case the trailing
>> double-dots, for example.
> 
> Its not an Apple thing. I am not even using macOS at the first place
> when I tested this, I was on Ubuntu running on my Mac.
> 
> Its a problem with Net::Domain. In systems without a domainname, and
> without a period in the hostname, Net::Domain will always output
> "hostname..". You probably should check your machine with smtp-debug?
> Btw, the output of `hostname -f` on these machines will be "hostname".
> 
> Now gmail does not reject this, probably the reason it is unnoticed?
> Since Outlook support is new, such problems are being observed.
> 
> 
>> 
>> I personally feel that "run of at most 63 alnum or dash separated by
>> a single dot in between" is easy enough to explain, so if I were
>> doing this change, I would just use the regexp used in posted patch
>> [*] and if nobody complains, stop right there.  If we get any
>> complaint, then I'd detect and reject the case where the string ends
>> with double-dots.
> 
> The regexp used in the original patch covers the double dots case as well.
> Its basically following the RFC guidelines, which a sensible SMTP server
> should follow, and so must a user.
> 
>> 
>> [Footnote]
>> 
>> * ... but I don't know if your use of negative lookaround
>>   assersions is correct.  Shouldn't the "a label cannot begin or
>>   end with dash" be applied not just to the first label but
>>   consistently to all of the dot-separated labels?
> 
> I think you are talking about this case:
> 
> someone.-example.com
> 
> No, its not valid.a

Although my regex is considering it as valid, which I can fix, but I'd rather wait
for us to come to a conclusion on how we are fixing this in the first place.

Re: [PATCH v3 1/3] send-mail: improve checks for valid_fqdn

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

>>  * ... but I don't know if your use of negative lookaround
>>    assersions is correct.  Shouldn't the "a label cannot begin or
>>    end with dash" be applied not just to the first label but
>>    consistently to all of the dot-separated labels?
>
> I think you are talking about this case:
>
> someone.-example.com
>
> No, its not valid.a

I was not talking about any "case"; I was talking more about your
regexp to catch invalid addresses.  From RFC 5321,

    helo       = "HELO" SP Domain CRLF
    Domain     = sub-domain *("." sub-domain)
    sub-domain = Let-dig [Ldh-str]
    Let-dig    = ALPHA / DIGIT
    Ldh-str    = *( ALPHA / DIGIT / "-" ) Let-dig

so the syntax for first "sub-domain" applies equally to the other
"sub-domain".  If "-example" cannot be the third-level subdomain,
then it equally cannot be the second-level, either, but IIRC, the
patch had regexp that treated the first level differently from the
rest.

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

[Aditya Garg]

This commit does the following changes to the send email doc:

1. Added examples to use OAuth2.0 with Gmail and Outlook.
2. Improved examples to send patches using git send-email
3. Added links of credential helpers for Gmail and Outlook

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 106 ++++++++++++++++++++++++++----
 1 file changed, 93 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 92389036fa..f30f573209 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -509,12 +509,12 @@ include::includes/cmd-config-section-all.adoc[]
 
 include::config/sendemail.adoc[]
 
-EXAMPLES
---------
-Use gmail as the smtp server
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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:
 
 ----
 [sendemail]
@@ -528,17 +528,97 @@ 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.
 
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
+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
+----
+
+SENDING PATCHES
+---------------
+The following examples can be used to have a basic idea on how to send patches
+to a mailing list:
+
+If you want to send a single patch, run:
+
+	$ git send-email --to="mailinglist@example.org" HEAD~1
+
+You can also add `--annotate` to edit the patches before sending:
+
+	$ git send-email --annotate --to="mailinglist@example.org" HEAD~1
+
+Multiple patches can also be sent. For example, if you want to send the last 3
+commits as patches, run:
+
+	$ git send-email --to="mailinglist@example.org" HEAD~3
+
+You can also add a cover letter. It is useful especially in case of multiple
+patches. Note the use of `--annotate` here since we have to edit the cover letter
+before sending it:
+
+	$ git send-email --annotate --cover-letter --to="mailinglist@example.org" HEAD~3
+
+Versions of a patch series can also be specified. For example to send a version 2:
+
+	$ git send-email --to="mailinglist@example.org" -v2 HEAD~1
+
+You can also specify custom subject prefixes. For example, to have '[PATCH RESEND]'
+as a prefix, run:
+
+	$ git send-email --to="mailinglist@example.org" --subject-prefix='PATCH RESEND' HEAD~1
+
+You can also Cc someone like this:
+
+	$ git send-email --to="mailinglist@example.org" --cc="someone@example.com" HEAD~1
+
+Multiple `--to` can also be specified:
+
+	$ git send-email --to="list1@example.org" --to="list2@example.com" HEAD~1
+
+Similarly you can specify multiple `--cc` as well.
 
-	$ git format-patch --cover-letter -M origin/master -o outgoing/
-	$ edit outgoing/0000-*
-	$ 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 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)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
 
 Note: the following core Perl modules that may be installed with your
 distribution of Perl are required:
-- 
2.49.0

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

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> +If you want to send a single patch, run:
> +
> +	$ git send-email --to="mailinglist@example.org" HEAD~1

Didn't I already tell you not to encourage to run format-patch from
send-email all over the place?  Just prepare the mail files once,
and feed them, perhaps

    ... how to send patches to a mailing list from a set of patch
    files you prepared with `git format-patch`.

    If you want to send a single patch:

	$ git send-email --to="there" 0001-fix-this.patch

    Or more than one

	$ git send-email --to="there" patches/000[1-4]*.patch

etc.

> -	$ git format-patch --cover-letter -M origin/master -o outgoing/
> -	$ edit outgoing/0000-*
> -	$ git send-email outgoing/*

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

[Aditya Garg]

> On 6 May 2025, at 5:24 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>> +If you want to send a single patch, run:
>> +
>> +    $ git send-email --to="mailinglist@example.org" HEAD~1
> 
> Didn't I already tell you not to encourage to run format-patch from
> send-email all over the place?  Just prepare the mail files once,
> and feed them, perhaps

This version was sent before your review ;)
> 
>    ... how to send patches to a mailing list from a set of patch
>    files you prepared with `git format-patch`.
> 
>    If you want to send a single patch:
> 
>    $ git send-email --to="there" 0001-fix-this.patch
> 
>    Or more than one
> 
>    $ git send-email --to="there" patches/000[1-4]*.patch
> 
> etc.
> 
>> -    $ git format-patch --cover-letter -M origin/master -o outgoing/
>> -    $ edit outgoing/0000-*
>> -    $ git send-email outgoing/*

[PATCH v3 3/3] docs: add credential helper for outlook and gmail in OAuth list of helpers

[Aditya Garg]

This commit adds the `git-credential-outlook` and `git-credential-gmail`
helpers to the list of OAuth helpers.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/gitcredentials.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gitcredentials.adoc b/Documentation/gitcredentials.adoc
index 3337bb475d..b49923db02 100644
--- a/Documentation/gitcredentials.adoc
+++ b/Documentation/gitcredentials.adoc
@@ -133,6 +133,10 @@ Popular helpers with OAuth support include:
 
     - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
 
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] (cross platform, dedicated helper to authenticate Gmail accounts for linkgit:git-send-email[1])
+
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] (cross platform, dedicated helper to authenticate Microsoft Outlook accounts for linkgit:git-send-email[1])
+
 CREDENTIAL CONTEXTS
 -------------------
 
-- 
2.49.0

[PATCH v4 0/3] Improve checks for valid_fqdn in send-email and update documentation

[Aditya Garg]

Hi all

This series of patches mainly has two changes:

1. Improve the checks for valid_fqdn in send-email to be more strict and
   compliant with RFC1035.
2. Update the documentation for send-email to include examples of using
   OAuth2.0 with Gmail and Outlook, as well as links to the credential
   helpers for these services.

P.S. I have used `git-credential-outlook` linked in the second and third
patch for this email!

v2: - Improve grammar and add missing "" in second patch.
    - Separate footnotes and the trailer block with a blank line in the first
      patch.

v3: - Change link for email helpers since old one was too long.

v4: - Improve log message of first and second patch.
    - Update valid_fqdn check in first patch to allow one or more <upto 63
      octet run of alnum or hyphen that does not begin or end with hyphen>,
      separated by a single dot in between each.
    - Revert the documentation regarding sending patches to a mailing list
      in the second patch.

Aditya Garg (3):
  send-mail: improve checks for valid_fqdn
  docs: improve send-email documentation
  docs: add credential helper for outlook and gmail in OAuth list of
    helpers

 Documentation/git-send-email.adoc | 61 +++++++++++++++++++++++++++----
 Documentation/gitcredentials.adoc |  4 ++
 git-send-email.perl               |  3 +-
 3 files changed, 59 insertions(+), 9 deletions(-)

-- 
2.49.0

[PATCH v4 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

The current implementation of a valid Fully Qualified Domain Name
is not that strict. It just checks whether it has a dot (.) and
if using macOS, it should not end with .local. As per RFC1035[1],
from what I understood, the following checks need to be done:

- The domain must contain atleast one dot
- Each label (separated by dots) must be 1-63 characters long
- Labels must start and end with an alphanumeric character
- Labels can contain alphanumeric characters and hyphens

Here are some examples of valid and invalid labels:

'example.com',          # Valid
'sub.example.com',      # Valid
'my-domain.org',        # Valid
'localhost',            # Invalid (no dot)
'MacBook..',            # Invalid (double dots)
'-example.com',         # Invalid (starts with a hyphen)
'example-.com',         # Invalid (ends with a hyphen)
'example..com',         # Invalid (double dots)
'example',              # Invalid (no TLD)
'example.local',        # Invalid on macOS
'valid-domain.co.uk',   # Valid
'123.example.com',      # Valid
'example.com.',         # Invalid (trailing dot)
'toolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabel.com', # Invalid (label > 63 chars)

Due to current implementation, I was not able to send emails from
Ubuntu. Upon debugging, I found that the SMTP domain being passed
to Outlook's servers was not valid.

Net::SMTP=GLOB(0x5db4351225f8)>>> EHLO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name
Net::SMTP=GLOB(0x5db4351225f8)>>> HELO MacBook..

Notice that an invalid domain name "MacBook.." is sent by git-send-email.
We have a fallback code that checks output from Net::Domain::domainname()
or asking domain method of an Net::SMTP instance to detect a misconfigured
hostname and replace it with fallback "localhost.localdomain", but the
valid_fqdn apparently is failing to say "MacBook.." is not a valid fqdn.

With this patch, the rule used in valid_fqdn is tightened, the beginning
part of the SMTP exchange looked like this:

Net::SMTP=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello

[1]: https://datatracker.ietf.org/doc/html/rfc1035

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 4215f8f7e9..17d26dffde 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1359,7 +1359,8 @@ sub process_address_list {
 
 sub valid_fqdn {
 	my $domain = shift;
-	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
+	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
+		&& $domain  =~ /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))*$/;
 }
 
 sub maildomain_net {
-- 
2.49.0

Re: [PATCH v4 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

> ---
>  git-send-email.perl | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/git-send-email.perl b/git-send-email.perl
> index 4215f8f7e9..17d26dffde 100755
> --- a/git-send-email.perl
> +++ b/git-send-email.perl
> @@ -1359,7 +1359,8 @@ sub process_address_list {
>  
>  sub valid_fqdn {
>  	my $domain = shift;
> -	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
> +	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
> +		&& $domain  =~ /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))*$/;
>  }
>  
>  sub maildomain_net {

FWIW, if you wanna test this regexp, this simple perl script could help:

---->8----
#!/usr/bin/perl

my @domains = ("macbook",
               "example.com",
               "-bad.com",
               "too..many.dots",
               "good-domain.org",
               "someone.-example.com",
               "some.hdhd-.com");

foreach my $d (@domains) {
    if ($d =~ /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))*$/) {
        print "$d => Valid\n";
    } else {
        print "$d => Invalid\n";
    }
}
----------

Also I am thinking of using `hostname -f` as a method to be used on Linux and macOS before
using the Net::Domain library.

Re: [PATCH v4 1/3] send-mail: improve checks for valid_fqdn

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

>  sub valid_fqdn {
>  	my $domain = shift;
> -	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
> +	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
> +		&& $domain  =~ /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))*$/;

Yuck, can we do something about this overly long mess?  

If use a temporary $subdomain = '(?!-)[A-Za-z0-9-]{1,63}(?<!-)',
would it make it easier to spot the repetition in the structure,
i.e. /^$subdomain(?:\.$subdomain)*$/ and make it less error prone
when somebody has to touch lines around here, or something?

But other than that, looking good.

Even though this allows "foo.local", on "darwin" it is still not
allowed, which sounds like a regression-free change.

Thanks.

Re: [PATCH v4 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

> Yuck, can we do something about this overly long mess?  
> 
> If use a temporary $subdomain = '(?!-)[A-Za-z0-9-]{1,63}(?<!-)',
> would it make it easier to spot the repetition in the structure,
> i.e. /^$subdomain(?:\.$subdomain)*$/ and make it less error prone
> when somebody has to touch lines around here, or something?
> 
> But other than that, looking good.
> 
> Even though this allows "foo.local", on "darwin" it is still not
> allowed, which sounds like a regression-free change

Sent a version 5 here: https://lore.kernel.org/git/PN3PR01MB95974932FF37D9F24A7633C6B88BA@PN3PR01MB9597.INDPRD01.PROD.OUTLOOK.COM/T/#t

I forgot to add --in-reply-to while using git send-email to send v5, so it got sent
as a separate thread by mistake.

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

[Aditya Garg]

OAuth2.0 is a new authentication method that is being used by many email
providers, including Outlook and Gmail. Recently, the Authen::SASL perl
module has been updated to support OAuth2.0 authentication, thus making
the git-send-email script be able to use this authentication method as
well. So lets improve the documentation to reflect this change.

I also had a hard time finding a reliable OAuth2.0 access token
generator for Outlook and Gmail. So I added a link to the such
generators which I developed myself after seaching through lots of code
and API documentation to make things easier for others.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 61 +++++++++++++++++++++++++++----
 1 file changed, 53 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 92389036fa..26df6514c1 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -509,12 +509,12 @@ include::includes/cmd-config-section-all.adoc[]
 
 include::config/sendemail.adoc[]
 
-EXAMPLES
---------
-Use gmail as the smtp server
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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:
 
 ----
 [sendemail]
@@ -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
+----
+
+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)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
 
 Note: the following core Perl modules that may be installed with your
 distribution of Perl are required:
-- 
2.49.0

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

[Junio C Hamano]

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

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

[Aditya Garg]

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

I think ~/.gitconfig should be in single quotes, its not a command.

> 
>> @@ -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?  

Gmail supports for OAUTHBEARER and XOAUTH2. I added OAUTHBEARER
just for the sake of a different example. I think addding 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).
> 
> 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.

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

[Junio C Hamano]

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

Thanks.

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

[Aditya Garg]

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

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

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

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

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

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

[Aditya Garg]

> On 8 May 2025, at 9:53 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>>> "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.


Alright. I'll just add some docs regarding this then

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> I think ~/.gitconfig should be in single quotes, its not a command.
>
> "Is this something the end-user would type verbatim?" is the criteria,
> not "Is this a command name?".

Looking for "^Markup:" in Documentation/CodingGuidelines, we find a
better description.

 Literal parts (e.g. use of command-line options, command names,
 branch names, URLs, pathnames (files and directories), configuration and
 environment variables) must be typeset as verbatim (i.e. wrapped with
 backticks):
   `--pretty=oneline`
   `git rev-list`
   `remote.pushDefault`
   `http://git.example.com`
   `.git/config`
   `GIT_DIR`
   `HEAD`
   `umask`(2)

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

[Aditya Garg]

> On 8 May 2025, at 8:23 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Junio C Hamano <gitster@pobox.com> writes:
> 
>>> I think ~/.gitconfig should be in single quotes, its not a command.
>> 
>> "Is this something the end-user would type verbatim?" is the criteria,
>> not "Is this a command name?".
> 
> Looking for "^Markup:" in Documentation/CodingGuidelines, we find a
> better description.
> 
> Literal parts (e.g. use of command-line options, command names,
> branch names, URLs, pathnames (files and directories), configuration and
> environment variables) must be typeset as verbatim (i.e. wrapped with
> backticks):
>   `--pretty=oneline`
>   `git rev-list`
>   `remote.pushDefault`
>   `http://git.example.com`
>   `.git/config`
>   `GIT_DIR`
>   `HEAD`
>   `umask`(2)
> 

I see. Since you have already queued the v5, can you do this change on your end,
or should I send a v6?

Also, if this is true, the docs need a review since I've found inconsistency across
many places.

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

[Aditya Garg]

> On 8 May 2025, at 8:35 PM, Aditya Garg <gargaditya08@live.com> wrote:
> 
> 
> 
>> On 8 May 2025, at 8:23 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> 
>> Junio C Hamano <gitster@pobox.com> writes:
>> 
>>>> I think ~/.gitconfig should be in single quotes, its not a command.
>>> 
>>> "Is this something the end-user would type verbatim?" is the criteria,
>>> not "Is this a command name?".
>> 
>> Looking for "^Markup:" in Documentation/CodingGuidelines, we find a
>> better description.
>> 
>> Literal parts (e.g. use of command-line options, command names,
>> branch names, URLs, pathnames (files and directories), configuration and
>> environment variables) must be typeset as verbatim (i.e. wrapped with
>> backticks):
>>  `--pretty=oneline`
>>  `git rev-list`
>>  `remote.pushDefault`
>>  `http://git.example.com`
>>  `.git/config`
>>  `GIT_DIR`
>>  `HEAD`
>>  `umask`(2)
>> 
> 
> I see. Since you have already queued the v5, can you do this change on your end,
> or should I send a v6?

Guess what, I'll just send a version 6. Its not a big change.

[PATCH v4 3/3] docs: add credential helper for outlook and gmail in OAuth list of helpers

[Aditya Garg]

This commit adds the `git-credential-outlook` and `git-credential-gmail`
helpers to the list of OAuth helpers.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/gitcredentials.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gitcredentials.adoc b/Documentation/gitcredentials.adoc
index 3337bb475d..b49923db02 100644
--- a/Documentation/gitcredentials.adoc
+++ b/Documentation/gitcredentials.adoc
@@ -133,6 +133,10 @@ Popular helpers with OAuth support include:
 
     - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
 
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] (cross platform, dedicated helper to authenticate Gmail accounts for linkgit:git-send-email[1])
+
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] (cross platform, dedicated helper to authenticate Microsoft Outlook accounts for linkgit:git-send-email[1])
+
 CREDENTIAL CONTEXTS
 -------------------
 
-- 
2.49.0

[PATCH v6 0/3] Improve checks for valid_fqdn in send-email and update documentation

[Aditya Garg]

Hi all

This series of patches mainly has two changes:

1. Improve the checks for valid_fqdn in send-email to be more strict and
   compliant with RFC1035.
2. Update the documentation for send-email to include examples of using
   OAuth2.0 with Gmail and Outlook, as well as links to the credential
   helpers for these services.

P.S. I have used `git-credential-outlook` linked in the second and third
patch for this email!

v2: - Improve grammar and add missing "" in second patch.
    - Separate footnotes and the trailer block with a blank line in the first
      patch.

v3: - Change link for email helpers since old one was too long.

v4: - Improve log message of first and second patch.
    - Update valid_fqdn check in first patch to allow one or more <upto 63
      octet run of alnum or hyphen that does not begin or end with hyphen>,
      separated by a single dot in between each.
    - Revert the documentation regarding sending patches to a mailing list
      in the second patch.

v5: - Simplify the regex in the first patch to check for valid FQDN.
    - Fix formatting in the second patch to make it more readable.

v6: - Use backticks for ~/.gitconfig in the second patch.

Aditya Garg (3):
  send-mail: improve checks for valid_fqdn
  docs: improve send-email documentation
  docs: add credential helper for outlook and gmail in OAuth list of
    helpers

 Documentation/git-send-email.adoc | 63 +++++++++++++++++++++++++++----
 Documentation/gitcredentials.adoc |  4 ++
 git-send-email.perl               |  4 +-
 3 files changed, 62 insertions(+), 9 deletions(-)

-- 
2.49.0

[PATCH v6 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

The current implementation of a valid Fully Qualified Domain Name
is not that strict. It just checks whether it has a dot (.) and
if using macOS, it should not end with .local. As per RFC1035[1],
from what I understood, the following checks need to be done:

- The domain must contain atleast one dot
- Each label (separated by dots) must be 1-63 characters long
- Labels must start and end with an alphanumeric character
- Labels can contain alphanumeric characters and hyphens

Here are some examples of valid and invalid labels:

'example.com',          # Valid
'sub.example.com',      # Valid
'my-domain.org',        # Valid
'localhost',            # Invalid (no dot)
'MacBook..',            # Invalid (double dots)
'-example.com',         # Invalid (starts with a hyphen)
'example-.com',         # Invalid (ends with a hyphen)
'example..com',         # Invalid (double dots)
'example',              # Invalid (no TLD)
'example.local',        # Invalid on macOS
'valid-domain.co.uk',   # Valid
'123.example.com',      # Valid
'example.com.',         # Invalid (trailing dot)
'toolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabel.com', # Invalid (label > 63 chars)

Due to current implementation, I was not able to send emails from
Ubuntu. Upon debugging, I found that the SMTP domain being passed
to Outlook's servers was not valid.

Net::SMTP=GLOB(0x5db4351225f8)>>> EHLO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name
Net::SMTP=GLOB(0x5db4351225f8)>>> HELO MacBook..

Notice that an invalid domain name "MacBook.." is sent by git-send-email.
We have a fallback code that checks output from Net::Domain::domainname()
or asking domain method of an Net::SMTP instance to detect a misconfigured
hostname and replace it with fallback "localhost.localdomain", but the
valid_fqdn apparently is failing to say "MacBook.." is not a valid fqdn.

With this patch, the rule used in valid_fqdn is tightened, the beginning
part of the SMTP exchange looked like this:

Net::SMTP=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello

[1]: https://datatracker.ietf.org/doc/html/rfc1035

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 4215f8f7e9..55b7e00d29 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1359,7 +1359,9 @@ sub process_address_list {
 
 sub valid_fqdn {
 	my $domain = shift;
-	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
+	my $subdomain = '(?!-)[A-Za-z0-9-]{1,63}(?<!-)';
+	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
+		&& $domain  =~ /^$subdomain(?:\.$subdomain)*$/;
 }
 
 sub maildomain_net {
-- 
2.49.0

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

[Aditya Garg]

OAuth2.0 is a new authentication method that is being used by many email
providers, including Outlook and Gmail. Recently, the Authen::SASL perl
module has been updated to support OAuth2.0 authentication, thus making
the git-send-email script be able to use this authentication method as
well. So lets improve the documentation to reflect this change.

I also had a hard time finding a reliable OAuth2.0 access token
generator for Outlook and Gmail. So I added a link to the such
generators which I developed myself after seaching through lots of code
and API documentation to make things easier for others.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 63 +++++++++++++++++++++++++++----
 1 file changed, 55 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 92389036fa..f4503a776d 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -509,12 +509,12 @@ include::includes/cmd-config-section-all.adoc[]
 
 include::config/sendemail.adoc[]
 
-EXAMPLES
---------
-Use gmail as the smtp server
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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:
 
 ----
 [sendemail]
@@ -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
+----
+
+SENDING PATCHES
+---------------
 Once your commits are ready to be sent to the mailing list, run the
 following commands:
 
@@ -536,9 +567,25 @@ 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)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
 
 Note: the following core Perl modules that may be installed with your
 distribution of Perl are required:
-- 
2.49.0

[PATCH v6 3/3] docs: add credential helper for outlook and gmail in OAuth list of helpers

[Aditya Garg]

This commit adds the `git-credential-outlook` and `git-credential-gmail`
helpers to the list of OAuth helpers.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/gitcredentials.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gitcredentials.adoc b/Documentation/gitcredentials.adoc
index 3337bb475d..b49923db02 100644
--- a/Documentation/gitcredentials.adoc
+++ b/Documentation/gitcredentials.adoc
@@ -133,6 +133,10 @@ Popular helpers with OAuth support include:
 
     - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
 
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] (cross platform, dedicated helper to authenticate Gmail accounts for linkgit:git-send-email[1])
+
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] (cross platform, dedicated helper to authenticate Microsoft Outlook accounts for linkgit:git-send-email[1])
+
 CREDENTIAL CONTEXTS
 -------------------
 
-- 
2.49.0

[PATCH v7 0/3] Improve checks for valid_fqdn in send-email and update documentation

[Aditya Garg]

Hi all

This series of patches mainly has two changes:

1. Improve the checks for valid_fqdn in send-email to be more strict and
   compliant with RFC1035.
2. Update the documentation for send-email to include examples of using
   OAuth2.0 with Gmail and Outlook, as well as links to the credential
   helpers for these services.

P.S. I have used `git-credential-outlook` linked in the second and third
patch for this email!

v2: - Improve grammar and add missing "" in second patch.
    - Separate footnotes and the trailer block with a blank line in the first
      patch.

v3: - Change link for email helpers since old one was too long.

v4: - Improve log message of first and second patch.
    - Update valid_fqdn check in first patch to allow one or more <upto 63
      octet run of alnum or hyphen that does not begin or end with hyphen>,
      separated by a single dot in between each.
    - Revert the documentation regarding sending patches to a mailing list
      in the second patch.

v5: - Simplify the regex in the first patch to check for valid FQDN.
    - Fix formatting in the second patch to make it more readable.

v6: - Use backticks for ~/.gitconfig in the second patch.

v7: - Clarify the use of `OAUTHBEARER` and `XOAUTH2` in the second patch.

Aditya Garg (3):
  send-mail: improve checks for valid_fqdn
  docs: improve send-email documentation
  docs: add credential helper for outlook and gmail in OAuth list of
    helpers

 Documentation/git-send-email.adoc | 67 +++++++++++++++++++++++++++----
 Documentation/gitcredentials.adoc |  4 ++
 git-send-email.perl               |  4 +-
 3 files changed, 66 insertions(+), 9 deletions(-)

-- 
2.49.0

[PATCH v7 1/3] send-mail: improve checks for valid_fqdn

[Aditya Garg]

The current implementation of a valid Fully Qualified Domain Name
is not that strict. It just checks whether it has a dot (.) and
if using macOS, it should not end with .local. As per RFC1035[1],
from what I understood, the following checks need to be done:

- The domain must contain atleast one dot
- Each label (separated by dots) must be 1-63 characters long
- Labels must start and end with an alphanumeric character
- Labels can contain alphanumeric characters and hyphens

Here are some examples of valid and invalid labels:

'example.com',          # Valid
'sub.example.com',      # Valid
'my-domain.org',        # Valid
'localhost',            # Invalid (no dot)
'MacBook..',            # Invalid (double dots)
'-example.com',         # Invalid (starts with a hyphen)
'example-.com',         # Invalid (ends with a hyphen)
'example..com',         # Invalid (double dots)
'example',              # Invalid (no TLD)
'example.local',        # Invalid on macOS
'valid-domain.co.uk',   # Valid
'123.example.com',      # Valid
'example.com.',         # Invalid (trailing dot)
'toolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabel.com', # Invalid (label > 63 chars)

Due to current implementation, I was not able to send emails from
Ubuntu. Upon debugging, I found that the SMTP domain being passed
to Outlook's servers was not valid.

Net::SMTP=GLOB(0x5db4351225f8)>>> EHLO MacBook..
Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name
Net::SMTP=GLOB(0x5db4351225f8)>>> HELO MacBook..

Notice that an invalid domain name "MacBook.." is sent by git-send-email.
We have a fallback code that checks output from Net::Domain::domainname()
or asking domain method of an Net::SMTP instance to detect a misconfigured
hostname and replace it with fallback "localhost.localdomain", but the
valid_fqdn apparently is failing to say "MacBook.." is not a valid fqdn.

With this patch, the rule used in valid_fqdn is tightened, the beginning
part of the SMTP exchange looked like this:

Net::SMTP=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain
Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello

[1]: https://datatracker.ietf.org/doc/html/rfc1035

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 4215f8f7e9..55b7e00d29 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1359,7 +1359,9 @@ sub process_address_list {
 
 sub valid_fqdn {
 	my $domain = shift;
-	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/) && $domain =~ /\./;
+	my $subdomain = '(?!-)[A-Za-z0-9-]{1,63}(?<!-)';
+	return defined $domain && !($^O eq 'darwin' && $domain =~ /\.local$/)
+		&& $domain  =~ /^$subdomain(?:\.$subdomain)*$/;
 }
 
 sub maildomain_net {
-- 
2.49.0

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

[Aditya Garg]

OAuth2.0 is a new authentication method that is being used by many email
providers, including Outlook and Gmail. Recently, the Authen::SASL perl
module has been updated to support OAuth2.0 authentication, thus making
the git-send-email script be able to use this authentication method as
well. So lets improve the documentation to reflect this change.

I also had a hard time finding a reliable OAuth2.0 access token
generator for Outlook and Gmail. So I added a link to the such
generators which I developed myself after seaching through lots of code
and API documentation to make things easier for others.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 67 +++++++++++++++++++++++++++----
 1 file changed, 59 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 92389036fa..26fda63c2f 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -509,12 +509,12 @@ include::includes/cmd-config-section-all.adoc[]
 
 include::config/sendemail.adoc[]
 
-EXAMPLES
---------
-Use gmail as the smtp server
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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:
 
 ----
 [sendemail]
@@ -528,6 +528,41 @@ 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:
+
+----
+[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. Also, it only
+supports `XOAUTH2` authentication method.
+
+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
+----
+
+SENDING PATCHES
+---------------
 Once your commits are ready to be sent to the mailing list, run the
 following commands:
 
@@ -536,9 +571,25 @@ 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)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
 
 Note: the following core Perl modules that may be installed with your
 distribution of Perl are required:
-- 
2.49.0

[PATCH v7 3/3] docs: add credential helper for outlook and gmail in OAuth list of helpers

[Aditya Garg]

This commit adds the `git-credential-outlook` and `git-credential-gmail`
helpers to the list of OAuth helpers.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/gitcredentials.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gitcredentials.adoc b/Documentation/gitcredentials.adoc
index 3337bb475d..b49923db02 100644
--- a/Documentation/gitcredentials.adoc
+++ b/Documentation/gitcredentials.adoc
@@ -133,6 +133,10 @@ Popular helpers with OAuth support include:
 
     - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
 
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] (cross platform, dedicated helper to authenticate Gmail accounts for linkgit:git-send-email[1])
+
+    - https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] (cross platform, dedicated helper to authenticate Microsoft Outlook accounts for linkgit:git-send-email[1])
+
 CREDENTIAL CONTEXTS
 -------------------
 
-- 
2.49.0

Re: [PATCH v7 0/3] Improve checks for valid_fqdn in send-email and update documentation

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> Hi all
>
> This series of patches mainly has two changes:
>
> 1. Improve the checks for valid_fqdn in send-email to be more strict and
>    compliant with RFC1035.
> 2. Update the documentation for send-email to include examples of using
>    OAuth2.0 with Gmail and Outlook, as well as links to the credential
>    helpers for these services.
>
> P.S. I have used `git-credential-outlook` linked in the second and third
> patch for this email!
>
> v2: - Improve grammar and add missing "" in second patch.
>     - Separate footnotes and the trailer block with a blank line in the first
>       patch.
>
> v3: - Change link for email helpers since old one was too long.
>
> v4: - Improve log message of first and second patch.
>     - Update valid_fqdn check in first patch to allow one or more <upto 63
>       octet run of alnum or hyphen that does not begin or end with hyphen>,
>       separated by a single dot in between each.
>     - Revert the documentation regarding sending patches to a mailing list
>       in the second patch.
>
> v5: - Simplify the regex in the first patch to check for valid FQDN.
>     - Fix formatting in the second patch to make it more readable.
>
> v6: - Use backticks for ~/.gitconfig in the second patch.
>
> v7: - Clarify the use of `OAUTHBEARER` and `XOAUTH2` in the second patch.

Much better than what I came up with ;-)  Nicely phrased.

Will queue.  Unless there are issues pointed out by others in a few
days, let me mark the topic for 'next'.

Thanks.

[PATCH] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Aditya Garg]

`hostname` is a popular command available on both Linux and macOS. As
per the man-page[1], `hostname --fqdn` command returns the fully
qualified domain name (FQDN) of the system. The current Net::Domain
perl module being used in the script for the same has been quite
unrealiable in many cases. Thankfully, we now have a better check for
valid_fqdn, which does reject the invalid FQDNs given by this module
properly, but at the same time, it will result in a fallback to
'localhost.localdomain' being used. `hostname --fqdn` has been quite
reliable (probably even more reliable than the Net::Domain module) and
before falling back to 'localhost.localdomain', we should try to use it.
Interestingly, the `hostname` command is actually used by perl modules
like Net::Domain[2] and Sys::Hostname[3] to get the hostname. So, lets
give `hostname --fqdn` a chance as well!

[1]: https://man7.org/linux/man-pages/man1/hostname.1.html
[2]: https://github.com/Perl/perl5/blob/blead/cpan/libnet/lib/Net/Domain.pm#L88
[3]: https://github.com/Perl/perl5/blob/blead/ext/Sys-Hostname/Hostname.pm#L93

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 55b7e00d29..735d8abc12 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1393,8 +1393,20 @@ sub maildomain_mta {
 	return $maildomain;
 }
 
+sub maildomain_hostname_command {
+	my $maildomain;
+
+	if ($^O eq 'linux' || $^O eq 'darwin') {
+		my $domain = `(hostname --fqdn) 2>/dev/null`;
+		chomp($domain);
+		$maildomain = $domain if valid_fqdn($domain);
+	}
+	return $maildomain;
+}
+
 sub maildomain {
-	return maildomain_net() || maildomain_mta() || 'localhost.localdomain';
+	return maildomain_net() || maildomain_mta() ||
+		maildomain_hostname_command || 'localhost.localdomain';
 }
 
 sub smtp_host_string {
-- 
2.49.0

Re: [PATCH] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> `hostname` is a popular command available on both Linux and macOS. As
> per the man-page[1], `hostname --fqdn` command returns the fully
> qualified domain name (FQDN) of the system. The current Net::Domain
> perl module being used in the script for the same has been quite
> unrealiable in many cases. Thankfully, we now have a better check for
> valid_fqdn, which does reject the invalid FQDNs given by this module
> properly, but at the same time, it will result in a fallback to
> 'localhost.localdomain' being used. `hostname --fqdn` has been quite
> reliable (probably even more reliable than the Net::Domain module) and
> before falling back to 'localhost.localdomain', we should try to use it.
> Interestingly, the `hostname` command is actually used by perl modules
> like Net::Domain[2] and Sys::Hostname[3] to get the hostname. So, lets
> give `hostname --fqdn` a chance as well!
>
> [1]: https://man7.org/linux/man-pages/man1/hostname.1.html
> [2]: https://github.com/Perl/perl5/blob/blead/cpan/libnet/lib/Net/Domain.pm#L88
> [3]: https://github.com/Perl/perl5/blob/blead/ext/Sys-Hostname/Hostname.pm#L93
>
> Signed-off-by: Aditya Garg <gargaditya08@live.com>
> ---
>  git-send-email.perl | 14 +++++++++++++-
>  1 file changed, 13 insertions(+), 1 deletion(-)

As maildomain() is called at most once in a process, thanks to
send_message() conditionally calling it only to set $smtp_domain
that is not yet set, I do not personally mind adding an extra
fork/exec here, but ...

> diff --git a/git-send-email.perl b/git-send-email.perl
> index 55b7e00d29..735d8abc12 100755
> --- a/git-send-email.perl
> +++ b/git-send-email.perl
> @@ -1393,8 +1393,20 @@ sub maildomain_mta {
>  	return $maildomain;
>  }
>  
> +sub maildomain_hostname_command {
> +	my $maildomain;
> +
> +	if ($^O eq 'linux' || $^O eq 'darwin') {
> +		my $domain = `(hostname --fqdn) 2>/dev/null`;
> +		chomp($domain);
> +		$maildomain = $domain if valid_fqdn($domain);

... we do not know everybody's implementation, especially including
the non stardard ones, of 'hostname --fqdn'.  Some may stay silent,
or say something only to its standard error, when it cannot produce
a usable output, which is the above code expects, but some others
emit whatever it wants to to its standard output while signalling an
error with its exit value, when it sees some error (like "I do not
know about that 'fqdn' option").

In short, I do not have too much trouble against the idea to add
"ask hostname(1)" to the source of maildomain information, but I'd
prefer for the implementation to be a bit more careful to detect
errors, more careful than "if we get anything on its standard
output, it cannot be an error and we'd use that".  I understand that
the call to "if valid_fqdn()" tightens the condition a bit better by
looking at $domain, but we shouldn't be even chomping $domain or
feeding it to valid_fqdn() when we know the `hostname` failed in the
first place.

> +	}
> +	return $maildomain;
> +}

Thanks.

[PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Aditya Garg]

`hostname` is a popular command available on both Linux and macOS. As
per the man-page[1], `hostname --fqdn` command returns the fully
qualified domain name (FQDN) of the system. The current Net::Domain
perl module being used in the script for the same has been quite
unrealiable in many cases. Thankfully, we now have a better check for
valid_fqdn, which does reject the invalid FQDNs given by this module
properly, but at the same time, it will result in a fallback to
'localhost.localdomain' being used. `hostname --fqdn` has been quite
reliable (probably even more reliable than the Net::Domain module) and
before falling back to 'localhost.localdomain', we should try to use it.
Interestingly, the `hostname` command is actually used by perl modules
like Net::Domain[2] and Sys::Hostname[3] to get the hostname. So, lets
give `hostname --fqdn` a chance as well!

[1]: https://man7.org/linux/man-pages/man1/hostname.1.html
[2]: https://github.com/Perl/perl5/blob/blead/cpan/libnet/lib/Net/Domain.pm#L88
[3]: https://github.com/Perl/perl5/blob/blead/ext/Sys-Hostname/Hostname.pm#L93

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
v2: Avoid chomping $domain and assigning it to $maildomain if the command fails.

 git-send-email.perl | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 55b7e00d29..511f627ba6 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1393,8 +1393,22 @@ sub maildomain_mta {
 	return $maildomain;
 }
 
+sub maildomain_hostname_command {
+	my $maildomain;
+
+	if ($^O eq 'linux' || $^O eq 'darwin') {
+		my $domain = `(hostname --fqdn) 2>/dev/null`;
+		if (!$?) {
+			chomp($domain);
+			$maildomain = $domain if valid_fqdn($domain);
+		}
+	}
+	return $maildomain;
+}
+
 sub maildomain {
-	return maildomain_net() || maildomain_mta() || 'localhost.localdomain';
+	return maildomain_net() || maildomain_mta() ||
+		maildomain_hostname_command || 'localhost.localdomain';
 }
 
 sub smtp_host_string {
-- 
2.49.0

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Julian Swagemakers]

On Sat May 10, 2025 at 9:37 AM CEST, Aditya Garg wrote:
> `hostname` is a popular command available on both Linux and macOS. As
> per the man-page[1], `hostname --fqdn` command returns the fully
> qualified domain name (FQDN) of the system.

There are multiple implementations of the hostname command, and they
don't all support `--fqdn`. For example this will not work on Alpine
Linux as well as macOS.

macOS:

    $ hostname --fqdn
    hostname: illegal option -- -
    usage: hostname [-f] [-s | -d] [name-of-host]

Alpine:

    $ hostname --fqdn
    hostname: unrecognized option: fqdn
    BusyBox v1.37.0 (2025-01-17 18:12:01 UTC) multi-call binary.

    Usage: hostname [-sidf] [HOSTNAME | -F FILE]

    Show or set hostname or DNS domain name

        -s	Short
        -i	Addresses for the hostname
        -d	DNS domain name
        -f	Fully qualified domain name
        -F FILE	Use FILE's content as hostname

All seem to support `-f` though, maybe that would be the better option.

Regards Julian

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Aditya Garg]

> On 12 May 2025, at 1:16 PM, Julian Swagemakers <julian@swagemakers.org> wrote:
> 
> On Sat May 10, 2025 at 9:37 AM CEST, Aditya Garg wrote:
>> `hostname` is a popular command available on both Linux and macOS. As
>> per the man-page[1], `hostname --fqdn` command returns the fully
>> qualified domain name (FQDN) of the system.
> 
> There are multiple implementations of the hostname command, and they
> don't all support `--fqdn`. For example this will not work on Alpine
> Linux as well as macOS.
> 
> macOS:
> 
>    $ hostname --fqdn
>    hostname: illegal option -- -
>    usage: hostname [-f] [-s | -d] [name-of-host]
> 
> Alpine:
> 
>    $ hostname --fqdn
>    hostname: unrecognized option: fqdn
>    BusyBox v1.37.0 (2025-01-17 18:12:01 UTC) multi-call binary.
> 
>    Usage: hostname [-sidf] [HOSTNAME | -F FILE]
> 
>    Show or set hostname or DNS domain name
> 
>        -s    Short
>        -i    Addresses for the hostname
>        -d    DNS domain name
>        -f    Fully qualified domain name
>        -F FILE    Use FILE's content as hostname
> 
> All seem to support `-f` though, maybe that would be the better option.

Sure. I was using -f before, but thought --fqdn would be more intuitive for
anyone reading the code. Didn't know its not supported every where.

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Junio C Hamano]

"Julian Swagemakers" <julian@swagemakers.org> writes:

> There are multiple implementations of the hostname command, and they
> don't all support `--fqdn`. For example this will not work on Alpine
> Linux as well as macOS.
> ...
> All seem to support `-f` though, maybe that would be the better option.

What makes me worried about such a proposed changes is if there are
implementations that takes `-f` but uses it to mean something
completely different from fqdn, and emits something that looks like
a hostname but is not.  At least an implementation that takes --fqdn
without erroring out would try to give what this code wants to find
out (or it is simply crazy), but -f does not feel specific enough.

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Aditya Garg]

> On 12 May 2025, at 10:12 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> "Julian Swagemakers" <julian@swagemakers.org> writes:
> 
>> There are multiple implementations of the hostname command, and they
>> don't all support `--fqdn`. For example this will not work on Alpine
>> Linux as well as macOS.
>> ...
>> All seem to support `-f` though, maybe that would be the better option.
> 
> What makes me worried about such a proposed changes is if there are
> implementations that takes `-f` but uses it to mean something
> completely different from fqdn, and emits something that looks like
> a hostname but is not.  At least an implementation that takes --fqdn
> without erroring out would try to give what this code wants to find
> out (or it is simply crazy), but -f does not feel specific enough.

What we can do is use `hostname -f` for macOS, after all its the only darwin based
OS used rn, and use hostname --fqdn for Linux.

Although it still leaves out Alpine Linux.

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

>> On 12 May 2025, at 10:12 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> 
>> "Julian Swagemakers" <julian@swagemakers.org> writes:
>> 
>>> There are multiple implementations of the hostname command, and they
>>> don't all support `--fqdn`. For example this will not work on Alpine
>>> Linux as well as macOS.
>>> ...
>>> All seem to support `-f` though, maybe that would be the better option.
>> 
>> What makes me worried about such a proposed changes is if there are
>> implementations that takes `-f` but uses it to mean something
>> completely different from fqdn, and emits something that looks like
>> a hostname but is not.  At least an implementation that takes --fqdn
>> without erroring out would try to give what this code wants to find
>> out (or it is simply crazy), but -f does not feel specific enough.
>
> What we can do is use `hostname -f` for macOS, after all its the only darwin based
> OS used rn, and use hostname --fqdn for Linux.
>
> Although it still leaves out Alpine Linux.

As long as we record the reasoning behind our decision to use `-f`,
with an explanation like "we can add a configuration to disable this
if an odd platform implementation of `hostname -f` truly misbehaves"
to suggest that we can, if needed, easily give an escape hatch if
this change breaks existing users, I think it is OK to just use
`-f`, which would be the simplest ;-)

Thanks.

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Aditya Garg]

> On 12 May 2025, at 11:05 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>>>> On 12 May 2025, at 10:12 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> 
>>> "Julian Swagemakers" <julian@swagemakers.org> writes:
>>> 
>>>> There are multiple implementations of the hostname command, and they
>>>> don't all support `--fqdn`. For example this will not work on Alpine
>>>> Linux as well as macOS.
>>>> ...
>>>> All seem to support `-f` though, maybe that would be the better option.
>>> 
>>> What makes me worried about such a proposed changes is if there are
>>> implementations that takes `-f` but uses it to mean something
>>> completely different from fqdn, and emits something that looks like
>>> a hostname but is not.  At least an implementation that takes --fqdn
>>> without erroring out would try to give what this code wants to find
>>> out (or it is simply crazy), but -f does not feel specific enough.
>> 
>> What we can do is use `hostname -f` for macOS, after all its the only darwin based
>> OS used rn, and use hostname --fqdn for Linux.
>> 
>> Although it still leaves out Alpine Linux.
> 
> As long as we record the reasoning behind our decision to use `-f`,
> with an explanation like "we can add a configuration to disable this
> if an odd platform implementation of `hostname -f` truly misbehaves"
> to suggest that we can, if needed, easily give an escape hatch if
> this change breaks existing users, I think it is OK to just use
> `-f`, which would be the simplest ;-)

I thinks its best to use --fqdn if its supported on most Linux distros and
-f on macOS. It's not really possible for me to check the result of -f on
all Linux distros. Although, we still have valid_fqdn checks in place which
should cover up most errors, and as far as I have noticed, distros supporting

--fqdn support -f as an alternative.

Tbh, your call. The v3 of this patch has hostname -f and v4 has hostname --fqdn
for Linux and -f for macOS.

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Eric Sunshine]

On Mon, May 12, 2025 at 1:34 PM Junio C Hamano <gitster@pobox.com> wrote:
> Aditya Garg <gargaditya08@live.com> writes:
> >> On 12 May 2025, at 10:12 PM, Junio C Hamano <gitster@pobox.com> wrote:
> >> "Julian Swagemakers" <julian@swagemakers.org> writes:
> >>> There are multiple implementations of the hostname command, and they
> >>> don't all support `--fqdn`. For example this will not work on Alpine
> >>> Linux as well as macOS.
> >>> ...
> >>> All seem to support `-f` though, maybe that would be the better option.
> >>
> >> What makes me worried about such a proposed changes is if there are
> >> implementations that takes `-f` but uses it to mean something
> >> completely different from fqdn, and emits something that looks like
> >> a hostname but is not.  At least an implementation that takes --fqdn
> >> without erroring out would try to give what this code wants to find
> >> out (or it is simply crazy), but -f does not feel specific enough.
> >
> > What we can do is use `hostname -f` for macOS, after all its the only darwin based
> > OS used rn, and use hostname --fqdn for Linux.
> >
> > Although it still leaves out Alpine Linux.
>
> As long as we record the reasoning behind our decision to use `-f`,
> with an explanation like "we can add a configuration to disable this
> if an odd platform implementation of `hostname -f` truly misbehaves"
> to suggest that we can, if needed, easily give an escape hatch if
> this change breaks existing users, I think it is OK to just use
> `-f`, which would be the simplest ;-)

The problem is not restricted only to macOS (and Alpine), but more
generally to all BSD-lineage `hostname` which does not understand
--fqdn but does understand -f.

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> The problem is not restricted only to macOS (and Alpine), but more
> generally to all BSD-lineage `hostname` which does not understand
> --fqdn but does understand -f.

True, but the proposed patch limits itself to 

      $^O eq 'linux' || $^O eq 'darwin'

for unfathomable reason, so BSD's are safe already ;-)

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Aditya Garg]

> On 13 May 2025, at 1:45 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Eric Sunshine <sunshine@sunshineco.com> writes:
> 
>> The problem is not restricted only to macOS (and Alpine), but more
>> generally to all BSD-lineage `hostname` which does not understand
>> --fqdn but does understand -f.
> 
> True, but the proposed patch limits itself to
> 
>      $^O eq 'linux' || $^O eq 'darwin'
> 
> for unfathomable reason, so BSD's are safe already ;-)

Exactly. I had tested hostname -f on both macOS and Linux, but was lazy
enough to not check --fqdn, thus resulting in a wrong patch. v3 and v4 should
work properly. I'll also avoid laziness in the future.

Re: [PATCH v2] send-email: try to get fqdn by running hostname --fqdn on Linux and macOS

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> writes:

> `hostname` is a popular command available on both Linux and macOS. As
> per the man-page[1], `hostname --fqdn` command returns the fully
> qualified domain name (FQDN) of the system. The current Net::Domain
> perl module being used in the script for the same has been quite
> unrealiable in many cases. Thankfully, we now have a better check for
> valid_fqdn, which does reject the invalid FQDNs given by this module
> properly, but at the same time, it will result in a fallback to
> 'localhost.localdomain' being used. `hostname --fqdn` has been quite
> reliable (probably even more reliable than the Net::Domain module) and
> before falling back to 'localhost.localdomain', we should try to use it.
> Interestingly, the `hostname` command is actually used by perl modules
> like Net::Domain[2] and Sys::Hostname[3] to get the hostname. So, lets
> give `hostname --fqdn` a chance as well!
>
> [1]: https://man7.org/linux/man-pages/man1/hostname.1.html
> [2]: https://github.com/Perl/perl5/blob/blead/cpan/libnet/lib/Net/Domain.pm#L88
> [3]: https://github.com/Perl/perl5/blob/blead/ext/Sys-Hostname/Hostname.pm#L93
>
> Signed-off-by: Aditya Garg <gargaditya08@live.com>
> ---
> v2: Avoid chomping $domain and assigning it to $maildomain if the command fails.
>
>  git-send-email.perl | 16 +++++++++++++++-
>  1 file changed, 15 insertions(+), 1 deletion(-)

Looks sensible. Will queue. Thanks.

> diff --git a/git-send-email.perl b/git-send-email.perl
> index 55b7e00d29..511f627ba6 100755
> --- a/git-send-email.perl
> +++ b/git-send-email.perl
> @@ -1393,8 +1393,22 @@ sub maildomain_mta {
>  	return $maildomain;
>  }
>  
> +sub maildomain_hostname_command {
> +	my $maildomain;
> +
> +	if ($^O eq 'linux' || $^O eq 'darwin') {
> +		my $domain = `(hostname --fqdn) 2>/dev/null`;
> +		if (!$?) {
> +			chomp($domain);
> +			$maildomain = $domain if valid_fqdn($domain);
> +		}
> +	}
> +	return $maildomain;
> +}
> +
>  sub maildomain {
> -	return maildomain_net() || maildomain_mta() || 'localhost.localdomain';
> +	return maildomain_net() || maildomain_mta() ||
> +		maildomain_hostname_command || 'localhost.localdomain';
>  }
>  
>  sub smtp_host_string {

[PATCH v3] send-email: try to get fqdn by running hostname -f on Linux and macOS

[Aditya Garg]

`hostname` is a popular command available on both Linux and macOS. As
per the man-page[1], `hostname -f` command returns the fully qualified
domain name (FQDN) of the system. The current Net::Domain perl module
being used in the script for the same has been quite unrealiable in many
cases. Thankfully, we now have a better check for valid_fqdn, which does
reject the invalid FQDNs given by this module properly, but at the same
time, it will result in a fallback to 'localhost.localdomain' being
used. `hostname -f` has been quite reliable (probably even more reliable
than the Net::Domain module) and before falling back to
'localhost.localdomain', we should try to use it. Interestingly, the
`hostname` command is actually used by perl modules like Net::Domain[2]
and Sys::Hostname[3] to get the hostname. So, lets give `hostname -f` a
chance as well!

[1]: https://man7.org/linux/man-pages/man1/hostname.1.html
[2]: https://github.com/Perl/perl5/blob/blead/cpan/libnet/lib/Net/Domain.pm#L88
[3]: https://github.com/Perl/perl5/blob/blead/ext/Sys-Hostname/Hostname.pm#L93

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
v2: Avoid chomping $domain and assigning it to $maildomain if the command fails.
v3: Use `hostname -f` instead of `hostname --fqdn` since -f is supported everywhere.

 git-send-email.perl | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 55b7e00d29..659e6c588b 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1393,8 +1393,22 @@ sub maildomain_mta {
 	return $maildomain;
 }
 
+sub maildomain_hostname_command {
+	my $maildomain;
+
+	if ($^O eq 'linux' || $^O eq 'darwin') {
+		my $domain = `(hostname -f) 2>/dev/null`;
+		if (!$?) {
+			chomp($domain);
+			$maildomain = $domain if valid_fqdn($domain);
+		}
+	}
+	return $maildomain;
+}
+
 sub maildomain {
-	return maildomain_net() || maildomain_mta() || 'localhost.localdomain';
+	return maildomain_net() || maildomain_mta() ||
+		maildomain_hostname_command || 'localhost.localdomain';
 }
 
 sub smtp_host_string {
-- 
2.49.0

[PATCH v4] send-email: try to get fqdn by running hostname -f on Linux and macOS

[Aditya Garg]

`hostname` is a popular command available on both Linux and macOS. As
per the man-page[1], `hostname -f` command returns the fully qualified
domain name (FQDN) of the system. The current Net::Domain perl module
being used in the script for the same has been quite unrealiable in many
cases. Thankfully, we now have a better check for valid_fqdn, which does
reject the invalid FQDNs given by this module properly, but at the same
time, it will result in a fallback to 'localhost.localdomain' being
used. `hostname -f` has been quite reliable (probably even more reliable
than the Net::Domain module) and before falling back to
'localhost.localdomain', we should try to use it.

In this patch we shall be using `hostname --fqdn` command on Linux
instead of `hostname -f`. This is because `hostname -f` could output
something else in case a Linux distro uses some other implementation of
`hostname`. On the other hand, `hostname --fqdn` is not valid on macOS,
so we shall be using `hostname -f` there.

Interestingly, the `hostname` command is actually used by perl modules
like Net::Domain[2] and Sys::Hostname[3] to get the hostname. So, lets
give `hostname -f` a chance as well!

[1]: https://man7.org/linux/man-pages/man1/hostname.1.html
[2]: https://github.com/Perl/perl5/blob/blead/cpan/libnet/lib/Net/Domain.pm#L88
[3]: https://github.com/Perl/perl5/blob/blead/ext/Sys-Hostname/Hostname.pm#L93

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
v2: Avoid chomping $domain and assigning it to $maildomain if the command fails.
v3: Use `hostname -f` instead of `hostname --fqdn` since -f is supported everywhere.
v4: Use `hostname --fqdn` on Linux and `hostname -f` on macOS.

 git-send-email.perl | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/git-send-email.perl b/git-send-email.perl
index 55b7e00d29..bdbc7f8149 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1393,8 +1393,24 @@ sub maildomain_mta {
 	return $maildomain;
 }
 
+sub maildomain_hostname_command {
+	my $maildomain;
+
+	if ($^O eq 'linux' || $^O eq 'darwin') {
+		my $domain = ($^O eq 'darwin') ?
+			`(hostname -f) 2>/dev/null` :
+			`(hostname --fqdn) 2>/dev/null`;
+		if (!$?) {
+			chomp($domain);
+			$maildomain = $domain if valid_fqdn($domain);
+		}
+	}
+	return $maildomain;
+}
+
 sub maildomain {
-	return maildomain_net() || maildomain_mta() || 'localhost.localdomain';
+	return maildomain_net() || maildomain_mta() ||
+		maildomain_hostname_command || 'localhost.localdomain';
 }
 
 sub smtp_host_string {
-- 
2.49.0