Documentation / git-send-email.txton commit transport.c: introduce core.alternateRefsCommand (89284c1)
   1git-send-email(1)
   2=================
   3
   4NAME
   5----
   6git-send-email - Send a collection of patches as emails
   7
   8
   9SYNOPSIS
  10--------
  11[verse]
  12'git send-email' [<options>] <file|directory|rev-list options>...
  13'git send-email' --dump-aliases
  14
  15
  16DESCRIPTION
  17-----------
  18Takes the patches given on the command line and emails them out.
  19Patches can be specified as files, directories (which will send all
  20files in the directory), or directly as a revision list.  In the
  21last case, any format accepted by linkgit:git-format-patch[1] can
  22be passed to git send-email.
  23
  24The header of the email is configurable via command-line options.  If not
  25specified on the command line, the user will be prompted with a ReadLine
  26enabled interface to provide the necessary information.
  27
  28There are two formats accepted for patch files:
  29
  301. mbox format files
  31+
  32This is what linkgit:git-format-patch[1] generates.  Most headers and MIME
  33formatting are ignored.
  34
  352. The original format used by Greg Kroah-Hartman's 'send_lots_of_email.pl'
  36script
  37+
  38This format expects the first line of the file to contain the "Cc:" value
  39and the "Subject:" of the message as the second line.
  40
  41
  42OPTIONS
  43-------
  44
  45Composing
  46~~~~~~~~~
  47
  48--annotate::
  49        Review and edit each patch you're about to send. Default is the value
  50        of `sendemail.annotate`. See the CONFIGURATION section for
  51        `sendemail.multiEdit`.
  52
  53--bcc=<address>,...::
  54        Specify a "Bcc:" value for each email. Default is the value of
  55        `sendemail.bcc`.
  56+
  57This option may be specified multiple times.
  58
  59--cc=<address>,...::
  60        Specify a starting "Cc:" value for each email.
  61        Default is the value of `sendemail.cc`.
  62+
  63This option may be specified multiple times.
  64
  65--compose::
  66        Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1])
  67        to edit an introductory message for the patch series.
  68+
  69When `--compose` is used, git send-email will use the From, Subject, and
  70In-Reply-To headers specified in the message. If the body of the message
  71(what you type after the headers and a blank line) only contains blank
  72(or Git: prefixed) lines, the summary won't be sent, but From, Subject,
  73and In-Reply-To headers will be used unless they are removed.
  74+
  75Missing From or In-Reply-To headers will be prompted for.
  76+
  77See the CONFIGURATION section for `sendemail.multiEdit`.
  78
  79--from=<address>::
  80        Specify the sender of the emails.  If not specified on the command line,
  81        the value of the `sendemail.from` configuration option is used.  If
  82        neither the command-line option nor `sendemail.from` are set, then the
  83        user will be prompted for the value.  The default for the prompt will be
  84        the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not
  85        set, as returned by "git var -l".
  86
  87--reply-to=<address>::
  88        Specify the address where replies from recipients should go to.
  89        Use this if replies to messages should go to another address than what
  90        is specified with the --from parameter.
  91
  92--in-reply-to=<identifier>::
  93        Make the first mail (or all the mails with `--no-thread`) appear as a
  94        reply to the given Message-Id, which avoids breaking threads to
  95        provide a new patch series.
  96        The second and subsequent emails will be sent as replies according to
  97        the `--[no-]chain-reply-to` setting.
  98+
  99So for example when `--thread` and `--no-chain-reply-to` are specified, the
 100second and subsequent patches will be replies to the first one like in the
 101illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:
 102+
 103  [PATCH 0/2] Here is what I did...
 104    [PATCH 1/2] Clean up and tests
 105    [PATCH 2/2] Implementation
 106    [PATCH v2 0/3] Here is a reroll
 107      [PATCH v2 1/3] Clean up
 108      [PATCH v2 2/3] New tests
 109      [PATCH v2 3/3] Implementation
 110+
 111Only necessary if --compose is also set.  If --compose
 112is not set, this will be prompted for.
 113
 114--subject=<string>::
 115        Specify the initial subject of the email thread.
 116        Only necessary if --compose is also set.  If --compose
 117        is not set, this will be prompted for.
 118
 119--to=<address>,...::
 120        Specify the primary recipient of the emails generated. Generally, this
 121        will be the upstream maintainer of the project involved. Default is the
 122        value of the `sendemail.to` configuration value; if that is unspecified,
 123        and --to-cmd is not specified, this will be prompted for.
 124+
 125This option may be specified multiple times.
 126
 127--8bit-encoding=<encoding>::
 128        When encountering a non-ASCII message or subject that does not
 129        declare its encoding, add headers/quoting to indicate it is
 130        encoded in <encoding>.  Default is the value of the
 131        'sendemail.assume8bitEncoding'; if that is unspecified, this
 132        will be prompted for if any non-ASCII files are encountered.
 133+
 134Note that no attempts whatsoever are made to validate the encoding.
 135
 136--compose-encoding=<encoding>::
 137        Specify encoding of compose message. Default is the value of the
 138        'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed.
 139
 140--transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::
 141        Specify the transfer encoding to be used to send the message over SMTP.
 142        7bit will fail upon encountering a non-ASCII message.  quoted-printable
 143        can be useful when the repository contains files that contain carriage
 144        returns, but makes the raw patch email file (as saved from a MUA) much
 145        harder to inspect manually.  base64 is even more fool proof, but also
 146        even more opaque.  auto will use 8bit when possible, and quoted-printable
 147        otherwise.
 148+
 149Default is the value of the `sendemail.transferEncoding` configuration
 150value; if that is unspecified, default to `auto`.
 151
 152--xmailer::
 153--no-xmailer::
 154        Add (or prevent adding) the "X-Mailer:" header.  By default,
 155        the header is added, but it can be turned off by setting the
 156        `sendemail.xmailer` configuration variable to `false`.
 157
 158Sending
 159~~~~~~~
 160
 161--envelope-sender=<address>::
 162        Specify the envelope sender used to send the emails.
 163        This is useful if your default address is not the address that is
 164        subscribed to a list. In order to use the 'From' address, set the
 165        value to "auto". If you use the sendmail binary, you must have
 166        suitable privileges for the -f parameter.  Default is the value of the
 167        `sendemail.envelopeSender` configuration variable; if that is
 168        unspecified, choosing the envelope sender is left to your MTA.
 169
 170--smtp-encryption=<encryption>::
 171        Specify the encryption to use, either 'ssl' or 'tls'.  Any other
 172        value reverts to plain SMTP.  Default is the value of
 173        `sendemail.smtpEncryption`.
 174
 175--smtp-domain=<FQDN>::
 176        Specifies the Fully Qualified Domain Name (FQDN) used in the
 177        HELO/EHLO command to the SMTP server.  Some servers require the
 178        FQDN to match your IP address.  If not set, git send-email attempts
 179        to determine your FQDN automatically.  Default is the value of
 180        `sendemail.smtpDomain`.
 181
 182--smtp-auth=<mechanisms>::
 183        Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting
 184        forces using only the listed mechanisms. Example:
 185+
 186------
 187$ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ...
 188------
 189+
 190If at least one of the specified mechanisms matches the ones advertised by the
 191SMTP server and if it is supported by the utilized SASL library, the mechanism
 192is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth`
 193is specified, all mechanisms supported by the SASL library can be used.
 194
 195--smtp-pass[=<password>]::
 196        Password for SMTP-AUTH. The argument is optional: If no
 197        argument is specified, then the empty string is used as
 198        the password. Default is the value of `sendemail.smtpPass`,
 199        however `--smtp-pass` always overrides this value.
 200+
 201Furthermore, passwords need not be specified in configuration files
 202or on the command line. If a username has been specified (with
 203`--smtp-user` or a `sendemail.smtpUser`), but no password has been
 204specified (with `--smtp-pass` or `sendemail.smtpPass`), then
 205a password is obtained using 'git-credential'.
 206
 207--smtp-server=<host>::
 208        If set, specifies the outgoing SMTP server to use (e.g.
 209        `smtp.example.com` or a raw IP address).  Alternatively it can
 210        specify a full pathname of a sendmail-like program instead;
 211        the program must support the `-i` option.  Default value can
 212        be specified by the `sendemail.smtpServer` configuration
 213        option; the built-in default is to search for `sendmail` in
 214        `/usr/sbin`, `/usr/lib` and $PATH if such program is
 215        available, falling back to `localhost` otherwise.
 216
 217--smtp-server-port=<port>::
 218        Specifies a port different from the default port (SMTP
 219        servers typically listen to smtp port 25, but may also listen to
 220        submission port 587, or the common SSL smtp port 465);
 221        symbolic port names (e.g. "submission" instead of 587)
 222        are also accepted. The port can also be set with the
 223        `sendemail.smtpServerPort` configuration variable.
 224
 225--smtp-server-option=<option>::
 226        If set, specifies the outgoing SMTP server option to use.
 227        Default value can be specified by the `sendemail.smtpServerOption`
 228        configuration option.
 229+
 230The --smtp-server-option option must be repeated for each option you want
 231to pass to the server. Likewise, different lines in the configuration files
 232must be used for each option.
 233
 234--smtp-ssl::
 235        Legacy alias for '--smtp-encryption ssl'.
 236
 237--smtp-ssl-cert-path::
 238        Path to a store of trusted CA certificates for SMTP SSL/TLS
 239        certificate validation (either a directory that has been processed
 240        by 'c_rehash', or a single file containing one or more PEM format
 241        certificates concatenated together: see verify(1) -CAfile and
 242        -CApath for more information on these). Set it to an empty string
 243        to disable certificate verification. Defaults to the value of the
 244        `sendemail.smtpsslcertpath` configuration variable, if set, or the
 245        backing SSL library's compiled-in default otherwise (which should
 246        be the best choice on most platforms).
 247
 248--smtp-user=<user>::
 249        Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`;
 250        if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),
 251        then authentication is not attempted.
 252
 253--smtp-debug=0|1::
 254        Enable (1) or disable (0) debug output. If enabled, SMTP
 255        commands and replies will be printed. Useful to debug TLS
 256        connection and authentication problems.
 257
 258--batch-size=<num>::
 259        Some email servers (e.g. smtp.163.com) limit the number emails to be
 260        sent per session (connection) and this will lead to a failure when
 261        sending many messages.  With this option, send-email will disconnect after
 262        sending $<num> messages and wait for a few seconds (see --relogin-delay)
 263        and reconnect, to work around such a limit.  You may want to
 264        use some form of credential helper to avoid having to retype
 265        your password every time this happens.  Defaults to the
 266        `sendemail.smtpBatchSize` configuration variable.
 267
 268--relogin-delay=<int>::
 269        Waiting $<int> seconds before reconnecting to SMTP server. Used together
 270        with --batch-size option.  Defaults to the `sendemail.smtpReloginDelay`
 271        configuration variable.
 272
 273Automating
 274~~~~~~~~~~
 275
 276--to-cmd=<command>::
 277        Specify a command to execute once per patch file which
 278        should generate patch file specific "To:" entries.
 279        Output of this command must be single email address per line.
 280        Default is the value of 'sendemail.tocmd' configuration value.
 281
 282--cc-cmd=<command>::
 283        Specify a command to execute once per patch file which
 284        should generate patch file specific "Cc:" entries.
 285        Output of this command must be single email address per line.
 286        Default is the value of `sendemail.ccCmd` configuration value.
 287
 288--[no-]chain-reply-to::
 289        If this is set, each email will be sent as a reply to the previous
 290        email sent.  If disabled with "--no-chain-reply-to", all emails after
 291        the first will be sent as replies to the first email sent.  When using
 292        this, it is recommended that the first file given be an overview of the
 293        entire patch series. Disabled by default, but the `sendemail.chainReplyTo`
 294        configuration variable can be used to enable it.
 295
 296--identity=<identity>::
 297        A configuration identity. When given, causes values in the
 298        'sendemail.<identity>' subsection to take precedence over
 299        values in the 'sendemail' section. The default identity is
 300        the value of `sendemail.identity`.
 301
 302--[no-]signed-off-by-cc::
 303        If this is set, add emails found in Signed-off-by: or Cc: lines to the
 304        cc list. Default is the value of `sendemail.signedoffbycc` configuration
 305        value; if that is unspecified, default to --signed-off-by-cc.
 306
 307--[no-]cc-cover::
 308        If this is set, emails found in Cc: headers in the first patch of
 309        the series (typically the cover letter) are added to the cc list
 310        for each email set. Default is the value of 'sendemail.cccover'
 311        configuration value; if that is unspecified, default to --no-cc-cover.
 312
 313--[no-]to-cover::
 314        If this is set, emails found in To: headers in the first patch of
 315        the series (typically the cover letter) are added to the to list
 316        for each email set. Default is the value of 'sendemail.tocover'
 317        configuration value; if that is unspecified, default to --no-to-cover.
 318
 319--suppress-cc=<category>::
 320        Specify an additional category of recipients to suppress the
 321        auto-cc of:
 322+
 323--
 324- 'author' will avoid including the patch author
 325- 'self' will avoid including the sender
 326- 'cc' will avoid including anyone mentioned in Cc lines in the patch header
 327  except for self (use 'self' for that).
 328- 'bodycc' will avoid including anyone mentioned in Cc lines in the
 329  patch body (commit message) except for self (use 'self' for that).
 330- 'sob' will avoid including anyone mentioned in Signed-off-by lines except
 331   for self (use 'self' for that).
 332- 'cccmd' will avoid running the --cc-cmd.
 333- 'body' is equivalent to 'sob' + 'bodycc'
 334- 'all' will suppress all auto cc values.
 335--
 336+
 337Default is the value of `sendemail.suppresscc` configuration value; if
 338that is unspecified, default to 'self' if --suppress-from is
 339specified, as well as 'body' if --no-signed-off-cc is specified.
 340
 341--[no-]suppress-from::
 342        If this is set, do not add the From: address to the cc: list.
 343        Default is the value of `sendemail.suppressFrom` configuration
 344        value; if that is unspecified, default to --no-suppress-from.
 345
 346--[no-]thread::
 347        If this is set, the In-Reply-To and References headers will be
 348        added to each email sent.  Whether each mail refers to the
 349        previous email (`deep` threading per 'git format-patch'
 350        wording) or to the first email (`shallow` threading) is
 351        governed by "--[no-]chain-reply-to".
 352+
 353If disabled with "--no-thread", those headers will not be added
 354(unless specified with --in-reply-to).  Default is the value of the
 355`sendemail.thread` configuration value; if that is unspecified,
 356default to --thread.
 357+
 358It is up to the user to ensure that no In-Reply-To header already
 359exists when 'git send-email' is asked to add it (especially note that
 360'git format-patch' can be configured to do the threading itself).
 361Failure to do so may not produce the expected result in the
 362recipient's MUA.
 363
 364
 365Administering
 366~~~~~~~~~~~~~
 367
 368--confirm=<mode>::
 369        Confirm just before sending:
 370+
 371--
 372- 'always' will always confirm before sending
 373- 'never' will never confirm before sending
 374- 'cc' will confirm before sending when send-email has automatically
 375  added addresses from the patch to the Cc list
 376- 'compose' will confirm before sending the first message when using --compose.
 377- 'auto' is equivalent to 'cc' + 'compose'
 378--
 379+
 380Default is the value of `sendemail.confirm` configuration value; if that
 381is unspecified, default to 'auto' unless any of the suppress options
 382have been specified, in which case default to 'compose'.
 383
 384--dry-run::
 385        Do everything except actually send the emails.
 386
 387--[no-]format-patch::
 388        When an argument may be understood either as a reference or as a file name,
 389        choose to understand it as a format-patch argument (`--format-patch`)
 390        or as a file name (`--no-format-patch`). By default, when such a conflict
 391        occurs, git send-email will fail.
 392
 393--quiet::
 394        Make git-send-email less verbose.  One line per email should be
 395        all that is output.
 396
 397--[no-]validate::
 398        Perform sanity checks on patches.
 399        Currently, validation means the following:
 400+
 401--
 402                *       Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
 403                *       Warn of patches that contain lines longer than
 404                        998 characters unless a suitable transfer encoding
 405                        ('auto', 'base64', or 'quoted-printable') is used;
 406                        this is due to SMTP limits as described by
 407                        http://www.ietf.org/rfc/rfc5322.txt.
 408--
 409+
 410Default is the value of `sendemail.validate`; if this is not set,
 411default to `--validate`.
 412
 413--force::
 414        Send emails even if safety checks would prevent it.
 415
 416
 417Information
 418~~~~~~~~~~~
 419
 420--dump-aliases::
 421        Instead of the normal operation, dump the shorthand alias names from
 422        the configured alias file(s), one per line in alphabetical order. Note,
 423        this only includes the alias name and not its expanded email addresses.
 424        See 'sendemail.aliasesfile' for more information about aliases.
 425
 426
 427CONFIGURATION
 428-------------
 429
 430sendemail.aliasesFile::
 431        To avoid typing long email addresses, point this to one or more
 432        email aliases files.  You must also supply `sendemail.aliasFileType`.
 433
 434sendemail.aliasFileType::
 435        Format of the file(s) specified in sendemail.aliasesFile. Must be
 436        one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
 437+
 438What an alias file in each format looks like can be found in
 439the documentation of the email program of the same name. The
 440differences and limitations from the standard formats are
 441described below:
 442+
 443--
 444sendmail;;
 445*       Quoted aliases and quoted addresses are not supported: lines that
 446        contain a `"` symbol are ignored.
 447*       Redirection to a file (`/path/name`) or pipe (`|command`) is not
 448        supported.
 449*       File inclusion (`:include: /path/name`) is not supported.
 450*       Warnings are printed on the standard error output for any
 451        explicitly unsupported constructs, and any other lines that are not
 452        recognized by the parser.
 453--
 454
 455sendemail.multiEdit::
 456        If true (default), a single editor instance will be spawned to edit
 457        files you have to edit (patches when `--annotate` is used, and the
 458        summary when `--compose` is used). If false, files will be edited one
 459        after the other, spawning a new editor each time.
 460
 461sendemail.confirm::
 462        Sets the default for whether to confirm before sending. Must be
 463        one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
 464        in the previous section for the meaning of these values.
 465
 466EXAMPLES
 467--------
 468Use gmail as the smtp server
 469~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 470To use 'git send-email' to send your patches through the GMail SMTP server,
 471edit ~/.gitconfig to specify your account settings:
 472
 473        [sendemail]
 474                smtpEncryption = tls
 475                smtpServer = smtp.gmail.com
 476                smtpUser = yourname@gmail.com
 477                smtpServerPort = 587
 478
 479If you have multifactor authentication setup on your gmail account, you will
 480need to generate an app-specific password for use with 'git send-email'. Visit
 481https://security.google.com/settings/security/apppasswords to create it.
 482
 483Once your commits are ready to be sent to the mailing list, run the
 484following commands:
 485
 486        $ git format-patch --cover-letter -M origin/master -o outgoing/
 487        $ edit outgoing/0000-*
 488        $ git send-email outgoing/*
 489
 490The first time you run it, you will be prompted for your credentials.  Enter the
 491app-specific or your regular password as appropriate.  If you have credential
 492helper configured (see linkgit:git-credential[1]), the password will be saved in
 493the credential store so you won't have to type it the next time.
 494
 495Note: the following perl modules are required
 496      Net::SMTP::SSL, MIME::Base64 and Authen::SASL
 497
 498SEE ALSO
 499--------
 500linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
 501
 502GIT
 503---
 504Part of the linkgit:git[1] suite