# stg-email

## NAME



           stg-email - Format and send patches as email
    


## SYNOPSIS



           _stg email format_ [OPTIONS] <patch>...
           _stg email format_ [OPTIONS] --all
           _stg email send_ [OPTIONS] <file|directory>...
           _stg email send_ [OPTIONS] <patch>...
           _stg email send_ [OPTIONS] --all
           _stg email send_ --dump-aliases
           _stg email help format_
           _stg email help send_
           _stg email help help_
    


## DESCRIPTION



           Format and send patches as email.
    
           A typical workflow is to first generate email files for each patch
           along with an optional cover letter using ‘stg email format**. Then,**
           **after checking the email files’ contents, sending the emails using**
           **`stg email send**. This workflow may be condensed to one step by
           specifying patch names to **stg email send** instead of email files.
    
           The **format** and **send** subcommands are thin wrappers over **git**
           **format-patch** and **git send-email** , respectively. Refer to the
           git-format-patch(1) and git-send-email(1) manpages for more
           details about configuration and options.
    


## COMMANDS



           format
               Format selected patches as email files, one patch per file.
               The files are formatted to resemble a UNIX mailbox (mbox) and
               may be sent with the **stg email send** command. The first line of
               the patch’s commit message is used to form the email’s subject
               with the remainder of the message in the email’s body.
    
               The patches to format may be specified as individual patch
               names or patch ranges of the form _p0..p3_ , or _--all_ may be used
               to format all applied patches. Note that the specified patches
               must be contiguous within the patch series.
    
               By default, the email files will be output to the current
               directory, however use of the -o/--output-directory option is
               recommended since sending the email with **stg email send <dir>**
               is simpler than specifying all the email files individually.
    
               A cover letter template may also be generated by specifying
               _--cover-letter_. A cover letter is recommended when sending
               multiple patches. The **format.coverLetter** configuration value
               may be set true to always generate a cover letter or _auto_ to
               generate a cover letter when formatting more than one patch.
    
               Recipients may be specified using the _--to_ and _--cc_ , or
               setting recipients may be deferred to **stg email send**.
    
               Many aspects of the format behavior may be controlled via
               **format.*** configuration values. Refer to the git-config(1) and
               git-format-patch(1) man pages for more details.
    
           send
               Send patches as emails.
    
               This is a wrapper for **git send-email**. Refer to the
               git-send-email(1) man page for additional details.
    
               The patches to send may be specified as files or directories
               generated by **stg email format** , or as patch names/ranges as
               would be supplied to **stg email format**. Specifying a directory
               will send all files in that directory.
    
               The header of the email is configurable via command line
               options. The user will be prompted for any necessary
               information not specified on the command line or in the
               configuration.
    
               Many aspects of the send behavior may be controlled via the
               **sendemail.*** configuration options. In particular, it is
               recommended to statically configure SMTP details such as
               **sendemail.smtpServer** , **sendemail.smtpUser** , etc. Refer to
               git-config(1) and git-send-email(1) man pages for more detail
               on all the available configuration options.
    
       **FORMAT OPTIONS**
           -b <branch>, --branch=<branch>
               Use <branch> instead of current branch
    
           -a, --all
               Format all applied patches
    
           -G <option>, --git-opt=<option>
               Pass additional <option> to **git format-patch**.
    
               See the git-format-patch(1) man page. This option may be
               specified multiple times.
    
           -o <dir>, --output-directory=<dir>
               Use <dir> to store the output files instead of the current
               working directory.
    
           --cover-letter
               In addition to the patches, generate a cover letter file
               containing the branch description, shortlog and the overall
               diffstat. You can fill in a description in the file before
               sending it out.
    
           -n, --numbered
               Use [PATCH n/m] even with a single patch
    
           -N, --no-numbered
               Use [PATCH] even with multiple patches
    
           --start-number=<n>
               Start numbering at <n> instead of 1
    
           -v <n>, --reroll-count=<n>
               Mark the series as the <n>-th iteration of the topic. The
               output filenames have "v<n>" prepended to them, and the
               subject prefix ("PATCH" by default, but configurable via the
               --subject-prefix option) has ` v<N>` appended to it. E.g.
               _--reroll-count=4_ may produce v4-0001-add-makefile.patch file
               that has "Subject: [PATCH v4 1/20] Add makefile" in it. <N>
               does not have to be an integer (e.g.  _--reroll-count=4.4_ , or
               _--reroll-count=4rev2_ are allowed), but the downside of using
               such a reroll-count is that the range-diff/interdiff with the
               previous version does not state exactly which version the new
               iteration is compared against.
    
           --rfc
               Alias for _--subject-prefix="RFC PATCH"_. RFC means "Request For
               Comments"; use this when sending an experimental patch for
               discussion rather than application.
    
           --subject-prefix=<prefix>
               Instead of the standard **[PATCH]** prefix in the subject line,
               instead use **[ <prefix>]**. This allows for useful naming of a
               patch series, and can be combined with the _--numbered_ option.
    
           --quiet
               Do not print the names of the generated files
    
           -s, --signoff
               Add a Signed-off-by trailer to the commit message, using the
               committer identity of yourself. See the signoff option in
               git-commit(1) for more information.
    
           --numbered-files
               Output file names will be a simple number sequence without the
               default first line of the commit appended.
    
           --suffix=<suffix>
               Instead of using **.patch** as the suffix for generated filenames,
               use specified suffix. A common alternative is _--suffix=.txt_.
               Leaving this empty will remove the **.patch** suffix.
    
           -k, --keep-subject
               Do not strip/add **[PATCH]** from the first line of the commit log
               message.
    
           --no-binary
               Do not output contents of changes in binary files, instead
               display a notice that those files changed. Patches generated
               using this option cannot be applied properly, but they are
               still useful for code review.
    
           --zero-commit
               Output an all-zero hash in each patch’s **From** header instead of
               the hash of the commit.
    
           --to=<address>
               Add a **To:** header to the email headers. This is in addition to
               any configured headers, and may be used multiple times. The
               negated form _--no-to_ discards all **To:** headers added so far
               (from config or command line).
    
           --no-to
               Discard all **To:** addresses added so far from config or command
               line.
    
           --cc=<address>
               Add a **Cc:** header to the email headers. This is in addition to
               any configured headers, and may be used multiple times. The
               negated form _--no-cc_ discards all **Cc:** headers added so far
               (from config or command line).
    
           --no-cc
               Discard all **Cc:** addresses added so far from config or command
               line.
    
           --in-reply-to=<message-id>
               Make the first mail (or all the mails with _--no-thread_) appear
               as a reply to the given <message-id>, which avoids breaking
               threads to provide a new patch series.
    
           --add-header=<header>
               Add an arbitrary header to the email headers. This is in
               addition to any configured headers, and may be used multiple
               times. For example, _--add-header="Organization: git-foo"_.
    
           --attach
               Create multipart/mixed attachment, the first part of which is
               the commit message and the patch itself in the second part,
               with **Content-Disposition:** attachment.
    
           --inline
               Create multipart/mixed attachment, the first part of which is
               the commit message and the patch itself in the second part,
               with **Content-Disposition: inline**.
    
           --thread[=<style>]
               Controls addition of **In-Reply-To** and **References** headers to
               make the second and subsequent mails appear as replies to the
               first. Also controls generation of the **Message-ID** header to
               reference.
    
               The optional <style> argument can be either **shallow** or **deep**.
               **shallow** threading makes every mail a reply to the head of the
               series, where the head is chosen from the cover letter, the
               _--in-reply-to_ , and the first patch mail, in this order.  **deep**
               threading makes every mail a reply to the previous one.
    
               The default is _--no-thread_ , unless the **format.thread**
               configuration is set. If _--thread_ is specified without a
               style, it defaults to the style specified by **format.thread** if
               any, or else **shallow**.
    
               Beware that the default for **git send-email** is to thread emails
               itself. If you want **git format-patch** to take care of
               threading, you will want to ensure that threading is disabled
               for **git send-email**.
    
           --no-thread
               Disable message threading
    
           --signature=<signature>
               Add a signature string to each email. The default signature is
               the git version number, or the **format.signature** configuration
               value, if specified. The signature may be disabled with
               _--no-signature_
    
           --no-signature
               Do not add a signature to each email
    
           --signature-file=<file>
               Like _--signature_ except the signature is read from a file.
    
           --base=<committish>
               See the BASE TREE INFORMATION section of git-format-patch(1).
    
           --progress
               Show progress reports on stderr as patches are generated.
    
           --interdiff=<rev>
               As a reviewer aid, insert an interdiff into the cover letter,
               or as commentary of the lone patch of a 1-patch series,
               showing the differences between the previous version of the
               patch series and the series currently being formatted. <rev>
               is a single revision naming the tip of the previous series
               which shares a common base with the series being formatted
               (for example **git format-patch --cover-letter**
               **--interdiff=feature/v1 -3 feature/v2**).
    
           --range-diff=<refspec>
               As a reviewer aid, insert a range-diff (see git-range-diff(1))
               into the cover letter, or as commentary of the lone patch of a
               single-patch series, showing the differences between the
               previous version of the patch series and the series currently
               being formatted. <refspec> can be a single revision naming the
               tip of the previous series if it shares a common base with the
               series being formatted (for example **git format-patch**
               **--cover-letter --range-diff=feature/v1 -3 feature/v2**), or a
               revision range if the two versions of the series are disjoint
               (for example **git format-patch --cover-letter**
               **--range-diff=feature/v1~3..feature/v1 -3 feature/v2**).
    
               Note that diff options passed to the command affect how the
               primary product of **format-patch** is generated, and they are not
               passed to the underlying **range-diff** machinery used to generate
               the cover-letter material (this may change in the future).
    
           --creation-factor=<n>
               Used with _--range-diff_ , tweak the heuristic which matches up
               commits between the previous and current series of patches by
               adjusting the creation/deletion cost fudge factor. See
               git-range-diff(1)) for details.
    
       **SEND OPTIONS**
           -b <branch>, --branch=<branch>
               Use <branch> instead of current branch
    
           -a, --all
               Send all applied patches
    
           -G <option>, --git-opt=<option>
               Pass additional <option> to **git send-email**.
    
               See the git-send-email(1) man page. This option may be
               specified multiple times.
    
           --from=<address>
               Specify the sender of the emails. If not specified on the
               command line, the value of the sendemail.from configuration
               option is used. If neither the command-line option nor
               sendemail.from are set, then the user will be prompted for the
               value. The default for the prompt will be the value of
               GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not set,
               as returned by **git var -l**.
    
           --to=<address>
               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, and _--to-cmd_ is
               not specified, this will be prompted for.
    
               This option may be specified multiple times.
    
           --cc=<address>
               Specify a starting "Cc:" value for each email. Default is the
               value of sendemail.cc.
    
               This option may be specified multiple times.
    
           --bcc=<address>
               Specify a starting "Bcc:" value for each email. Default is the
               value of sendemail.bcc.
    
               This option may be specified multiple times.
    
           --subject=<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.
    
           --reply-to=<address>
               Specify the address where replies from recipients should go
               to. Use this if replies to messages should go to another
               address than what is specified with the _--from_ parameter.
    
           --in-reply-to=<id>
               Make the first mail (or all the mails with _--no-thread_) appear
               as a reply to the given Message-ID, which avoids breaking
               threads to provide a new patch series. The second and
               subsequent emails will be sent as replies according to the
               _--[no-]chain-reply-to_ setting.
    
               So for example when _--thread_ and _--no-chain-reply-to_ are
               specified, the second and subsequent patches will be replies
               to the first one like in the illustration below where [PATCH
               v2 0/3] is in reply to [PATCH 0/2]:
    
                   [PATCH 0/2] Here is what I did...
                     [PATCH 1/2] Clean up and tests
                     [PATCH 2/2] Implementation
                     [PATCH v2 0/3] Here is a reroll
                       [PATCH v2 1/3] Clean up
                       [PATCH v2 2/3] New tests
                       [PATCH v2 3/3] Implementation
    
               Only necessary if _--compose_ is also set. If _--compose_ is not
               set, this will be prompted for.
    
           --compose
               Invoke a text editor (see GIT_EDITOR in git-var(1)) to edit an
               introductory message for the patch series.
    
               When _--compose_ is used, git send-email will use the From,
               Subject, and In-Reply-To headers specified in the message. If
               the body of the message (what you type after the headers and a
               blank line) only contains blank (or Git: prefixed) lines, the
               summary will not be sent, but From, Subject, and In-Reply-To
               headers will be used unless they are removed.
    
               Missing From or In-Reply-To headers will be prompted for.
    
               See the CONFIGURATION section of git-send-email(1) for
               sendemail.multiEdit.
    
           --annotate
               Review and edit each patch you are about to send. Default is
               the value of sendemail.annotate.
    
           --identity=<id>
               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.
    
           --no-thread
               If threading is enabled, the In-Reply-To and References
               headers will be added to each email sent. Whether each mail
               refers to the previous email (deep threading per **git**
               **format-patch** wording) or to the first email (shallow
               threading) is governed by _--[no-]chain-reply-to_.
    
               If disabled with _--no-thread_ , those headers will not be added
               (unless specified with _--in-reply-to_). Default is the value of
               the sendemail.thread configuration value; if that is
               unspecified, default to _--thread_.
    
               It is up to the user to ensure that no In-Reply-To header
               already exists when **git send-email** is asked to add it
               (especially note that **git format-patch** can be configured to do
               the threading itself). Failure to do so may not produce the
               expected result in the recipient’s MUA.
    
           --confirm=<mode>
               Confirm just before sending.
    
               Default is the value of sendemail.confirm configuration value;
               if that is unspecified, default to auto unless any of the
               suppress options have been specified, in which case default to
               compose.
    
               Confirmation modes:
    
               •   _always_ will always confirm before sending
    
               •   _never_ will never confirm before sending
    
               •   _cc_ will confirm before sending when send-email has
                   automatically added addresses from the patch to the Cc
                   list
    
               •   _compose_ will confirm before sending the first message when
                   using --compose
    
               •   _auto_ is equivalent to cc + compose
    
           --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.
    
           --dump-aliases
               Dump configured aliases and exit
    
           -n, --numbered
               Use [PATCH n/m] even with a single patch
    
           -N, --no-numbered
               Use [PATCH] even with multiple patches
    
           --start-number=<n>
               Start numbering at <n> instead of 1
    
           -v <n>, --reroll-count=<n>
               Mark the series as the <n>th reroll
    
           --rfc
               Use [RFC PATCH] instead of [PATCH]
    
           --subject-prefix=<prefix>
               Use [<prefix>] instead of [PATCH]
    


## STGIT



           Part of the StGit suite - see stg(1)
    


* * *