diff options
| -rw-r--r-- | Documentation/git-send-email.txt | 242 | ||||
| -rwxr-xr-x | contrib/completion/git-completion.bash | 3 | ||||
| -rwxr-xr-x | git-send-email.perl | 117 |
3 files changed, 147 insertions, 215 deletions
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 3c3e1b0e7..82f505686 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -11,7 +11,6 @@ SYNOPSIS 'git send-email' [options] <file|directory> [... file|directory] - DESCRIPTION ----------- Takes the patches given on the command line and emails them out. @@ -20,12 +19,16 @@ The header of the email is configurable by command line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information. + OPTIONS ------- -The options available are: + +Composing +~~~~~~~~~ --bcc:: - Specify a "Bcc:" value for each email. + Specify a "Bcc:" value for each email. Default is the value of + 'sendemail.bcc'. + The --bcc option must be repeated for each user you want on the bcc list. @@ -34,22 +37,6 @@ The --bcc option must be repeated for each user you want on the bcc list. + The --cc option must be repeated for each user you want on the cc list. ---cc-cmd:: - Specify a command to execute once per patch file which - should generate patch file specific "Cc:" entries. - Output of this command must be single email address per line. - Default is the value of 'sendemail.cccmd' configuration value. - ---chain-reply-to:: ---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 - this, it is recommended that the first file given be an overview of the - entire patch series. - Default is the value of the 'sendemail.chainreplyto' configuration - value; if that is unspecified, default to --chain-reply-to. - --compose:: Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an introductory message for the patch series. @@ -66,22 +53,47 @@ The --cc option must be repeated for each user you want on the cc list. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---signed-off-by-cc:: ---no-signed-off-by-cc:: - If this is set, add emails found in Signed-off-by: or Cc: lines to the - cc list. - Default is the value of 'sendemail.signedoffcc' configuration value; - if that is unspecified, default to --signed-off-by-cc. +--subject:: + Specify the initial subject of the email thread. + Only necessary if --compose is also set. If --compose + is not set, this will be prompted for. + +--to:: + Specify the primary recipient of the emails generated. Generally, this + will be the upstream maintainer of the project involved. Default is the + value of the 'sendemail.to' configuration value; if that is unspecified, + this will be prompted for. ++ +The --to option must be repeated for each user you want on the to list. ---quiet:: - Make git-send-email less verbose. One line per email should be - all that is output. ---identity:: - 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'. +Sending +~~~~~~~ + +--envelope-sender:: + Specify the envelope sender used to send the emails. + This is useful if your default address is not the address that is + subscribed to a list. If you use the sendmail binary, you must have + suitable privileges for the -f parameter. Default is the value of + the 'sendemail.envelopesender' configuration variable; if that is + unspecified, choosing the envelope sender is left to your MTA. + +--smtp-encryption:: + Specify the encryption to use, either 'ssl' or 'tls'. Any other + value reverts to plain SMTP. Default is the value of + 'sendemail.smtpencryption'. + +--smtp-pass:: + Password for SMTP-AUTH. The argument is optional: If no + argument is specified, then the empty string is used as + the password. Default is the value of 'sendemail.smtppass', + however '--smtp-pass' always overrides this value. ++ +Furthermore, passwords need not be specified in configuration files +or on the command line. If a username has been specified (with +'--smtp-user' or a 'sendemail.smtpuser'), but no password has been +specified (with '--smtp-pass' or 'sendemail.smtppass'), then the +user is prompted for a password while the input is masked for privacy. --smtp-server:: If set, specifies the outgoing SMTP server to use (e.g. @@ -96,61 +108,44 @@ The --cc option must be repeated for each user you want on the cc list. --smtp-server-port:: Specifies a port different from the default port (SMTP servers typically listen to smtp port 25 and ssmtp port - 465). + 465). This can be set with 'sendemail.smtpserverport'. + +--smtp-ssl:: + Legacy alias for '--smtp-encryption ssl'. --smtp-user:: - Username for SMTP-AUTH. In place of this option, the following - configuration variables can be specified: -+ --- - * sendemail.smtpuser - * sendemail.<identity>.smtpuser (see sendemail.identity). --- -+ -However, --smtp-user always overrides these variables. -+ -If a username is not specified (with --smtp-user or a -configuration variable), then authentication is not attempted. + Username for SMTP-AUTH. Default is the value of 'sendemail.smtpuser'; + if a username is not specified (with '--smtp-user' or 'sendemail.smtpuser'), + then authentication is not attempted. ---smtp-pass:: - Password for SMTP-AUTH. The argument is optional: If no - argument is specified, then the empty string is used as - the password. -+ -In place of this option, the following configuration variables -can be specified: -+ --- - * sendemail.smtppass - * sendemail.<identity>.smtppass (see sendemail.identity). --- -+ -However, --smtp-pass always overrides these variables. -+ -Furthermore, passwords need not be specified in configuration files -or on the command line. If a username has been specified (with ---smtp-user or a configuration variable), but no password has been -specified (with --smtp-pass or a configuration variable), then the -user is prompted for a password while the input is masked for privacy. ---smtp-encryption:: - Specify the encryption to use, either 'ssl' or 'tls'. Any other - value reverts to plain SMTP. Default is the value of - 'sendemail.smtpencryption'. +Automating +~~~~~~~~~~ ---smtp-ssl:: - Legacy alias for '--smtp-encryption=ssl'. +--cc-cmd:: + Specify a command to execute once per patch file which + should generate patch file specific "Cc:" entries. + Output of this command must be single email address per line. + Default is the value of 'sendemail.cccmd' configuration value. ---subject:: - Specify the initial subject of the email thread. - Only necessary if --compose is also set. If --compose - is not set, this will be prompted for. +--[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 + this, it is recommended that the first file given be an overview of the + entire patch series. Default is the value of the 'sendemail.chainreplyto' + configuration value; if that is unspecified, default to --chain-reply-to. + +--identity:: + 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'. ---suppress-from:: ---no-suppress-from:: - If this is set, do not add the From: address to the cc: list. - Default is the value of 'sendemail.suppressfrom' configuration value; - if that is unspecified, default to --no-suppress-from. +--[no-]signed-off-by-cc:: + If this is set, add emails found in Signed-off-by: or Cc: lines to the + cc list. Default is the value of 'sendemail.signedoffbycc' configuration + value; if that is unspecified, default to --signed-off-by-cc. --suppress-cc:: Specify an additional category of recipients to suppress the @@ -163,44 +158,43 @@ user is prompted for a password while the input is masked for privacy. if that is unspecified, default to 'self' if --suppress-from is specified, as well as 'sob' if --no-signed-off-cc is specified. ---thread:: ---no-thread:: +--[no-]suppress-from:: + If this is set, do not add the From: address to the cc: list. + Default is the value of 'sendemail.suppressfrom' configuration + value; if that is unspecified, default to --no-suppress-from. + +--[no-]thread:: If this is set, the In-Reply-To header will be set on each email sent. If disabled with "--no-thread", no emails will have the In-Reply-To - header set. - Default is the value of the 'sendemail.thread' configuration value; - if that is unspecified, default to --thread. + header set. Default is the value of the 'sendemail.thread' configuration + value; if that is unspecified, default to --thread. + + +Administering +~~~~~~~~~~~~~ --dry-run:: Do everything except actually send the emails. ---envelope-sender:: - Specify the envelope sender used to send the emails. - This is useful if your default address is not the address that is - subscribed to a list. If you use the sendmail binary, you must have - suitable privileges for the -f parameter. - Default is the value of the 'sendemail.envelopesender' configuration - variable; if that is unspecified, choosing the envelope sender is left - to your MTA. +--quiet:: + Make git-send-email less verbose. One line per email should be + all that is output. ---to:: - Specify the primary recipient of the emails generated. - Generally, this will be the upstream maintainer of the - project involved. - Default is the value of the 'sendemail.to' configuration value; - if that is unspecified, this will be prompted for. +--[no-]validate:: + Perform sanity checks on patches. + Currently, validation means the following: + -The --to option must be repeated for each user you want on the to list. +-- + * Warn of patches that contain lines longer than 998 characters; this + is due to SMTP limits as described by http://www.ietf.org/rfc/rfc2821.txt. +-- ++ +Default is the value of 'sendemail.validate'; if this is not set, +default to '--validate'. CONFIGURATION ------------- -sendemail.identity:: - The default configuration identity. When specified, - 'sendemail.<identity>.<item>' will have higher precedence than - 'sendemail.<item>'. This is useful to declare multiple SMTP - identities and to hoist sensitive authentication information - out of the repository and into the global configuration file. sendemail.aliasesfile:: To avoid typing long email addresses, point this to one or more @@ -210,38 +204,6 @@ sendemail.aliasfiletype:: Format of the file(s) specified in sendemail.aliasesfile. Must be one of 'mutt', 'mailrc', 'pine', or 'gnus'. -sendemail.to:: - Email address (or alias) to always send to. - -sendemail.cccmd:: - Command to execute to generate per patch file specific "Cc:"s. - -sendemail.bcc:: - Email address (or alias) to always bcc. - -sendemail.chainreplyto:: - Boolean value specifying the default to the '--chain_reply_to' - parameter. - -sendemail.smtpserver:: - Default SMTP server to use. - -sendemail.smtpserverport:: - Default SMTP server port to use. - -sendemail.smtpuser:: - Default SMTP-AUTH username. - -sendemail.smtppass:: - Default SMTP-AUTH password. - -sendemail.smtpencryption:: - Default encryption method. Use 'ssl' for SSL (and specify an - appropriate port), or 'tls' for TLS. Takes precedence over - 'smtpssl' if both are specified. - -sendemail.smtpssl:: - Legacy boolean that sets 'smtpencryption=ssl' if enabled. Author ------ @@ -250,10 +212,12 @@ Written by Ryan Anderson <ryan@michonline.com> git-send-email is originally based upon send_lots_of_email.pl by Greg Kroah-Hartman. + Documentation -------------- Documentation by Ryan Anderson + GIT --- Part of the linkgit:git[1] suite diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash index 15073d4c9..d192927c2 100755 --- a/contrib/completion/git-completion.bash +++ b/contrib/completion/git-completion.bash @@ -1123,7 +1123,8 @@ _git_send_email () --no-suppress-from --no-thread --quiet --signed-off-by-cc --smtp-pass --smtp-server --smtp-server-port --smtp-ssl --smtp-user --subject - --suppress-cc --suppress-from --thread --to" + --suppress-cc --suppress-from --thread --to + --validate --no-validate" return ;; esac diff --git a/git-send-email.perl b/git-send-email.perl index d2fd89907..bdbfac662 100755 --- a/git-send-email.perl +++ b/git-send-email.perl @@ -39,75 +39,40 @@ 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-encryption Specify 'tls' for STARTTLS encryption, or 'ssl' for SSL. - Any other value disables the feature. - - --smtp-ssl Synonym for '--smtp-encryption=ssl'. Deprecated. - - --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. + 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); @@ -186,17 +151,19 @@ if ($@) { my ($quiet, $dry_run) = (0, 0); # Variables with corresponding config settings -my ($thread, $chain_reply_to, $suppress_from, $signed_off_cc, $cc_cmd); +my ($thread, $chain_reply_to, $suppress_from, $signed_off_by_cc, $cc_cmd); 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 = ( "thread" => [\$thread, 1], "chainreplyto" => [\$chain_reply_to, 1], "suppressfrom" => [\$suppress_from, undef], - "signedoffcc" => [\$signed_off_cc, undef], + "signedoffbycc" => [\$signed_off_by_cc, undef], + "signedoffcc" => [\$signed_off_by_cc, undef], # Deprecated + "validate" => [\$validate, 1], ); my %config_settings = ( @@ -259,11 +226,11 @@ my $rc = GetOptions("sender|from=s" => \$sender, "cc-cmd=s" => \$cc_cmd, "suppress-from!" => \$suppress_from, "suppress-cc=s" => \@suppress_cc, - "signed-off-cc|signed-off-by-cc!" => \$signed_off_cc, + "signed-off-cc|signed-off-by-cc!" => \$signed_off_by_cc, "dry-run" => \$dry_run, "envelope-sender=s" => \$envelope_sender, "thread!" => \$thread, - "no-validate" => \$no_validate, + "validate!" => \$validate, ); unless ($rc) { @@ -335,7 +302,7 @@ if ($suppress_cc{'all'}) { # If explicit old-style ones are specified, they trump --suppress-cc. $suppress_cc{'self'} = $suppress_from if defined $suppress_from; -$suppress_cc{'sob'} = !$signed_off_cc if defined $signed_off_cc; +$suppress_cc{'sob'} = !$signed_off_by_cc if defined $signed_off_by_cc; # Debugging, print out the suppressions. if (0) { @@ -416,7 +383,7 @@ for my $f (@ARGV) { } } -if (!$no_validate) { +if ($validate) { foreach my $f (@files) { unless (-p $f) { my $error = validate_patch($f); |