git send-email | Send a patch by email in Git
Table of Contents
- Use Git format-patch before emailing
- How do I email from Git?
- How to use git send-email?
- Configure git send email
- git send-email examples
- Git send multiple patches to one recipient
- Git mail patch to multiple recipients (CC or BCC)
- Next steps
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?
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
smtpEncryption = tls
smtpServer = smtp.gmail.com
smtpUser = firstname.lastname@example.org
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 --email@example.com 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
(mbox) Adding cc: Jacob Stopak <firstname.lastname@example.org> from line 'From: Jacob Stopak <email@example.com>'
Subject: [PATCH] Add readme
Date: Mon, 31 Oct 2022 20:56:08 -0700
X-Mailer: git-send-email 2.38.0
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
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:
TO:fields: Verify these are correct before sending.
SUBJECTfield: Verify that the subject is correct before sending.
Message-Idheader: 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 --firstname.lastname@example.org 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 --email@example.com 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 --firstname.lastname@example.org --email@example.com --firstname.lastname@example.org 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.
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.
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 email@example.com with any questions or comments.
- Official Git mailing list - https://lore.kernel.org/git/
- Git-scm: git send-email docs - https://git-scm.com/docs/git-send-email
Recommended product: Decoding Git Guidebook for Developers