Image of git send-email | Send a patch by email in Git

ADVERTISEMENT

Table of Contents

Introduction

Git is a flexible version control system that offers developers various ways to work as a team. Although most dev teams share their code changes by Git pushing and Git pulling from a centralized repository, some teams choose to share their changes over email right from the command-line.

Most notably, the core Git developers and community maintain an official public Git mailing list for collaboration on Git software itself. The Linux community maintains a similar Linux kernel mailing list archive.

Use Git format-patch before emailing

Before sending code changes via email, the specific changes need to be prepared for email transfer in a way that Git can understand. This is done by creating patches using the git format-patch command.

If you aren't familiar with Git patches, we highly recommend reading our post on how to create a patch in Git before continuing this article on emailing patches.

As a reminder, a Git patch is just a file that stores the changes in a commit - basically the git diff of the commit with its parent - in a text format that can be easily sent via email.

How do I email from Git?

Once you have created your Git patch series (one or more Git patch files), you are ready to send them using the git send-email command.

The git send-email command can be used to send a single patch or multiple patch files from your local machine to a recipient. The main recipient is often a project mailing list, but individual developers who are involved are often CC'd.

You can also always share patches directory with a colleague for review in a less formal setting.

How to use git send-email?

By default, git format-patch creates one or more patch files in the current directory, which often coincides with your project root directory, which is tracked by Git.

Be careful not to accidentally commit your patches. It's usually a good idea to add *.patch into your .gitignore file.

If patches are created in your current directory, you can simply specify them as arguments to git send-email, as we'll see in a minute.

If patches are created in their own directory, which is generally a good idea to keep them separated from your other code files and other patch sets, the entire directory can be specified.

Let's start with a few simple examples.

Configure git send email

Git send-email has a variety of configuration options that you'll need to set in order to relay mail. It is common practice to add these into the logged-in user's git config file, located at ~/.gitconfig:

[sendemail]
	smtpEncryption = tls
	smtpServer = smtp.gmail.com
	smtpUser = yourname@gmail.com
	smtpServerPort = 587

Here is a brief explanation of each of these four properties:

  • smtpEncryption=tls: smtpEncryption tells Git to Transport Layer Security (TLS) to encrypt outgoing mail
  • smtpServer: smtpServer tells Git which email server or service to use for mail relay
  • smtpUser: smtpUser is your source email address for the mail that Git sends
  • smtpServerPort: smtpServerPort is the email service port to use for mail relay

Note that the example above assumes you want to relay your Git emails through your gmail account. If you use a different email service, you'll need to determine the correct values to use. In addition, there are many more Git mail properties to work with.

More details about Git send-email configuration be found on the [git send-email docs].

git send-email examples

The simplest way to use git send-email is to send a single patch to one recipient:

$ git send-email --to=jacob@initialcommit.io 0001-Add-readme.patch

Note that the recipient email address is specified in the --to parameter, and the name of the patch file, in this case 0001-Add-readme.patch is supplied after that.

Once you hit , you'll see output similar to the following in your terminal:

0001-Add-git-branch-subcommand-parser.patch
(mbox) Adding cc: Jacob Stopak <jacob@initialcommit.io> from line 'From: Jacob Stopak <jacob@initialcommit.io>'

From: jacob@initialcommit.io
To: jacob@initialcommit.io
Subject: [PATCH] Add readme
Date: Mon, 31 Oct 2022 20:56:08 -0700
Message-Id: <20221101035608.19161-1-jacob@initialcommit.io>
X-Mailer: git-send-email 2.38.0
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

    The Cc list above has been expanded by additional
    addresses found in the patch commit message. By default
    send-email prompts before sending whenever this occurs.
    This behavior is controlled by the sendemail.confirm
    configuration setting.

    For additional information, run 'git send-email --help'.
    To retain the current behavior, but squelch this message,
    run 'git config --global sendemail.confirm auto'.

Send this email? ([y]es|[n]o|[e]dit|[q]uit|[a]ll):

This output gives you important information about your email, and asks you if you really want to send the email or not.

Important lines to pay attention to are:

  • The FROM: and TO: fields: Verify these are correct before sending.
  • The SUBJECT field: Verify that the subject is correct before sending.
  • The Message-Id header: Used by the recipient mailbox to keep related messages together.

These fields are populated automatically from a combination of the patch file email headers, and the parameters supplied to the git send-email command.

Once everything looks good, you can typer y and hit ENTER to send, or press n followed by ENTER to cancel and return to the command-line.

As the output states, you can suppress some of Git's extra information by tweaking the git config senderemail.confirm:

$ git config --global sendemail.confirm auto

Git send multiple patches to one recipient

To send multiple patches to one recipient just list all patches in the command as follows:

$ git send-email --to=jacob@initialcommit.io 0001-Add-readme.patch 0002-Update-pom.patch 0003-Create-feature.patch

Keep in mind when sending multiple patches, the git send-email output will prompt you to send or cancel each one in a separate email.

If you used the git format-patch -o directory/ option to create your patches in a new empty directory, you can send all patches in that directory like this:

$ git send-email --to=jacob@initialcommit.io directory/*

This will also prompt you to send each patch as a separate email.

Git send-email uses a consistent Message-ID header in your emails so that to recipient mailbox can link together multiple patches that were sent together in this way. You will see this Message-ID header when prompted by git send-email.

Git mail patch to multiple recipients (CC or BCC)

Similar to the git send-mail --to flag, you can use the --cc or --bcc flags to add additional recipients to your Git emails:

$ git send-email --to=jacob@initialcommit.io --cc=jacob@initialcommit.io --bcc=jacob@initialcommit.io 0001-Add-readme.patch

Note that Git will prioritize any command line arguments supplied to git send-email over those on the patch files. Non-conflicting parameters will simply both be applied, for example if there is a CC line in the patch file and the --cc option is used as well.

Summary

In this article, we covered what you need to known about sending email using Git, specifically relaying patches using the git send-email command.

We mentioned why you might want to collaborate via email, showed how to configure your local machine to send mail, and explained how to use the git send-email command to mail one or more patches to other devs on your team.

Next steps

If you're interested in learning more about how Git works under the hood, check out our Decoding Git Guidebook for Developers, which dives into Git's code in an accessible way. We wrote it for curious developers to learn how Git works at the code level. To do this, we documented the first version of Git's code and discuss it in detail.

We hope you enjoyed this post! Feel free to shoot me an email at jacob@initialcommit.io with any questions or comments.

References

  1. Official Git mailing list - https://lore.kernel.org/git/
  2. Git-scm: git send-email docs - https://git-scm.com/docs/git-send-email

Final Notes