Using Git Send-Email

November 12, 2023 — 940 words — 5 min

Table of Contents

Why?

With big collaborating platforms such as GitHub or GitLab one might argue that that sending patches via email is an antique thing of the past. I don’t think so. And it’s not. Take a look at one of the largest open source projects, the Linux kernel, and you’ll see that they rely heavily and exclusively on mailing lists. OpenBSD development happens on mailing lists, too. Sourcehut is a development platform similar to GitHub or GitLab but with some distinctive differences:

at its core it’s powered by git send-email
no account needed to contribute to projects. On GitHub and others you have to have an account before you can start contributing. On Sourcehut you can just send an email to the projects mailing list.
no tracking and no JavaScript needed. Ugh, finally. Yes.
Private repositories, mercurial support, continuous integration, Sourcehut pages (like “(GitHub|GitLab|…) Pages”), review patches on the web, issue tracking, IRC, and much more. Take a look at their homepage.

The initiator of Sourcehut is Drew DeVault and this is not his only project by far. He also started Sway (SirCmpwn’s Wayland compositor) and as far as I know was an important force behind Wayland adoption. Take a look Drew DeVault’s blog.

Another great project by Drew or the team behind Sourcehut is this tutorial about git send-email. After all this command is essential to collaborate with others on Sourcehut. This quick introduction teaches you everything you need to know to get started with git send-email. Below are my notes and some tips and the end.

Package Requirements

Install the following dependencies on Arch Linux to use git send-email.

sudo pacman -Syu --needed git perl-authen-sasl perl-io-socket-ssl

In your global git configuration (git config --global --edit) you can now configure the settings to connect to the SMTP server of your mail account like this:

[sendemail]
    smtpserver = mail.example.org
    smtpuser = you@example.org
    smtpencryption = ssl
    smtpserverport = 465

or configure your local SMTP client, for example msmtp:

[sendemail]
    smtpserver = /usr/bin/msmtp
    smtpserveroption = -a
    smtpserveroption = mailprofile

The smtpserveroption lines are optional. With them you can specify a specific msmtp profile, otherwise the default is used. I use the option envelopeSender = auto. This tells git send-email to use the email of the commit author and pass it to msmtp with the -f flag that subsequently selects the first profile that matches the from: <email> field in the msmtp configuration file. This makes it possible to maintain one git configuration but use multiple git profiles with different email addresses (work and private for example). The following configuration will do.

[sendemail]
    smtpserver = /usr/bin/msmtp
    envelopeSender = auto

Send a Patch

Let’s send a patch. Go to a local sample repository (you can use the one from the tutorial linked above), make a commit, and send the changes.

git clone https://git.sr.ht/~sircmpwn/email-test-drive
cd email-test-drive/
git add <your changes>
git commit -m 'new stuff'
git send-email --to="~sircmpwn/email-test-drive@lists.sr.ht" HEAD^

Instead of specifying the mailing list as recipient you could also send to email to yourself to verify that everything works. Check out the archive of the tutorial repository to see who did the tutorial and how the mails look like.

If you want to send another version of my patch you can specify -v2 for a second version.

git send-email -v2 --to="~sircmpwn/email-test-drive@lists.sr.ht" HEAD^

You can also add the mailing list address to the git configuration of that git repository (not in the global git configuration). Then there is no need to specify it for every patch with the --to flag.

git config sendemail.to "~sircmpwn/email-test-drive@lists.sr.ht"

With --annotate you can annotate the patch before sending the email.

git send-email --annotate -v3 HEAD^

When you annotate the patch, you can give maintainers more context about the patch that will not end up in the commit message itself. Consider the following content in your editor:

From: ...
Date: ...
Subject: [PATCH] add feature xyz

Everything you write above the three dashes starting the diff will be
part of the commit message; basically the normal email body.

---
In here you can give the maintainers of the project more context about
the patch. Nothing in here will be part of the final git commit log.

 max | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 max

diff --git a/max b/max
new file mode 100644
index 0000000..66cb3d4
--- /dev/null
+++ b/max
@@ -0,0 +1 @@
+I have successfully used git send-email!
--
2.42.0

Tips and Tricks

Take a look and the tips and tricks section of the tutorial I linked at the beginning. Below are some that I find most useful.

Adjust the prefix, for example for multiple projects on the same mailing list.

git config format.subjectPrefix "PATCH subproject"

Always use --annotate (set in the global git configuration) and sign off commits (set in the project’s git configuration). Depending on the project you might have to sign off your work, for example take a look at the guidelines to submit patches to the Linux project.

git config --global sendemail.annotate yes
git config format.signOff yes

You can also send more than one commit (HEAD^). In general, take a look at the git revision selection.

# send the last 3 commits
git send-email HEAD~3

# send all commits from the one specified to HEAD
git send-email c2e0aa0a62

When sending multiple patches you might want to explain a bit further what this patch series does and how. In this case you can send a cover letter and subsequently the patches belonging to it in the same email thread.

git send-email --cover-letter --annotate HEAD~5

With --dry-run you can test annotating patches and you can see the email with all the headers how it would have been sent.

git send-email --annotate --dry-run HEAD^

That’s it. If you have other tips or useful commands, get in touch and I’ll add them here. Now you can start sending patches to your favorite projects! 🙂

Other Resources

the official Git documentation
the man page of git-send-email(1) and git-format-patch(1)
this post is only about git send-email but, of course, git supports many other features, one of them is git rebase. And recently, Julia Evans wrote a post about pitfalls when using it.

Articles from blogs I follow around the net

India tech friends: I just bought my ticket to IndiaFOSS in BLR Sept 26-27: https://fossunited.org/indiafoss/2026 Want to meet? Email me: https://sive.rs/contact

via Derek Sivers June 12, 2026

AI errno(2) values

errno(2) values for the AI age

via Signs of Triviality May 19, 2026

Status update, February 2026

Hi all! Lars has contributed an implementation independent test suite for the scfg configuration file format. This is quite nice for implementors, they get a base test suite for free. I’ve added support for it for libscfg, the C implementation. I’ve spent some…

via emersion February 22, 2026

Generated by openring