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!
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.)
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 = email@example.com [sendemail] smtpserver = mail.example.org smtpuser = firstname.lastname@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 "email@example.com" 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
more info on git config options, see
git help config.
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
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.
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.
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.
In order to integrate the changes, you need to apply the patch. The tool for
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
commit 36e61708da5f61231d230c77e8580e20219ffdf7 Author: Peter Sanchez <firstname.lastname@example.org> Date: 2022-07-25T12:07:27-06:00 Adding Drew Devault link to contributing doc