[PATCH] send-email: clarify SMTP encryption settings

[Drew DeVault <sir@cmpwn.com>]

The present options are misleading; "ssl" enables generic, "modern" SSL
support, which could use either SSL or TLS; and "tls" enables the
SMTP-specific (and deprecated) STARTTLS protocol.

This changes the canonical config options to "ssl/tls" and "starttls",
updates the docs to explain the options in more detail, and updates
git-send-email to accept either form.
---
 Documentation/git-send-email.txt | 11 ++++++++---
 git-send-email.perl              |  4 ++--
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 93708aefea..3597935e41 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -168,9 +168,14 @@ Sending
 	unspecified, choosing the envelope sender is left to your MTA.
 
 --smtp-encryption=<encryption>::
-	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
-	value reverts to plain SMTP.  Default is the value of
-	`sendemail.smtpEncryption`.
+	Specify the encryption to use, either 'ssl/tls' or 'starttls', whichever
+	is recommended by your email service provider.  SSL/TLS is typically
+	used on port 465 and is preferred if available.  STARTTLS is typically
+	used on port 25 or 587. Any other value reverts to plain SMTP.  The
+	default is the value of `sendemail.smtpEncryption`.
++
+For legacy reasons, 'ssl' is accepted for 'ssl/tls' and 'tls' is accepted for
+'starttls'.
 
 --smtp-domain=<FQDN>::
 	Specifies the Fully Qualified Domain Name (FQDN) used in the
diff --git a/git-send-email.perl b/git-send-email.perl
index f5bbf1647e..34fdf587bd 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -1503,7 +1503,7 @@ sub send_message {
 		my $use_net_smtp_ssl = version->parse($Net::SMTP::VERSION) < version->parse("2.34");
 		$smtp_domain ||= maildomain();
 
-		if ($smtp_encryption eq 'ssl') {
+		if ($smtp_encryption eq 'ssl' || $smtp_encryption eq 'ssl/tls') {
 			$smtp_server_port ||= 465; # ssmtp
 			require IO::Socket::SSL;
 
@@ -1538,7 +1538,7 @@ sub send_message {
 						 Hello => $smtp_domain,
 						 Debug => $debug_net_smtp,
 						 Port => $smtp_server_port);
-			if ($smtp_encryption eq 'tls' && $smtp) {
+			if (($smtp_encryption eq 'tls' || $smtp_encryption eq 'starttls') && $smtp) {
 				if ($use_net_smtp_ssl) {
 					$smtp->command('STARTTLS');
 					$smtp->response();
-- 
2.31.1