STG-EMAIL(1)

📦
version 2.7.0 · 8 versions
, in opensuse-leap 16.0

💌 STG-EMAIL(1) 💌

StGit Manual — okay bestie, buckle up: this is the stg-email page, and we are gonna make patch emails make sense. ✨

🌸 NAME 🌸

stg-email - format and send patches as email. No cap, that’s the whole gig. 💅

📬 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. That’s the vibe. 🎀

The classic workflow is: first generate email files for each patch, plus an optional cover letter, using stg email format. Then, after checking the email files’ contents, send 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. Lowkey efficient, fr fr.

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. Iconic delegation behavior. 💫

🧚 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. Cute, organized, slay. 💌

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. Contiguous, bestie — no little gaps in the lineup. 🫶

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. Trust: the directory route is the main character move. 👑

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. Either way, the address situation can be handled here or later. 💅

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. Iykyk. ✨

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. One directory, all the emails — highkey satisfying. 🗂️💖

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. So if you forgot something, the prompt has your back. 🙈

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. Set those SMTP details once, thank yourself forever. 💅

🎀 FORMAT OPTIONS 🎀

  • -b <branch>, --branch=<branch> — use <branch> instead of the current branch. Branch switch-up, but make it patch-email official. 🌿
  • -a, --all — format all applied patches. Every applied patch gets the email glow-up. ✨
  • -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. You can stack these like accessories. 💅
  • -o <dir>, --output-directory=<dir> — use <dir> to store the output files instead of the current working directory. Put the email files somewhere cute and organized. 🎀
  • --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. Cover letter era. 👑
  • -n, --numbered — use [PATCH n/m] even with a single patch. Numbering when you don’t technically need numbering? Bold. 🔥
  • -N, --no-numbered — use [PATCH] even with multiple patches. No numbers, just vibes. 🦋
  • --start-number=<n> — start numbering at <n> instead of 1. Custom starting point, because why not. ⭐
  • -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. Messy version math? It’s giving “technically allowed, slightly chaotic.” 💀
  • --rfc — alias for --subject-prefix="RFC PATCH". RFC means "Request For Comments"; use this when sending an experimental patch for discussion rather than application. Discussion mode: activated. 🗣️✨
  • --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. Custom label, custom little crown. 👑
  • --quiet — do not print the names of the generated files. Shhh. 🤫
  • -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. Sign your name, bestie. ✍️
  • --numbered-files — output file names will be a simple number sequence without the default first line of the commit appended. Just numbers. Clean, minimal, suspiciously chill. 🔢
  • --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. Suffix customization is real. 🎀
  • -k, --keep-subject — do not strip/add [PATCH] from the first line of the commit log message. Keep the subject exactly as it is. 🫶
  • --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. Careful, bestie: not properly applicable — but valid for review. 👀
  • --zero-commit — output an all-zero hash in each patch’s From header instead of the hash of the commit. Zero hash, zero drama. ⭐
  • --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). More recipients, more To: energy. 💌
  • --no-to — discard all To: addresses added so far from config or command line. Bye-bye, To: list. 🫡
  • --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). Cc: the whole group chat. 👯
  • --no-cc — discard all Cc: addresses added so far from config or command line. Clear the Cc: bench. 🧹
  • --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. Thread continuity, we love to see it. 🧵
  • --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". Custom headers? We stan. 🎀
  • --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. Attachment behavior, very official. 📎
  • --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. Same structure, inline disposition. 💅
  • --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. Threading lore drop, bestie. 🧵✨
  • --no-thread — disable message threading. No thread, no reply chain. Simple. 🦋
  • --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. Signature moment. ✨
  • --no-signature — do not add a signature to each email. No signature, no extra text. 🫶
  • --signature-file=<file> — like --signature except the signature is read from a file. Signature, but file-sourced. 📄
  • --base=<committish> — see the BASE TREE INFORMATION section of git-format-patch(1). Base tree info is over there, bestie. 🌳
  • --progress — show progress reports on stderr as patches are generated. Progress bar energy. 📈
  • --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). Reviewer aid, but make it interdiff. 🔍
  • --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). Range-diff into the cover letter? Reviewer bestie behavior. 👑
✨ Note: diff options you pass to the command affect how the primary product of format-patch is generated — and they are not passed along to the underlying range-diff machinery that builds the cover-letter material. (This may change in the future. 👀)
  • --creation-factor=<n> — used together with --range-diff, this tweaks the heuristic that matches up commits between the previous series of patches and the current one, by adjusting the creation/deletion cost fudge factor. Peep git-range-diff(1)) for the deets.

🦋 SEND OPTIONS 🦋

  • -b <branch>, --branch=<branch> — use <branch> instead of the current branch, bestie.
  • -a, --all — send all applied patches. all of them. every last one. 💅
  • -G <option>, --git-opt=<option> — pass an additional <option> straight through to git send-email. Check the git-send-email(1) man page for what's on offer. You can specify this one multiple times — stack 'em up. 🎀
  • --from=<address> — sets the sender of the emails. If you don't say it on the command line, the value of the sendemail.from configuration option is used instead. And if neither the command-line option nor sendemail.from is set? Then you get prompted for it. The default for that prompt is the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that one isn't set, as returned by git var -l. ✨
  • --to=<address> — the primary recipient of the emails being generated. Generally this is the upstream maintainer of the project involved. Default is the value of the sendemail.to configuration value; if that's unspecified, and --to-cmd isn't specified either, you'll be prompted for it. This option may be specified multiple times. 🫶
  • --cc=<address> — gives each email a starting "Cc:" value. Default is the value of sendemail.cc. May be specified multiple times. 💖
  • --bcc=<address> — gives each email a starting "Bcc:" value. Default is the value of sendemail.bcc. May be specified multiple times. 🙈
  • --subject=<subject> — sets the initial subject of the email thread. Only necessary if --compose is also set. If --compose isn't set, you'll be prompted for it.
  • --reply-to=<address> — the address where replies from recipients should go to. Use this when replies to messages should land somewhere other than what's specified with the --from parameter. 🎯
  • --in-reply-to=<id> — makes the first mail (or all the mails with --no-thread) show up as a reply to the given Message-ID, which avoids breaking threads when you're providing a new patch series. The second and subsequent emails get 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 isn't set, you'll be prompted for it. 🧵

  • --compose — invokes a text editor (see GIT_EDITOR in git-var(1)) so you can 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 (that's what you type after the headers and a blank line) only contains blank lines — or lines prefixed with Git: — then the summary will not be sent, but the From, Subject, and In-Reply-To headers will still be used, unless you remove them.

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're about to send. Default is the value of sendemail.annotate. ✍️
  • --identity=<id> — a configuration identity. When given, it 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 get 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's unspecified, it defaults to --thread.

⚠️ It is up to you, the user, to make sure that no In-Reply-To header already exists when git send-email is asked to add one (especially note that git format-patch can be configured to do the threading itself). Failing to do this may not produce the expected result in the recipient's MUA. fr fr, be careful. 💀
  • --confirm=<mode> — confirm right before sending. Default is the value of the sendemail.confirm configuration value; if that's unspecified, it defaults to auto — unless any of the suppress options have been specified, in which case it defaults to compose.

Confirmation modes, bestie:

  • 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 — equivalent to cc + compose
  • --quiet — makes git-send-email less verbose. One line per email should be all that's output. shhh. 🤫
  • --dry-run — does everything except actually send the emails. practice mode. 💅
  • --dump-aliases — dumps configured aliases and exits.
  • -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> — marks 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). 🫶

okay that's literally the whole page, bestie, you ate that. this icon was brought to you by StGit 2.7.0, dated 10/17/2026, and it's STG-EMAIL(1) — go forth and send some patches, mwah 💋🌸

📦 where this page comes from