Note: This document was taken from the sourcehut documentation. It's been adapted to fit our setup where appropriate.

This horrible wall of text has been replaced with a much better interactive tutorial on using git send-email to send patches by email. Check it out here!

https://git-send-email.io

To get setup quickly, read on (you should still refer back to the tutorial above! It's truly amazing and also a very fast read.)

#For contributors

You need to make sure that your git install is configured to be able to send email. To do this, you should edit your git config file, typically ~/.git/config, to contain something like the following:

[user]
    name = Your Name
    email = you@example.org

[sendemail]
    smtpserver = mail.example.org
    smtpuser = you@example.org
    smtpencryption = tls
    smtpserverport = 587

You can also set them from the command line. However this is usually more work to do it all at once than simply editing your config file. Still, if you want to do it this way, you can do:

git config --global user.email "you@example.org"
git config --global user.name "Your Name"
git config --global sendemail.smtpserver "mail.example.org"
...

If you don't set your password here, you will be prompted for it when submitting a patch. If you wish to set it, the setting name is smtppass. For more info on git config options, see git help config.

#Submitting patches

Once you've got some commits ready, you can submit them to the configured mailing list. You simply run the following:

git send-email HEAD^

The list will evaluate and accept it or provide feedback. If you need to make a change do so and amend your last commit with git commit --amend. Then you can resubmit version 2 of your patch.

git send-email --annotate -v2 HEAD^

You can iterate each version of your patch the same way. Use -v3, -v4, etc. You probably noticed the --annotate flag, this lets you add some extra information about the patch without it being added to the commit history.

Please see the tutorial above for more in-depth info on how this works.

#For maintainers

#Tell people how to contribute

The first thing you need to do is help potential contributors figure out how to contact you. The easiest way is to do nothing - git records your email with every commit, so someone with a copy of your git repository can figure out how to contact you. You'll probably want to make it a bit easier on them, though.

We recommend setting up a mailing list on lists.code.netlandish.com for this purpose. Once you do, you will get an email address for contributors to submit patches to. Write this into your docs! You will probably also want to link to the archives so that potential contributors can read other people's work to get a feel for your submission process.

#Reviewing patches

When a patch comes in, you should review it carefully. Read the code, apply the patch locally and make sure it compiles, test the changes, and so on. During this process you'll probably come up with feedback on the patch. Pull open that email client and compose a reply to the patch author. When your client composes the reply, don't be afraid to slice and dice the email you're replying to - trim out the fat and only include specific lines that you want to comment on.

If you only have small comments here and there, feel free to make the changes yourself, again utilizing git commit --amend and git rebase to your heart's content. You may be wise to point out these small errors when you thank the submitter for their patch, however, if you don't want to see the same errors in future patches.

#Applying patches

In order to integrate the changes, you need to apply the patch. The tool for this is git am. The difficult part here is going to be obtaining a copy of the email to provide to git am. Some clients like mutt make this easy (in mutt, you can use the | key to pipe an email directly to git am), or tools like offlineimap can help (or a combination of the two!). Most popular end-user clients do not provide this option. If you're in this boat, the easiest way to get a raw email is to use the "raw" link on lists.code.netlandish.com, which is hidden away under the "details" button.

If you copy the link to the raw email from lists.code.netlandish.com, the command might look like this:

curl -s https://lists.code.netlandish.com/... | git am

You can also just run git am alone and paste the patch into it, followed by Ctrl+D. You can then make these commits available upstream by using git push normally. Don't forget to send the contributor a thank you email!