Docs: send-email: Create logical groupings for man text
[gitweb.git] / git-send-email.perl
index c6bba47eb638a4d5c9e5013c405ed8f5ed6292ce..80dae88c7333df2cb72022570dc8f18ab61972d1 100755 (executable)
@@ -38,73 +38,41 @@ package main;
 
 sub usage {
        print <<EOT;
-git-send-email [options] <file | directory>...
-Options:
-   --from         Specify the "From:" line of the email to be sent.
-
-   --to           Specify the primary "To:" line of the email.
-
-   --cc           Specify an initial "Cc:" list for the entire series
-                  of emails.
-
-   --cc-cmd       Specify a command to execute per file which adds
-                  per file specific cc address entries
-
-   --bcc          Specify a list of email addresses that should be Bcc:
-                 on all the emails.
-
-   --compose      Use \$GIT_EDITOR, core.editor, \$EDITOR, or \$VISUAL to edit
-                 an introductory message for the patch series.
-
-   --subject      Specify the initial "Subject:" line.
-                  Only necessary if --compose is also set.  If --compose
-                 is not set, this will be prompted for.
-
-   --in-reply-to  Specify the first "In-Reply-To:" header line.
-                  Only used if --compose is also set.  If --compose is not
-                 set, this will be prompted for.
-
-   --chain-reply-to If set, the replies will all be to the previous
-                  email sent, rather than to the first email sent.
-                  Defaults to on.
-
-   --signed-off-cc Automatically add email addresses that appear in
-                 Signed-off-by: or Cc: lines to the cc: list. Defaults to on.
-
-   --identity     The configuration identity, a subsection to prioritise over
-                  the default section.
-
-   --smtp-server  If set, specifies the outgoing SMTP server to use.
-                  Defaults to localhost.  Port number can be specified here with
-                  hostname:port format or by using --smtp-server-port option.
-
-   --smtp-server-port Specify a port on the outgoing SMTP server to connect to.
-
-   --smtp-user    The username for SMTP-AUTH.
-
-   --smtp-pass    The password for SMTP-AUTH.
-
-   --smtp-ssl     If set, connects to the SMTP server using SSL.
-
-   --suppress-cc  Suppress the specified category of auto-CC.  The category
-                 can be one of 'author' for the patch author, 'self' to
-                 avoid copying yourself, 'sob' for Signed-off-by lines,
-                 'cccmd' for the output of the cccmd, or 'all' to suppress
-                 all of these.
-
-   --suppress-from Suppress sending emails to yourself. Defaults to off.
-
-   --thread       Specify that the "In-Reply-To:" header should be set on all
-                  emails. Defaults to on.
-
-   --quiet       Make git-send-email less verbose.  One line per email
-                  should be all that is output.
-
-   --dry-run     Do everything except actually send the emails.
-
-   --envelope-sender   Specify the envelope sender used to send the emails.
-
-   --no-validate       Don't perform any sanity checks on patches.
+git send-email [options] <file | directory>...
+
+  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:"
+    --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.
+    --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, cccmd, all.
+    --[no-]signed-off-by-cc        * Send to Cc: and 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:
+    --quiet                        * Output one line of info per email.
+    --dry-run                      * Don't actually send the emails.
+    --[no-]validate                * Perform patch sanity checks. Default on.
 
 EOT
        exit(1);
@@ -168,7 +136,8 @@ sub format_2822_time {
 # Example reply to:
 #$initial_reply_to = ''; #<20050203173208.GA23964@foobar.com>';
 
-my $repo = Git->repository();
+my $repo = eval { Git->repository() };
+my @repo = $repo ? ($repo) : ();
 my $term = eval {
        $ENV{"GIT_SEND_EMAIL_NOTTY"}
                ? new Term::ReadLine 'git-send-email', \*STDIN, \*STDOUT
@@ -183,9 +152,9 @@ sub format_2822_time {
 
 # Variables with corresponding config settings
 my ($thread, $chain_reply_to, $suppress_from, $signed_off_cc, $cc_cmd);
-my ($smtp_server, $smtp_server_port, $smtp_authuser, $smtp_ssl);
+my ($smtp_server, $smtp_server_port, $smtp_authuser, $smtp_encryption);
 my ($identity, $aliasfiletype, @alias_files, @smtp_host_parts);
-my ($no_validate);
+my ($validate);
 my (@suppress_cc);
 
 my %config_bool_settings = (
@@ -193,7 +162,7 @@ sub format_2822_time {
     "chainreplyto" => [\$chain_reply_to, 1],
     "suppressfrom" => [\$suppress_from, undef],
     "signedoffcc" => [\$signed_off_cc, undef],
-    "smtpssl" => [\$smtp_ssl, 0],
+    "validate" => [\$validate, 1],
 );
 
 my %config_settings = (
@@ -202,11 +171,13 @@ sub format_2822_time {
     "smtpuser" => \$smtp_authuser,
     "smtppass" => \$smtp_authpass,
     "to" => \@to,
+    "cc" => \@initial_cc,
     "cccmd" => \$cc_cmd,
     "aliasfiletype" => \$aliasfiletype,
     "bcc" => \@bcclist,
     "aliasesfile" => \@alias_files,
     "suppresscc" => \@suppress_cc,
+    "envelopesender" => \$envelope_sender,
 );
 
 # Handle Uncouth Termination
@@ -246,7 +217,8 @@ sub signal_handler {
                    "smtp-server-port=s" => \$smtp_server_port,
                    "smtp-user=s" => \$smtp_authuser,
                    "smtp-pass:s" => \$smtp_authpass,
-                   "smtp-ssl!" => \$smtp_ssl,
+                   "smtp-ssl" => sub { $smtp_encryption = 'ssl' },
+                   "smtp-encryption=s" => \$smtp_encryption,
                    "identity=s" => \$identity,
                    "compose" => \$compose,
                    "quiet" => \$quiet,
@@ -257,7 +229,7 @@ sub signal_handler {
                    "dry-run" => \$dry_run,
                    "envelope-sender=s" => \$envelope_sender,
                    "thread!" => \$thread,
-                   "no-validate" => \$no_validate,
+                   "validate!" => \$validate,
         );
 
 unless ($rc) {
@@ -271,25 +243,34 @@ sub read_config {
 
        foreach my $setting (keys %config_bool_settings) {
                my $target = $config_bool_settings{$setting}->[0];
-               $$target = $repo->config_bool("$prefix.$setting") unless (defined $$target);
+               $$target = Git::config_bool(@repo, "$prefix.$setting") unless (defined $$target);
        }
 
        foreach my $setting (keys %config_settings) {
                my $target = $config_settings{$setting};
                if (ref($target) eq "ARRAY") {
                        unless (@$target) {
-                               my @values = $repo->config("$prefix.$setting");
+                               my @values = Git::config(@repo, "$prefix.$setting");
                                @$target = @values if (@values && defined $values[0]);
                        }
                }
                else {
-                       $$target = $repo->config("$prefix.$setting") unless (defined $$target);
+                       $$target = Git::config(@repo, "$prefix.$setting") unless (defined $$target);
+               }
+       }
+
+       if (!defined $smtp_encryption) {
+               my $enc = Git::config(@repo, "$prefix.smtpencryption");
+               if (defined $enc) {
+                       $smtp_encryption = $enc;
+               } elsif (Git::config_bool(@repo, "$prefix.smtpssl")) {
+                       $smtp_encryption = 'ssl';
                }
        }
 }
 
 # read configuration from [sendemail "$identity"], fall back on [sendemail]
-$identity = $repo->config("sendemail.identity") unless (defined $identity);
+$identity = Git::config(@repo, "sendemail.identity") unless (defined $identity);
 read_config("sendemail.$identity") if (defined $identity);
 read_config("sendemail");
 
@@ -298,6 +279,9 @@ sub read_config {
        ${$setting->[0]} = $setting->[1] unless (defined (${$setting->[0]}));
 }
 
+# 'default' encryption is none -- this only prevents a warning
+$smtp_encryption = '' unless (defined $smtp_encryption);
+
 # Set CC suppressions
 my(%suppress_cc);
 if (@suppress_cc) {
@@ -327,8 +311,9 @@ sub read_config {
        }
 }
 
-my ($repoauthor) = $repo->ident_person('author');
-my ($repocommitter) = $repo->ident_person('committer');
+my ($repoauthor, $repocommitter);
+($repoauthor) = Git::ident_person(@repo, 'author');
+($repocommitter) = Git::ident_person(@repo, 'committer');
 
 # Verify the user input
 
@@ -389,7 +374,7 @@ sub read_config {
                push @files, grep { -f $_ } map { +$f . "/" . $_ }
                                sort readdir(DH);
 
-       } elsif (-f $f) {
+       } elsif (-f $f or -p $f) {
                push @files, $f;
 
        } else {
@@ -397,10 +382,12 @@ sub read_config {
        }
 }
 
-if (!$no_validate) {
+if ($validate) {
        foreach my $f (@files) {
-               my $error = validate_patch($f);
-               $error and die "fatal: $f: $error\nwarning: no patches were sent\n";
+               unless (-p $f) {
+                       my $error = validate_patch($f);
+                       $error and die "fatal: $f: $error\nwarning: no patches were sent\n";
+               }
        }
 }
 
@@ -415,7 +402,7 @@ sub read_config {
 
 my $prompting = 0;
 if (!defined $sender) {
-       $sender = $repoauthor || $repocommitter;
+       $sender = $repoauthor || $repocommitter || '';
 
        while (1) {
                $_ = $term->readline("Who should the emails appear to be from? [$sender] ");
@@ -438,7 +425,7 @@ sub read_config {
        }
 
        my $to = $_;
-       push @to, split /,/, $to;
+       push @to, split /,\s*/, $to;
        $prompting++;
 }
 
@@ -509,8 +496,8 @@ sub expand_aliases {
 EOT
        close(C);
 
-       my $editor = $ENV{GIT_EDITOR} || $repo->config("core.editor") || $ENV{VISUAL} || $ENV{EDITOR} || "vi";
-       system('sh', '-c', '$0 $@', $editor, $compose_filename);
+       my $editor = $ENV{GIT_EDITOR} || Git::config(@repo, "core.editor") || $ENV{VISUAL} || $ENV{EDITOR} || "vi";
+       system('sh', '-c', $editor.' "$@"', $editor, $compose_filename);
 
        open(C2,">",$compose_filename . ".final")
                or die "Failed to open $compose_filename.final : " . $!;
@@ -734,7 +721,7 @@ sub send_message
                        die "The required SMTP server is not properly defined."
                }
 
-               if ($smtp_ssl) {
+               if ($smtp_encryption eq 'ssl') {
                        $smtp_server_port ||= 465; # ssmtp
                        require Net::SMTP::SSL;
                        $smtp ||= Net::SMTP::SSL->new($smtp_server, Port => $smtp_server_port);
@@ -744,6 +731,21 @@ sub send_message
                        $smtp ||= Net::SMTP->new((defined $smtp_server_port)
                                                 ? "$smtp_server:$smtp_server_port"
                                                 : $smtp_server);
+                       if ($smtp_encryption eq 'tls') {
+                               require Net::SMTP::SSL;
+                               $smtp->command('STARTTLS');
+                               $smtp->response();
+                               if ($smtp->code == 220) {
+                                       $smtp = Net::SMTP::SSL->start_SSL($smtp)
+                                               or die "STARTTLS failed! ".$smtp->message;
+                                       $smtp_encryption = '';
+                                       # Send EHLO again to receive fresh
+                                       # supported commands
+                                       $smtp->hello();
+                               } else {
+                                       die "Server does not support STARTTLS! ".$smtp->message;
+                               }
+                       }
                }
 
                if (!$smtp) {
@@ -846,7 +848,7 @@ sub send_message
                                }
                                elsif (/^Content-type:/i) {
                                        $has_content_type = 1;
-                                       if (/charset="?[^ "]+/) {
+                                       if (/charset="?([^ "]+)/) {
                                                $body_encoding = $1;
                                        }
                                        push @xh, $_;