For the hackers who study the blade, the preferred method of collaborating is with email patches. Both git and email are decentralized. Git was initially designed around the idea of emailing patches. Then, the GitHub empire introduced the world to PR’s. Now, it dominates the way developers think about collaborating. The hacker art of email patches has nearly been wiped out. This blog post is meant to help other developers revive the lost art. More seriously, this is a workflow I have figured out while using SourceHut. In my experience, most blog posts focus on sending git patches while leaving receiving patches an exercise for the reader. In this post, I will dive into how you can use himalaya, the email client, to quickly receive patches and add them to your git log like a true hacker.

Sending Patches

I learned to use git with email by going through this great tutorial. It will walk you through configuring your local git config for sending emails. However, there are a few pieces that are missing that this post will try to fill in for you. If you have an email service like Migadu or Gmail, I recommend following the tutorial to set up your git config and the git send-email plugin. If your email service does not allow you to access the SMTP ports, I recommend sending the patches as attachments.

The problem with the tutorial I linked above is it relies too much on the basic command:

git send-email HEAD^1

Unfortunately, this doesn’t make setting the subject or content type easy. So the email, when sent, comes out as an octet-stream which is considered noob.

Here is how to send patches like a pro hacker.

git format-patch \
    --subject-prefix="PATCH example" \
    --add-header="Content-Type: text/plain; charset=\"utf-8\"" \
    HEAD^1

This will create a .patch file in your local directory.

Then run:

git send-email --to=joe@example.com *.patch

This will send the generated patch file as you want it, with the proper content type header. The same command will work if you happen to generate multiple patch files.

Example Workflow

This is a workflow for sending your local commits as a patch file.

After committing your changes to your local repo you will want to generate a patch file for that commit. This can be accomplished with this command:

git format-patch \
    --subject-prefix="PATCH example" \
    --add-header="Content-Type: text/plain; charset=\"utf-8\"" \
    HEAD^1

I’ll break down the parameters:

1. subject-prefix: This is how to specify the prefix of the email subject. By convention, sending patches includes PATCH at the beginning. It is also best practice to include the project name. In this example, the project name is “example.”

2. add-header: This will send the Content-Type of the patch as plain text. This helps other email clients render the patch correctly.

3. HEAD^1: This is standard git syntax for the most recent commit. Since it is easier to send one commit, I recommend looking into git rebase -i so you can learn how to squash commits.

This will make a patch file something like 0001-Whatever-my-commit-was.patch.

git send-email --to="joe@example.com" *.patch

You can optionally specify the exact patch file. Using a wildcard makes it easy.

Sending Patch as Attachment

The benefit of not sending it as an attachment is that it embeds the PATCH directly into the email, so you can read the diff in your email client. This is the way. However, sometimes, you might find yourself with a not-so-hacker email service. When you are unable to configure git send-email, you can send the patch as an attachment. The recipient will download the attachment and apply the patch.

Replying to messages

So you have sent your patch to the hacker mailing list. Then, the code owner replies to your patch and asks you to make changes. Now, you could send another patch to the mailing list like you did the first time. However, that is not the hacker way.

To acheive hacker status. You’ll want to use the --in-reply-to=*message id*.

git send-email --to="joe@example.com" --in-reply-to=*message-id* *.patch

The message id will be the email to which you want to reply. This will allow the emails to be rendered in a mail thread. Now that is hacker.

Receiving Patches

You have your own hacker mailing list where you point your fellow hackers to send you patches. How do you actually accept the patches into your code? Fear not; I will show you how to use the himalaya email client to receive and apply patches to your project. The benefit is that we can pipe the email body into a local patch file and then accept that patch file into your repo.

It is a good idea to add *.patch into your .gitignore file.

So once you have himalaya installed here is the example workflow:

himalaya message read *number* > example.patch

git apply --check example.patch

git am -i example.patch

Select edit if you need to edit the commit message.

Now when you run git log you should see the commit added to your log.

Note that git apply --check is optional. It is a good way to tell if the patch is in the proper format to be applied as a commit.

Conclusion

To practice, I would advise going through the above by sending patches and replying to your own email to get a feel for how it works. Sending and receiving patches can feel a bit intimidating, but hopefully, after this, you can get going.