The prerequisites for this tutorial is that you have already made some changes to your local kernel tree and that these changes have been committed.
In this tutorial, are described the steps to follow in order to create and send a patch series using git-send-email.
Initially, you need to determine which of your commits want to be sent, so do:
$ git log --pretty=oneline --abbrev-commit
The output, in my case, looks like:
db868ad xhci: remove conversion from generic to pci device in xhci_mem.c c010f0c xhci: remove unnecessary check in xhci_free_stream_info() a166493 xhci: fix SCT_FOR_CTX(p) macro 56e4cd3 xhci: replace USB_MAXINTERFACES with config->desc.bNumInterface ...
Lets assume that I want to send the last 3 commits i.e db868ad, c010f0c and a166493. The first thing I need to do is to create patches for these commits and store them in a local directory e.g. ~/patches/
Patches that can be sent using git-send-email should have been generated with git-format-patch. Patches with other formats may fail to be passed to git-send-email. So to create the patches I do:
$ git format-patch -o ~/patches/ -3 HEAD
HEAD may be omitted since it is implied by default when you do not state the starting commit-id. If you want, for example, to create patches for the last 3 commits starting from commit c010f0c i.e. c010f0c, a166493 and 56e4cd3, you need to alter the above command in the following way:
$ git format-patch -o ~/patches/ -3 c010f0c
If you observe the patches created in ~/patches/, you will notice that the patch subjects got prefixed with [PATCH n/m]. If you intend to send a patch as RFC, you can alter the subject prefixes into [RFC n/m] by doing:
$ git format-patch --subject-prefix="RFC" -o ~/patches/ -3
Now, you have created your patches and you are ready to send them. Note, that in case you do not want to keep a copy of your patches in a local directory, the above steps on patch creation can be omitted and you can use git-send-email to directly create and send patches for your commits. How to do that will be described below.
The next step is to indicate to git-send-email which SMTP server it will use to send your patches and to specify its parameters e.g. encryption protocol, port etc. If you have a gmail account, you can use the following commands. Otherwise, you need to alter them accordingly.
$ git config --global sendemail.smtpuser <your mail> $ git config --global sendemail.smtpserver smtp.googlemail.com $ git config --global sendemail.smtpencryption tls $ git config --global sendemail.smtpserverport 587
You can also configure your password doing:
$ git config --global sendemail.smtppass <your passwd>
However, that is not recommended since your password will be written unencrypted in ~/.gitconfig. This command has been included just for completeness. If smtppass has not been set, you will be prompted for your password every time you send a patchset.
Every time a patch is send, your mail address is CC’ed by default. To prevent git-send-email from sending you back copies of your emails, do:
$ git config --global sendemail.suppresscc self
You can check ~/.gitconfig to see if you have setup correctly git-send-email. Its contents should look similar to the following:
[user] email = email@example.com name = Xenia Ragiadakou [sendemail] smtpuser = firstname.lastname@example.org smtpserver = smtp.googlemail.com smtpencryption = tls smtpserverport = 587 suppresscc = self
Now, before proceeding with git-send-email options, try to send the patch series to your email account by doing:
$ git send-email --to <your mail> ~/patches/*.patch
If the above command fails, maybe there is a typo in your git-send-email configuration. The error message will help you can track down possibly misconfigured settings in your ~/.gitconfig
As I already stated above, if you are not interested in keeping a copy of your patches in a local directory, you can run git-send-email directly on your commits. Try it:
$ git send-email -3 --to=<your mail>
The above command will create the patchset in a subdirectory in /tmp/ and send it to your email. You can specify a different subject prefix as well, using –subject-prefix option. For example:
$ git send-email -3 --subject-prefix="RFC" --to=<your mail>
Now, lets have a look at some useful git-send-email options. A complete list can be found in:
--to=<destination address> If you forget to set it, you will be prompted for it. --cc=<cc'ed address> If you want to cc more than one address, you need to repeat --cc for each CC'ed address. --[no-]chain-reply-to With --no-chain-reply-to, all patches following the first patch will be sent as replies to the first (shallow threading). This is the recommended way to send patch series to mailing lists. This is also the default so you don't need to set it explicitly. [PATCH 1/4] ... [PATCH 2/4] ... [PATCH 3/4] ... [PATCH 4/4] ... With --chain-reply-to, each patch will be sent in reply to the previous one (deep threading). [PATCH 1/4] ... [PATCH 2/4] ... [PATCH 3/4] ... [PATCH 4/4] ... --[no-]thread With --thread, to the sent emails would be added In-Reply-To and References headers. This is enabled by default. --in-reply-to= It is used in order to send the patchset as a reply to an email with the specified Message ID. This is particularly useful when you want to send a revised version for a patchset because it won't break the existing thread and will help reviewers to follow up your changes on the patchset. When --thread and --no-chain-reply-to are specified, threading will look like: [PATCH 1/4] ... [PATCH 2/4] ... [PATCH 3/4] ... [PATCH 4/4] ... [PATCH v2 1/4] ... [PATCH v2 2/4] ... [PATCH v2 3/4] ... [PATCH v2 4/4] ... --compose With this option you can edit and send an introductory message to your patch series. You can specify the subject either when you directly edit the mail or using the option --subject. That can be helpful in case you want to add a cover-letter to describe, for example, the changes introduced after the last revision of the patchset. Take in mind that you would need to set explicitly the subject prefix if you use that method (other method can be using --cover-letter option with git-format-patch) for creating your cover letter e.g: $ git send-email -3 --subject="[RFC 0/3] ..." --compose --to=<your mail>
The last step is to identify to who the patchset should be sent. That can be done using get_maintainer.pl script and the following command:
$ perl scripts/get_maintainer.pl < <your patch>
For instance, in the case of 0002-xhci-fix-SCT_FOR_CTX-p-macro.patch, I did:
$ perl scripts/get_maintainer.pl < 0002-xhci-fix-SCT_FOR_CTX-p-macro.patch
And the output was:
Sarah Sharp (supporter:USB XHCI DRIVER) Greg Kroah-Hartman (supporter:USB SUBSYSTEM) email@example.com (open list:USB XHCI DRIVER) firstname.lastname@example.org (open list)
To send the patchset, I do:
$ git send-email --to email@example.com --cc firstname.lastname@example.org --cc email@example.com --cc firstname.lastname@example.org ~/patches/*.patch
Now, you are ready to send your patchsets to the kernel mailing lists using git-send-email 🙂
Before attempting that though please read the documentation on submitting patches to increase the chances of your patches being accepted.