From 96e5b72d1a7ce8851cf8d1bdfc61f717c0a39407 Mon Sep 17 00:00:00 2001 From: Aditya Garg Date: Mon, 30 Jun 2025 18:06:28 +0000 Subject: [PATCH 1/5] docs: link OpenSSL's verify(1) manual page to know about -CAfile and -CApath options 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 Signed-off-by: Junio C Hamano --- Documentation/git-send-email.adoc | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) 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` __ and the `-CApath` __ 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=:: Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`; From a717ef18f2fa7c91e801869ec5aab00d99d4ceb5 Mon Sep 17 00:00:00 2001 From: Aditya Garg Date: Mon, 30 Jun 2025 18:06:34 +0000 Subject: [PATCH 2/5] docs: add outlookidfix config option to sendemail documentation 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 Signed-off-by: Junio C Hamano --- Documentation/config/sendemail.adoc | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) 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`. From 18617b2afd74db9912ae80b55a2c813b90231629 Mon Sep 17 00:00:00 2001 From: Aditya Garg Date: Mon, 30 Jun 2025 18:06:40 +0000 Subject: [PATCH 3/5] docs: add an OAuth2.0 credential helper for AOL accounts 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 Signed-off-by: Junio C Hamano --- Documentation/git-send-email.adoc | 3 +++ 1 file changed, 3 insertions(+) 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. From 95ce81f68d519339fc57c0f321845527792cade9 Mon Sep 17 00:00:00 2001 From: Aditya Garg Date: Mon, 30 Jun 2025 18:06:46 +0000 Subject: [PATCH 4/5] docs: add a paragraph explaining the `sendmailCmd` option of sendemail `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 Signed-off-by: Junio C Hamano --- Documentation/git-send-email.adoc | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) 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=` 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 -------- From ac1a32ea52532fadba18128d67b9dc211002059e Mon Sep 17 00:00:00 2001 From: Aditya Garg Date: Mon, 30 Jun 2025 18:06:56 +0000 Subject: [PATCH 5/5] docs: mention possible options for Proton Mail users 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 Signed-off-by: Junio C Hamano --- Documentation/git-send-email.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) 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: