Using Git Send-Email

— 1194 words — 6 min

#email 

Table of Contents
  1. Why?
  2. Package Requirements
  3. Send a Patch
  4. Tips and Tricks
  5. Other Resources

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:

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🔗


Articles from blogs I follow around the net

Status update, May 2024

Hi! Sadly, I need to start this status update with bad news: SourceHut has decided to terminate my contract. At this time, I’m still in the process of figuring out what I’ll do next. I’ve marked some SourceHut-specific projects as unmaintained, such as sr.ht-…

via emersion May 21, 2024

How and why to make a /now page on your site

Background I used to wonder what my friend Benny Lewis was doing. He has a website and social media accounts, but neither gave an overview of what he’s doing now. Then I realized some people might wonder the same about me. So in 2015, I made a /now page on my…

via Derek Sivers blog May 18, 2024

Email DNS Records Cheatsheet

A quick summary of the SMTP related DNS records together with brief examples.

via Signs of Triviality April 12, 2024

Generated by openring