stg-mail(1)
===========

NAME
----
stg-mail - Send a patch or series of patches by e-mail

SYNOPSIS
--------
[verse]
'stg' mail  [options] [<patch1>] [<patch2>] [<patch3>..<patch4>]

DESCRIPTION
-----------

Send a patch or a range of patches by e-mail using the SMTP server
specified by the 'stgit.smtpserver' configuration option, or the
'--smtp-server' command line option. This option can also be an
absolute path to 'sendmail' followed by command line arguments.

The From address and the e-mail format are generated from the template
file passed as argument to '--template' (defaulting to
'.git/patchmail.tmpl' or '~/.stgit/templates/patchmail.tmpl' or
'/usr/share/stgit/templates/patchmail.tmpl'). A patch can be sent as
attachment using the --attach option in which case the
'mailattch.tmpl' template will be used instead of 'patchmail.tmpl'.

The To/Cc/Bcc addresses can either be added to the template file or
passed via the corresponding command line options. They can be e-mail
addresses or aliases which are automatically expanded to the values
stored in the [mail "alias"] section of GIT configuration files.

A preamble e-mail can be sent using the '--cover' and/or
'--edit-cover' options. The first allows the user to specify a file to
be used as a template. The latter option will invoke the editor on the
specified file (defaulting to '.git/covermail.tmpl' or
'~/.stgit/templates/covermail.tmpl' or
'/usr/share/stgit/templates/covermail.tmpl').

All the subsequent e-mails appear as replies to the first e-mail sent
(either the preamble or the first patch). E-mails can be seen as
replies to a different e-mail by using the '--refid' option.

SMTP authentication is also possible with '--smtp-user' and
'--smtp-password' options, also available as configuration settings:
'smtpuser' and 'smtppassword'. TLS encryption can be enabled by
'--smtp-tls' option and 'smtptls' setting.

The following variables are accepted by both the preamble and the
patch e-mail templates:

  %(diffstat)s     - diff statistics
  %(number)s       - empty if only one patch is sent or ' patchnr/totalnr'
  %(patchnr)s      - patch number
  %(sender)s       - 'sender'  or 'authname <authemail>' as per the config file
  %(totalnr)s      - total number of patches to be sent
  %(version)s      - ' version' string passed on the command line (or empty)

In addition to the common variables, the preamble e-mail template
accepts the following:

  %(shortlog)s     - first line of each patch description, listed by author

In addition to the common variables, the patch e-mail template accepts
the following:

  %(authdate)s     - patch creation date
  %(authemail)s    - author's email
  %(authname)s     - author's name
  %(commemail)s    - committer's e-mail
  %(commname)s     - committer's name
  %(diff)s         - unified diff of the patch
  %(fromauth)s     - 'From: author\n\n' if different from sender
  %(longdescr)s    - the rest of the patch description, after the first line
  %(patch)s        - patch name
  %(prefix)s       - 'prefix ' string passed on the command line
  %(shortdescr)s   - the first line of the patch description

OPTIONS
-------
-a::
--all::
        E-mail all the applied patches.

--to TO::
        Add TO to the To: list.

--cc CC::
        Add CC to the Cc: list.

--bcc BCC::
        Add BCC to the Bcc: list.

--auto::
        Automatically cc the patch signers.

--noreply::
        Do not send subsequent messages as replies.

--unrelated::
        Send patches without sequence numbering.

--attach::
        Send a patch as attachment.

-v VERSION::
--version VERSION::
        Add VERSION to the [PATCH ...] prefix.

--prefix PREFIX::
        Add PREFIX to the [... PATCH ...] prefix.

-t FILE::
--template FILE::
        Use FILE as the message template.

-c FILE::
--cover FILE::
        Send FILE as the cover message.

-e::
--edit-cover::
        Edit the cover message before sending.

-E::
--edit-patches::
        Edit each patch before sending.

-s SECONDS::
--sleep SECONDS::
        Sleep for SECONDS between e-mails sending.

--refid REFID::
        Use REFID as the reference id.

--smtp-server HOST[:PORT] or "/path/to/sendmail -t -i"::
        SMTP server or command to use for sending mail.

-u USER::
--smtp-user USER::
        Username for SMTP authentication.

-p PASSWORD::
--smtp-password PASSWORD::
        Password for SMTP authentication.

-T::
--smtp-tls::
        Use SMTP with TLS encryption.

-b BRANCH::
--branch BRANCH::
        Use BRANCH instead of the default branch.

-m::
--mbox::
        Generate an mbox file instead of sending.

-O OPTIONS::
--diff-opts OPTIONS::
        Extra options to pass to "git diff".

StGit
-----
Part of the StGit suite - see linkman:stg[1]