git-send-email

Send Git patches as emails

TLDR

Send the last commit in the current branch interactively

$ git send-email -1

Send a given commit

$ git send-email -1 [commit]

Send multiple (e.g. 10) commits in the current branch

$ git send-email [-10]

Send an introductory email message for the patch series

$ git send-email -[number_of_commits] --compose

Review and edit the email message for each patch you're about to send

$ git send-email -[number_of_commits] --annotate

SYNOPSIS

git send-email [options] (revision-range | mbox)

PARAMETERS

--to=

Specify the primary recipient(s) for the emails.

--cc=

Specify Carbon Copy (CC) recipient(s) for the emails.

--from=

    Specify the sender's email address.

--smtp-server=
    Specify the SMTP server hostname to use for sending emails.

--smtp-port=
    Specify the port number for the SMTP server.

--smtp-user=
    Specify the username for SMTP authentication.

--smtp-pass=
    Specify the password for SMTP authentication. Caution: storing passwords directly in commands or history is not recommended.

--smtp-encryption=
    Specify the encryption type (e.g., ssl, tls, starttls) for SMTP communication.

--dry-run
    Don't send emails; instead, print what would be sent to standard output. Useful for testing.

--compose
    Open an editor to compose/edit the cover letter and/or message body before sending.

--cover-letter
    Generate and include a cover letter email before the patch series, providing an overall description.

--in-reply-to=
    Make the first email in the series a reply to the given Message-ID.

--chain-reply-to
    Make each subsequent patch email a reply to the previous patch email, creating a chain of replies.

--signed-off-by
    Automatically add a 'Signed-off-by:' line to the email body if missing from the commit message.

revision-range
    The range of commits to send as patches (e.g., HEAD~3..HEAD, v1.0..master).

mbox
    Path to a mailbox file containing patches to send, typically generated by git format-patch.

DESCRIPTION

git-send-email is a Git porcelain command designed to send a series of commits (patches) from a Git repository as emails. It is a fundamental tool for developers contributing to projects that utilize a patch-based workflow, most notably the Linux kernel development model.

The command efficiently formats your commits into standard email messages, handling various aspects like subject lines (with patch numbers), body content, and diffs. It can automatically generate a cover letter for a series of patches and manage threading for better email client readability.

It supports direct SMTP communication, allowing users to specify server details, authentication credentials, and encryption methods. This makes it a powerful and flexible solution for submitting code contributions directly from your local Git repository without relying on web-based interfaces. Its deep integration with Git's commit history ensures that patches are correctly formatted and attributed.

CAVEATS

Initial setup can be complex due to various SMTP and authentication configurations.
Sensitive information like SMTP passwords can be exposed if not handled carefully (e.g., in command history).
Email client compatibility for threaded messages and patch application can vary.
Relies on a correctly configured Git environment and system mail settings.

CONFIGURATION

Most options for git-send-email, especially SMTP server details and common recipients, can be persistently configured using git config. For example, git config --global sendemail.smtpserver smtp.example.com allows you to avoid typing these options for every invocation.

INTERACTIVE MODE

By default, git-send-email often operates in an interactive mode, prompting the user for confirmation before sending each email or the entire series. This provides an opportunity to review the formatted emails and ensure correctness before dispatch.

COVER LETTER & ANNOTATION

The command provides robust support for generating a cover letter, which serves as an introduction to a series of patches. The --compose and --annotate options allow for in-depth editing and adding extra notes or explanations directly within the cover letter, crucial for large contributions.

HISTORY

git-send-email is a core part of Git, developed to facilitate the traditional patch-based contribution model prevalent in many open-source projects, particularly the Linux kernel. Its design predates the widespread adoption of web-based pull request systems and remains essential for workflows that prioritize email-based code review and submission.