patch, 3 partsImprove checks for valid_fqdn in send-email and update documentation

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(-)

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(-)

On Sun, May 4, 2025, at 15:54, Aditya Garg wrote:

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.

On Sun, May 4, 2025, at 17:26, Aditya Garg wrote:

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

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(-)

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(+)

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(-)

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(-)

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(-)

Aditya Garg <gargaditya08@live.com> writes:

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.

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.

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

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(+)

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(-)

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(+)

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(-)

Aditya Garg <gargaditya08@live.com> writes:

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.

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

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.

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?

On 06/05/25 3:05 pm, Aditya Garg wrote:

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.

Aditya Garg <gargaditya08@live.com> writes:

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

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

That does sound problematic.

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.

Aditya Garg <gargaditya08@live.com> writes:

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?

On 06/05/25 10:41 pm, Junio C Hamano wrote:

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.

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.

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.

Aditya Garg <gargaditya08@live.com> writes:

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.

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(-)

Aditya Garg <gargaditya08@live.com> writes:

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.

This version was sent before your review ;)

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(-)

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(-)

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.

Aditya Garg <gargaditya08@live.com> writes:

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.

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.

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(-)

Nice to see that you got the capitalization got right while at it.

The four single quotes above should probably be changed to back quotes, to match the "You can also use OAuth2.0..." below.

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.

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.

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

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

Aditya Garg <gargaditya08@live.com> writes:

"Is this something the end-user would type verbatim?" is the criteria, not "Is this a command name?".

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.

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.

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.

Aditya Garg <gargaditya08@live.com> writes:

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.

OK.

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?

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

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

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

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.

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

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(+)

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(-)

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(-)

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(-)

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(+)

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(-)

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(-)

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(-)

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(+)

Aditya Garg <gargaditya08@live.com> writes:

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.

`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(-)

Aditya Garg <gargaditya08@live.com> writes:

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

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

Thanks.

`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(-)

On Sat May 10, 2025 at 9:37 AM CEST, Aditya Garg wrote:

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

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.

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

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.

Aditya Garg <gargaditya08@live.com> writes:

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.

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.

On Mon, May 12, 2025 at 1:34 PM Junio C Hamano <gitster@pobox.com> wrote:

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.

Eric Sunshine <sunshine@sunshineco.com> writes:

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.

Aditya Garg <gargaditya08@live.com> writes:

Looks sensible. Will queue. Thanks.

`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(-)

`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(-)