threads / patch / 63714

patch, 5 partsdocs: more improvements to sendemail documentation

Subject: [PATCH 0/5] docs: more improvements to sendemail documentation

## tl;dr

6 messages between Jun 30, 2025 and Jun 30, 2025. Diffs are folded; open one to read it.

replies: 5people: 1as markdown or json

Aditya Garg· Jun 30, 2025, 18:05 UTC · lore
From: Aditya Garg <gargaditya08@live.com>
Hi all
This patch series adds more improvements to the sendemail documentation.

The first patch links the OpenSSL's `verify(1)` manual page to the documentation of `-CAfile` and `-CApath` options, mentioned in a very confusing way in the documentation. The changes are similar to what Junio suggested in https://lore.kernel.org/all/xmqqbjraf29c.fsf@gitster.g/

The second patch adds the `sendemail.outlookidfix` config option to the documentation, which corresponds to the `--outlook-id-fix` command line option. The documentation of the same was left by mistake before.

The third patch adds an OAuth2.0 credential helper link for AOL accounts to the documentation.

The fourth patch adds a paragraph explaining the `sendmailCmd` option of git send-email, and giving users an idea of how it can be used to support proprietary APIs like Proton Mail API.

The last patch adds a paragraph explaining the options available for Proton Mail, which has been increasing in popularity recently.

P.S. all the patches are being sent using `git-protonmail`, linked in the fourth and fifth patch!

Aditya Garg (5):
  docs: link OpenSSL's verify(1) manual page to know about -CAfile and
    -CApath options
  docs: add outlookidfix config option to sendemail documentation
  docs: add an OAuth2.0 credential helper for AOL accounts
  docs: add a paragraph explaining the `sendmailCmd` option of sendemail
  docs: mention possible options for Proton Mail users
 Documentation/config/sendemail.adoc |  9 +++--
 Documentation/git-send-email.adoc   | 54 +++++++++++++++++++++++++----
 2 files changed, 55 insertions(+), 8 deletions(-)
-- 
2.50.0.windows.1
Aditya Garg· Jun 30, 2025, 18:06 UTC · re: Aditya Garg · lore

[PATCH 1/5] docs: link OpenSSL's verify(1) manual page to know about -CAfile and -CApath options

From: Aditya Garg <gargaditya08@live.com>

The description of `--smtp-ssl-cert-path` in the git-send-email documentation mentions consulting OpenSSL's verify(1) manual page for details about the `-CAfile` and `-CApath` options. However, the way it was written was quite confusing, and it didn't mention that OpenSSL's verify(1) is the manual page to refer to.

Fix this by slightly rewording the description and also add a link to the OpenSSL verify(1) manual page.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
Show changes to Documentation/git-send-email.adoc +8 −6
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 7bd09c254b..4208bac44c 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -280,12 +280,14 @@ must be used for each option.
 	Path to a store of trusted CA certificates for SMTP SSL/TLS
 	certificate validation (either a directory that has been processed
 	by `c_rehash`, or a single file containing one or more PEM format
-	certificates concatenated together: see verify(1) -CAfile and
-	-CApath for more information on these). Set it to an empty string
-	to disable certificate verification. Defaults to the value of the
-	`sendemail.smtpSSLCertPath` configuration variable, if set, or the
-	backing SSL library's compiled-in default otherwise (which should
-	be the best choice on most platforms).
+	certificates concatenated together: see the description of the
+	`-CAfile` _<file>_ and the `-CApath` _<dir>_ options of
+	https://docs.openssl.org/master/man1/openssl-verify/
+	[OpenSSL's verify(1) manual page] for more information on these).
+	Set it to an empty string to disable certificate verification.
+	Defaults to the value of the `sendemail.smtpSSLCertPath` configuration
+	variable, if set, or the backing SSL library's compiled-in default
+	otherwise (which should be the best choice on most platforms).
 
 --smtp-user=<user>::
 	Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`;

-- 
2.50.0.windows.1
Aditya Garg· Jun 30, 2025, 18:06 UTC · re: Aditya Garg · lore

[PATCH 2/5] docs: add outlookidfix config option to sendemail documentation

From: Aditya Garg <gargaditya08@live.com>

The documentation for command line option `--outlook-id-fix` is there in the sendemail documentation, but the config option `sendemail.outlookidfix` was missing. Add the same to the documentation.

White at it, also enclose the values `true` and `false` in backticks in the documentation for `sendemail.mailmap`.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/config/sendemail.adoc | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
Show changes to Documentation/config/sendemail.adoc +7 −2
diff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc
index 54f1248e64..4722334657 100644
--- a/Documentation/config/sendemail.adoc
+++ b/Documentation/config/sendemail.adoc
@@ -31,8 +31,8 @@ sendemail.confirm::
 	values.
 
 sendemail.mailmap::
-	If true, makes linkgit:git-send-email[1] assume `--mailmap`,
-	otherwise assume `--no-mailmap`. False by default.
+	If `true`, makes linkgit:git-send-email[1] assume `--mailmap`,
+	otherwise assume `--no-mailmap`. `False` by default.
 
 sendemail.mailmap.file::
 	The location of a linkgit:git-send-email[1] specific augmenting
@@ -96,6 +96,11 @@ sendemail.xmailer::
 	linkgit:git-send-email[1] command-line options. See its
 	documentation for details.
 
+sendemail.outlookidfix::
+	If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`,
+	and if `false` assume `--no-outlook-id-fix`. If not specified, it will
+	behave the same way as if `--outlook-id-fix` is not specified.
+
 sendemail.signedOffCc (deprecated)::
 	Deprecated alias for `sendemail.signedOffByCc`.
 

-- 
2.50.0.windows.1
Aditya Garg· Jun 30, 2025, 18:06 UTC · re: Aditya Garg · lore

[PATCH 3/5] docs: add an OAuth2.0 credential helper for AOL accounts

From: Aditya Garg <gargaditya08@live.com>

Yahoo and AOL, both advertise that they support app passwords for third-party applications. But generating app passwords for them is broken and unreliable for quite some time now. Yahoo already had an OAuth2.0 credential helper added in the documentation, so I thought it would be a good idea to add one for AOL accounts as well, which is more reliable and secure.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 3 +++
 1 file changed, 3 insertions(+)
Show changes to Documentation/git-send-email.adoc +3 −0
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 4208bac44c..b31145901c 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -600,6 +600,9 @@ available online. Community maintained credential helpers are also available:
 	- https://github.com/AdityaGarg8/git-credential-email[git-credential-yahoo]
 	  (cross platform, dedicated helper for authenticating Yahoo accounts)
 
+	- https://github.com/AdityaGarg8/git-credential-email[git-credential-aol]
+	  (cross platform, dedicated helper for authenticating AOL accounts)
+
 You can also see linkgit:gitcredentials[7] for more OAuth based authentication
 helpers.
 

-- 
2.50.0.windows.1
Aditya Garg· Jun 30, 2025, 18:06 UTC · re: Aditya Garg · lore

[PATCH 4/5] docs: add a paragraph explaining the `sendmailCmd` option of sendemail

From: Aditya Garg <gargaditya08@live.com>

`sendmailCmd` is a configuration option in `git-send-email` that allows users to send emails using an external application that supports sendmail-like commands. This ability has been very useful to support proprietary email APIs without modifying the `git-send-email` codebase. It is also useful for users who prefer to use another SMTP client instead of the SMTP perl library used by `git-send-email`. This commit adds a paragraph to the documentation explaining this option.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
Show changes to Documentation/git-send-email.adoc +29 −0
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index b31145901c..6556f949a1 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -619,6 +619,35 @@ These additional Perl modules are also required:
 https://metacpan.org/pod/Authen::SASL[Authen::SASL] and
 https://metacpan.org/pod/Mail::Address[Mail::Address].
 
+Exploiting the `sendmailCmd` option of `git send-email`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Apart from sending emails via an SMTP server, `git send-email` can also send
+emails through any application that supports sendmail-like commands. You can
+read documentation of `--sendmail-cmd=<command>` above for more information.
+This ability can be very useful if you want to use another application as an
+SMTP client for `git send-email`, or if your email provider uses proprietary
+APIs instead of SMTP to send emails.
+
+As an example, lets see how to configure https://marlam.de/msmtp/[msmtp], a
+popular SMTP client found in many Linux distributions. Edit `~/.gitconfig`
+to instruct `git-send-email` to use it for sending emails.
+
+----
+[sendemail]
+	sendmailCmd = /usr/bin/msmtp # Change this to the path where msmtp is installed
+----
+
+Links of a few such community maintained helpers are:
+
+	- https://marlam.de/msmtp/[msmtp]
+	  (popular SMTP client with many features, available for Linux and macOS)
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-protonmail]
+	  (cross platform client that can send emails using the ProtonMail API)
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-msgraph]
+	  (cross platform client that can send emails using the Microsoft Graph API)
 
 SEE ALSO
 --------

-- 
2.50.0.windows.1
Aditya Garg· Jun 30, 2025, 18:06 UTC · re: Aditya Garg · lore

[PATCH 5/5] docs: mention possible options for Proton Mail users

From: Aditya Garg <gargaditya08@live.com>

Proton Mail is an privacy-focused email service gaining popularity. Unfortunately, it does not provide an SMTP server to send emails. Proton Mail Bridge is an official solution for paid users, and for free users, a client named git-protonmail is available. Mention the same in the docs.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)
Show changes to Documentation/git-send-email.adoc +8 −0
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
index 6556f949a1..5335502d68 100644
--- a/Documentation/git-send-email.adoc
+++ b/Documentation/git-send-email.adoc
@@ -606,6 +606,14 @@ available online. Community maintained credential helpers are also available:
 You can also see linkgit:gitcredentials[7] for more OAuth based authentication
 helpers.
 
+Proton Mail does not provide an SMTP server to send emails. If you are a paid
+customer of Proton Mail, you can use
+https://proton.me/mail/bridge[Proton Mail Bridge]
+officially provided by Proton Mail to create a local SMTP server for sending
+emails. For both free and paid users, community maintained projects like
+https://github.com/AdityaGarg8/git-credential-email[git-protonmail] can be
+used.
+
 Note: the following core Perl modules that may be installed with your
 distribution of Perl are required:
 

-- 
2.50.0.windows.1

← back to recent threads