How to send patches with git-send-email

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 = burzalodowa@gmail.com
	name = Xenia Ragiadakou
[sendemail]
	smtpuser = burzalodowa@gmail.com
	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:
https://www.kernel.org/pub/software/scm/git/docs/git-send-email.html

--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)
linux-usb@vger.kernel.org (open list:USB XHCI DRIVER)
linux-kernel@vger.kernel.org (open list)

To send the patchset, I do:

$ git send-email --to sarah.a.sharp@linux.intel.com
  --cc gregkh@linuxfoundation.org --cc linux-usb@vger.kernel.org
  --cc linux-kernel@vger.kernel.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.
https://www.kernel.org/doc/Documentation/SubmittingPatches

This entry was posted in Uncategorized. Bookmark the permalink.

3 Responses to How to send patches with git-send-email

  1. prajul says:

    This post is really good, better than what’s there in the Documentation.I could have saved a day’s work if i had seen this blog first !!

  2. Guy-Daniel Tiku says:

    This howto is well written and is so totally sweet and awesome for git send-email newbies. This deserves to be the man page for git send-email. It REALLY helped me out when I needed it.

  3. Pingback: GSoC 2018 – DAWN a decentralized WiFi controller (1st update) - Freifunkblog

Leave a comment