Git Tip of the Day – introduction text when emailing patches

You have created a great patch and want to send it to project maintainers, but you don’t want to create all the emails by hand (that means opening your email client and copy-n-pasting the patch into the message or – god forbid – adding those patches as attachments). At the same time you would like to provide some introduction text for your patches. How do you do that?

First option: use send-email --compose

git send-email is able to send the patches for you. If you use the --compose option, you will be able to write up an introduction that will be sent as the first email of the whole email series.

Second option: use format-patch --cover-letter

git format-patch creates a series of patches nicely formatted to be used as email bodies. The output is one file per commit. The magical option --cover-letter will create one more file, probably called 0000-cover-letter.patch, that you can use for introduction of your changes. This file will also contain a short summary of your patch series, including author names, commit messages and changed files. Neat.

Third option: misuse git patch syntax

If you have just a single commit change and you don’t like sending multiple emails, but you still want to provide further information (besides commit message), you can misuse the git patch syntax and smuggle some further information into it without affecting the very patch.

Let’s see a sample patch generated with git format-patch:

From 7ea3c50fa83950549de11c6834c465bc8f28b52b Mon Sep 17 00:00:00 2001
From: James Laska
Date: Mon, 1 Aug 2011 09:53:16 -0400
Subject: [PATCH] compose_tree - Save the setup.sh script for later debugging

---
 tests/compose_tree/compose_tree.sh |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

diff --git a/tests/compose_tree/compose_tree.sh b/tests/compose_tree/compose_tree.sh
index 66ecefd..c2e041d 100755
--- a/tests/compose_tree/compose_tree.sh
+++ b/tests/compose_tree/compose_tree.sh
@@ -204,6 +204,8 @@ let RETVAL+=$?

 # Report the results.  We do all the copies individually in case one of the files doesn't exist.
 mkdir -p ${RESULTSDIR}
+cp -f ${SETUP} ${RESULTSDIR}/setup.sh
+let RETVAL+=$?
 cp -f ${MOCKROOTDIR}/${KSCFG} ${RESULTSDIR}/ks.cfg
 let RETVAL+=$?
 cp -f ${MOCKROOTDIR}/../result/root.log ${RESULTSDIR}/
--
1.7.6

Now, if you look up the space between --- and tests/compose_tree/compose_tree.sh, that’s our secret spot. You can add any text in there, it will be visible to the developers, but it will not affect the patch. It then might look like this:

From 7ea3c50fa83950549de11c6834c465bc8f28b52b Mon Sep 17 00:00:00 2001
From: James Laska
Date: Mon, 1 Aug 2011 09:53:16 -0400
Subject: [PATCH] compose_tree - Save the setup.sh script for later debugging

---
This patch is really really important, because otherwise the world will end in
2012. Please accept it.
 tests/compose_tree/compose_tree.sh |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

diff --git a/tests/compose_tree/compose_tree.sh b/tests/compose_tree/compose_tree.sh
index 66ecefd..c2e041d 100755
... (the rest of the patch)

Don’t we love it, having so many options? I’m sure there are more of them, but I like these three.

Enjoy!