stg-email(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | STGIT | COLOPHON

STG-EMAIL(1)                  StGit Manual                  STG-EMAIL(1)

NAME         top

       stg-email - Format and send patches as email

SYNOPSIS         top

       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         top

       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         top

       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         top

       Part of the StGit suite - see stg(1)

COLOPHON         top

       This page is part of the stgit (Stacked Git) project.
       Information about the project can be found at 
       ⟨http://www.procode.org/stgit/⟩.  If you have a bug report for
       this manual page, see ⟨http://www.procode.org/stgit/⟩.  This page
       was obtained from the project's upstream Git repository
       ⟨https://github.com/stacked-git/stgit.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-05-22.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

StGit 2.4.7                    06/14/2024                   STG-EMAIL(1)

Pages that refer to this page: stg(1)