If you are a newcomer in the kernel or git development community (or others), you may find it odd that contributions aren’t sent via fancy user interfaces such as the ones provided by Github (Pull Requests) and Gitlab (Merge Request). All patches, as they are called, are sent by email to the respective mailing list.
Ok, so you got your first commit and you already figured out whom to send it to,
now how do you send it? Some email clients insert html code and convert tabs to
whitespaces, to make the text prettier. And that, as a result, messes up with
the code you are trying to send :( So some good options are:
neomutt (a terminal based email client) or
git send-email! Yes, git can send
your patches! In this tutorial, we are going to see a little step-by-step guide
on how to set up and use
git send-email to send a single patch and patchsets.
Most of what I’ll show comes from here. I encourage you to take a look there too. Also, if you are, indeed, starting to make patches for the kernel, you may find the patch philosophy, the first kernel patch post and how to write good commit messages very useful.
Without further ado, let’s get to it!
Note: This section is for reference only. There are several nuances of setting up and using git-send-email. So read the tutorial completely.
## Configure with: git config --global user.name "<your name>" git config --global user.email "<your email>" git config --global sendemail.smtpencryption tls git config --global sendemail.smtpserver "<your_email_smtp_server_address>" git config --global sendemail.smtpuser "<your_email>" git config --global sendemail.smtpserverport "<your_email_smtp_server_port>" ## Send patches with: git send-email --annotate --to="firstname.lastname@example.org" --cc="email@example.com" -1 # for a single patch git send-email --annotate --cover-letter --thread --no-chain-reply-to --to="firstname.lastname@example.org" --cc="email@example.com" -3 # for a patchset
Setting it up
You probably already have git installed (if not, that’s the first thing), but
depending on your distro, you may need some additional packages. In ubuntu,
for example, you need
git-email, in Manjaro you need
perl-net-ssleay and in Arch you need
2) If you haven’t told git your name and email yet, do that:
git config --global user.name "<your name>" git config --global user.email "<your email>"
Note: use you full name (or at least partial) here. For example, “Johnathan F. Hanks” and “Michael Stuart” are ok. But “Johnathan” and “Stuart” are not.
3) Configure the sending email SMTP server:
For this section, you may have to check some values depending on your email
service. For gmail, for example, the SMTP server address is
and the port is
587. Also, note that, for gmail, you will have to
allow less secure apps.
You can do that here. Another
option is to
sign in using app passwords,
but I haven’t tried that.
git config --global sendemail.smtpencryption tls git config --global sendemail.smtpserver "<your_email_smtp_server_address>" git config --global sendemail.smtpuser "<your_email>" git config --global sendemail.smtpserverport "<your_email_smtp_server_port>"
You can also set your email password with:
git config --global sendemail.smtppass "<your password>"
But that will store your password as plain text at
~/.gitconfig, so I don’t
recommend it. If you don’t set your password, you will be asked for it when you
try to send an email.
4) [Optional] Supress yourself in cc:
By default, git will add the author of the commit(s) to cc. This means that when you are the author, you will send the email to yourself too. To suppress this behavior (of sending to yourself), run:
git config --global sendemail.suppresscc self
How to use it
You can send patches by different means. You can use
git format-patch to
write the patch to a file and then send this file using
Another option is to let
git send-email deal with both patch formatting and
sending (which I personally prefer).
1) Basic usage:
If you want to send your last
N patches run:
git send-email -N # Replace N with the number of patches
If you want to send the commits from hash
d2901 to hash
git send-email d2901..89e73
You can specify who to send the emails to with
--cc, but if you
don’t use them, git will prompt you the recipient.
2) A more complete/real usage:
There is a lot of other useful options, and you can check them all with a
man git-send-email, but what I usually use, for a single patch, is this:
git send-email --annotate --to="firstname.lastname@example.org" --cc="email@example.com" -1
And for a patchset (i.e. a series of patches), is something like this:
git send-email --annotate --cover-letter --thread --no-chain-reply-to --to="firstname.lastname@example.org" --cc="email@example.com" -3
The options used are:
--annotate: open the emails in your text editor to be edited/annotated before sending. Even when you won’t make any annotations, this is an excellent option to use so that you can do a final check in the patch before sending.
--cover-letter: make a cover letter, where you can explain the overall modifications your patches make. Useful when you are sending more than one patch.
--thread: send all the emails in the same thread, either making each one a reply to the last one or making all replying to the first one (the cover letter, if you used
--cover-letter). You can specify which behavior you want with the
no-if you want all the emails to reply the first one (the expected behavior when sending emails to linux kernel).
More tips on patch sending
1) Dry-run: A safe way to test send-email
You can use the
--dry-run option to make git-send-email do all the process
but without actually sending the emails. It’s a good option to test everything
before sending. You can see in the command’s output, for example, if all the
people you desired to be at
CC really got there.
2) Prefixing emails’ subjects
When sending a patchset, the subject of each email, which will be each commits’ message title, will already be prefixed with a [PATCH 1/N], [PATCH 2/N] and so on.
When you receive a review for your patch, you’ll probably want to send a new modified version. In this case you can use a
-v3, and so on), in
order to make
git send-email prefix the email subjects with [PATCH v2 X/N].
You can also change the default “PATCH” in the prefix with
3) Annotating the patch
Sometimes you want to add comments to your patch that are not meant to be in
the final patch message. For example, a comment saying “This patch depends on
patch XYZ” or a patch version comment. To do that, you may use the
option, which will open the email in the set editor to be edited before sending.
--annotate option can also be used so that one can do a final check in the
patch and email before sending (which is always very nice :)
Note about patch version comments
Usually, when sending a v2, v3, etc., it’s good to add comments explaining the modifications made, like this:
--- Changes in V3: - Add xpto call Changes in v3: - Removed foo increment - Refactor patch message
--- is called “scissors separator”. Eveything you add below it, until the
beginning of the diff, will be ignored when applying the patch to a git
repository. That’s the place to add any comment.
4) A note about patchsets and cover letter
Patchsets are series of patches sent each one in its own email. It is common to
send an extra mail before the patch mails with a little abstract introducing
them. This email is called cover letter, and usually it usually takes the index
0 in the series. To make a cover letter, just use the
Tip: take a look at mailing list archives to see how contributors usually
write cover letters.
All the following email patches in a patchset should be a reply to the first
email (which usually is the cover letter). To make git do that, you must use the
5) The editor set for git
You can configure which editor git will open when using the
editing a commit message and everything that needs and editor. One way of doing
that is by running:
git config --global core.editor <your_editor>
But git also supports the standardized VISUAL and EDITOR environment variables, so you can run these commands in your bash:
export VISUAL=<your_editor> export EDITOR=<your_editor>
Note: The above command will set the editor for git and other programs that follow these environment variables standards.
comments powered by Disqus