git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH RFC3.5 01/12] send-email: Cleanup the usage text and docs a bit

From
Michael Witten <mfwitten@gmail.com>
Date
Apr 18, 2009, 17:01 UTC
Message-ID
<1240074128-16132-2-git-send-email-mfwitten@gmail.com>
In-Reply-To
<1240074128-16132-1-git-send-email-mfwitten@gmail.com>
--chain-reply-to doesn't take an argument.

The here-document quotation that defines the usage text is now a single-quote form, so that no interpolation takes place.

All usage text lines should be < 80 characters.
The usage text's option arguments match those of the docs.

The 'host:port' form of argument for --smtp-server was only working for SSL connections, because the SSL connection code was relying on undocumented behavior of Net::SMTP::SSL (really, undocumented behavior of Net::SMTP's new method). Because the main documentation for send-email doesn't even list it as valid, <str:int> has been replaced with just <server> and <host | command> in the usage text; this is only temporary and for purity.

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-send-email.txt |   21 ++++++++-------
 git-send-email.perl              |   49 +++++++++++++++++++++-----------------
 2 files changed, 38 insertions(+), 32 deletions(-)
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index f7e428e..071e9bf 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -74,8 +74,9 @@ See the CONFIGURATION section for 'sendemail.multiedit'.
 	the value GIT_COMMITTER_IDENT, as returned by "git var -l".
 	The user will still be prompted to confirm this entry.
 
---in-reply-to=<identifier>::
-	Specify the contents of the first In-Reply-To header.
+--in-reply-to=<message-id>::
+	Specify the contents of the first In-Reply-To header;
+	include the angle brackets `<` and `>`.
 	Subsequent emails will refer to the previous email
 	instead of this if --chain-reply-to is set (the default)
 	Only necessary if --compose is also set.  If --compose
@@ -106,7 +107,7 @@ Sending
 	the 'sendemail.envelopesender' configuration variable; if that is
 	unspecified, choosing the envelope sender is left to your MTA.
 
---smtp-encryption=<encryption>::
+--smtp-encryption=<type>::
 	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
 	value reverts to plain SMTP.  Default is the value of
 	'sendemail.smtpencryption'.
@@ -123,20 +124,20 @@ or on the command line. If a username has been specified (with
 specified (with '--smtp-pass' or 'sendemail.smtppass'), then the
 user is prompted for a password while the input is masked for privacy.
 
---smtp-server=<host>::
+--smtp-server=<server>::
 	If set, specifies the outgoing SMTP server to use (e.g.
 	`smtp.example.com` or a raw IP address).  Alternatively it can
 	specify a full pathname of a sendmail-like program instead;
 	the program must support the `-i` option.  Default value can
 	be specified by the 'sendemail.smtpserver' configuration
-	option; the built-in default is `/usr/sbin/sendmail` or
-	`/usr/lib/sendmail` if such program is available, or
+	variable; the built-in default is `/usr/sbin/sendmail` or
+	`/usr/lib/sendmail` if such a program is available, or
 	`localhost` otherwise.
 
 --smtp-server-port=<port>::
 	Specifies a port different from the default port (SMTP
 	servers typically listen to smtp port 25 and ssmtp port
-	465); symbolic port names (e.g. "submission" instead of 465)
+	465); symbolic service names (e.g. "submission" instead of 587)
 	are also accepted. The port can also be set with the
 	'sendemail.smtpserverport' configuration variable.
 
@@ -158,7 +159,7 @@ Automating
 	Output of this command must be single email address per line.
 	Default is the value of 'sendemail.cccmd' configuration value.
 
---[no-]chain-reply-to=<identifier>::
+--[no-]chain-reply-to::
 	If this is set, each email will be sent as a reply to the previous
 	email sent.  If disabled with "--no-chain-reply-to", all emails after
 	the first will be sent as replies to the first email sent.  When using
@@ -170,7 +171,7 @@ Automating
 	A configuration identity. When given, causes values in the
 	'sendemail.<identity>' subsection to take precedence over
 	values in the 'sendemail' section. The default identity is
-	the value of 'sendemail.identity'.
+	the value of the 'sendemail.identity' configuration variable.
 
 --[no-]signed-off-by-cc::
 	If this is set, add emails found in Signed-off-by: or Cc: lines to the
@@ -214,7 +215,7 @@ specified, as well as 'body' if --no-signed-off-cc is specified.
 Administering
 ~~~~~~~~~~~~~
 
---confirm=<mode>::
+--confirm=<when>::
 	Confirm just before sending:
 +
 --
diff --git a/git-send-email.perl b/git-send-email.perl
index 04267c5..e43342e 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -42,46 +42,51 @@ package main;
 
 
 sub usage {
-	print <<EOT;
+
+	# All printed lines should be less than 80 characters.
+
+	print <<'EOT';
 git send-email [options] <file | directory | rev-list options >
 
   Composing:
-    --from                  <str>  * Email From:
-    --to                    <str>  * Email To:
-    --cc                    <str>  * Email Cc:
-    --bcc                   <str>  * Email Bcc:
-    --subject               <str>  * Email "Subject:"
-    --in-reply-to           <str>  * Email "In-Reply-To:"
-    --annotate                     * Review each patch that will be sent in an editor.
+    --from              <address>  * Email From:
+    --to                <address>  * Email To:
+    --cc                <address>  * Email Cc:
+    --bcc               <address>  * Email Bcc:
+    --subject            <string>  * Email "Subject:"
+    --in-reply-to    <message-id>  * Email "In-Reply-To:"; include '<' and '>'.
+    --annotate                     * Review each patch that will be sent in
+                                     an editor.
     --compose                      * Open an editor for introduction.
 
   Sending:
-    --envelope-sender       <str>  * Email envelope sender.
-    --smtp-server       <str:int>  * Outgoing SMTP server to use. The port
-                                     is optional. Default 'localhost'.
-    --smtp-server-port      <int>  * Outgoing SMTP server port.
-    --smtp-user             <str>  * Username for SMTP-AUTH.
-    --smtp-pass             <str>  * Password for SMTP-AUTH; not necessary.
-    --smtp-encryption       <str>  * tls or ssl; anything else disables.
+    --envelope-sender   <address>  * Email envelope sender.
+    --smtp-server        <server>  * Outgoing SMTP server. <host | command>
+    --smtp-server-port     <port>  * Outgoing SMTP server port; symbolic too.
+    --smtp-user        <username>  * Username for SMTP-AUTH.
+    --smtp-pass       [<password>] * Password for SMTP-AUTH; not necessary.
+    --smtp-encryption      <type>  * tls or ssl; anything else disables.
     --smtp-ssl                     * Deprecated. Use '--smtp-encryption ssl'.
 
   Automating:
-    --identity              <str>  * Use the sendemail.<id> options.
-    --cc-cmd                <str>  * Email Cc: via `<str> \$patch_path`
-    --suppress-cc           <str>  * author, self, sob, cc, cccmd, body, bodycc, all.
-    --[no-]signed-off-by-cc        * Send to Signed-off-by: addresses. Default on.
+    --identity         <identity>  * Use the sendemail.<identity> options.
+    --cc-cmd            <command>  * Email Cc: via `<command> $patch_path`
+    --suppress-cc      <category>  * author, self, sob, cc, cccmd, body,
+                                     bodycc, all.
+    --[no-]signed-off-by-cc        * Send to Signed-off-by: addresses.
+                                     Default on.
     --[no-]suppress-from           * Send to self. Default off.
     --[no-]chain-reply-to          * Chain In-Reply-To: fields. Default on.
     --[no-]thread                  * Use In-Reply-To: field. Default on.
 
   Administering:
-    --confirm               <str>  * Confirm recipients before sending;
+    --confirm              <when>  * Confirm recipients before sending;
                                      auto, cc, compose, always, or never.
     --quiet                        * Output one line of info per email.
     --dry-run                      * Don't actually send the emails.
     --[no-]validate                * Perform patch sanity checks. Default on.
-    --[no-]format-patch            * understand any non optional arguments as
-                                     `git format-patch` ones.
+    --[no-]format-patch            * Understand any non-optional arguments as
+                                     `git format-patch' arguments.
 
 EOT
 	exit(1);

-- 
1.6.2.2.479.g2aec
Previous: Michael WittenNext: Michael Witten
Message 2 of 50 in “Introduction to Decreasing send-email Entropy”
  1. 00/12 Introduction to Decreasing send-email EntropyMichael Witten, Apr 18, 2009
  2. 01/12 send-email: Cleanup the usage text and docs a bitMichael Witten, Apr 18, 2009
  3. 02/12 send-email: No longer repeatedly test if $smtp_server is a commandMichael Witten, Apr 18, 2009
  4. 03/12 send-email: Interpret --smtp-server "" as "use a default".Michael Witten, Apr 18, 2009
  5. 04/12 send-email: Verification for --smtp-server and --smpt-server-portMichael Witten, Apr 18, 2009
  6. 05/12 send-email: Improve redability and error-handling in send_message's sendmail codeMichael Witten, Apr 18, 2009
  7. 06/12 send-email: Cleanup and streamline the SMTP code in send_messageMichael Witten, Apr 18, 2009
  8. 07/12 send-email: Cleanup send_message 'log' codeMichael Witten, Apr 18, 2009
  9. 08/12 send-email: Move Subject sanitization from --compose code to send_messageMichael Witten, Apr 18, 2009
  10. 09/12 Docs: send-email: Reorganize the CONFIGURATION sectionMichael Witten, Apr 18, 2009
  11. 10/12 Docs: Embolden the CONFIGURATION referencesMichael Witten, Apr 18, 2009
  12. 11/12 Docs: send-email: Clarification of sendemail.<identity>Michael Witten, Apr 18, 2009
  13. 12/12 Docs: send-email: git send-email -> 'send-email'Michael Witten, Apr 18, 2009
  14. Jay SoffianApr 19, 2009
  15. Michael WittenApr 19, 2009
  16. Jay SoffianApr 19, 2009
  17. Michael WittenApr 19, 2009
  18. Michael WittenApr 19, 2009
  19. 08/12 send-email: Simplify --compose subject sanitationMichael Witten, Apr 19, 2009
  20. Jeff KingApr 21, 2009
  21. Michael WittenApr 21, 2009
  22. Junio C HamanoApr 20, 2009
  23. Michael WittenApr 20, 2009
  24. Junio C HamanoApr 20, 2009
  25. Jay SoffianApr 19, 2009
  26. Michael WittenApr 19, 2009
  27. Thomas AdamApr 19, 2009
  28. Michael WittenApr 19, 2009
  29. Junio C HamanoApr 19, 2009
  30. 05/12 send-email: Improve readability and error-handling in send_message's sendmail codeMichael Witten, Apr 19, 2009
  31. Jay SoffianApr 19, 2009
  32. Junio C HamanoApr 20, 2009
  33. Junio C HamanoApr 20, 2009
  34. Jeff KingApr 21, 2009
  35. Jeff KingApr 21, 2009
  36. 04/12 send-email: Verification for --smtp-server and --smpt-server-portMichael Witten, Apr 19, 2009
  37. Michael WittenApr 20, 2009
  38. Junio C HamanoApr 20, 2009
  39. Junio C HamanoApr 20, 2009
  40. Michael WittenApr 20, 2009
  41. Michael WittenApr 20, 2009
  42. Wesley J. LandakerApr 18, 2009
  43. Michael WittenApr 19, 2009
  44. 03/12 send-email: Interpret --smtp-server "" as "use a default".Michael Witten, Apr 19, 2009
  45. Junio C HamanoApr 20, 2009
  46. Michael WittenApr 20, 2009
  47. Junio C HamanoApr 20, 2009
  48. Michael WittenApr 20, 2009
  49. Junio C HamanoApr 20, 2009
  50. Subject: Re: [PATCH RFC3.5 02/12] send-email: No longer repeatedly test if $smtp_server is a commandMichael Witten, Apr 20, 2009

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.