Using Git Send-Email
— 1194 words — 6 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.
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:
or configure your local SMTP client, for example msmtp:
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.
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.
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.
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.
With --annotate you can annotate the patch before sending the email.
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
+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.
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.
You can also send more than one commit (HEAD^). In general, take a
look at the git revision selection.
# send the last 3 commits
# send all commits from the one specified to HEAD
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.
With --dry-run you can test annotating patches and you can see the
email with all the headers how it would have been sent.
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-emailbut, of course, git supports many other features, one of them isgit rebase. And recently, Julia Evans wrote a post about pitfalls when using it.
Articles from blogs I follow around the net
Status update, November 2024
Hi all! This month I’ve spent a lot of time triaging Sway and wlroots issues following the Sway 1.10 release. There are a few regressions, some of which are already fixed (thanks to all contributors for sending patches!). Kenny has added support for software-…
via emersion November 22, 2024Dismissed!
Dismissing gives me a quick little lift. “That guy is an idiot!” “That place sucks!” There. Now I feel superior. Now I don’t have to think about it. I don’t even need first-hand experience. I can just echo any complaint I’ve heard. I’ve done this with restaurants…
via Derek Sivers blog November 18, 2024Generated by openring