ao2.it
Antonio Ospite, attacchi teoristici

In linux kernel development there are informal, and yet quite solid, conventions which apply when sharing patches and collaborating during the —public and undisclosed— phase of code peer-review.

As some of you may know, all the communications about kernel development happen via e-mail, and there are some tools to ease the task of preparing and sending patches; these tools allow some degree of customization, or “branding” like I am calling it in this case. Let's see how to decorate our patches so that their author is more easily recognizable (and acknowledgeable). Obviously all this doesn't apply only to linux, that's just where my experience come from.

Let's step back to summarize a common work-flow used when preparing patches with the git SCM:

# clone some repository
git clone git://git.example.com/repo.git
cd repo.git

# create a new development branch and work on it
git branch new-dev-branch
git checkout new-dev-branch

# Commit operation is inexpensive in git, use it
$EDITOR fileA
$EDITOR fileB
git commit fileA fileB
$EDITOR fileA
git commit fileA

# Prepare patches to be sent
git format-patch -s --cover-letter master..new-dev-branch

# Edit patches to:
#   - add Cc recipients
#   - add annotations after the '---' separator,
#      this does not interfere with commit messages
$EDITOR *.patch
git send-email --to "Some MailingList <some@mailinglist>" *.patch

# When the patches are accepted upstream we can delete
# our local development branch
git checkout master
git branch -D new-dev-branch

Now, the patches we are producing this way have the author figuring as the sender, and are signed off according to the Developer Certificate of Origin, but we can still make them more “personal”, for instance we can:

• Add some custom email headers, like Organization or X-Face.
• Appending a signature to the cover letter.

Adding custom headers

Using the format.headers option in git you can add any header conforming to RFC2822 into the patches you generate with git format-patch.

I am adding an X-Face header (the source image is attached at the end of the post):

X-Face: z*RaLf`X<@C75u6Ig9}{oW$H;1_\2t5)({*|jhM<pyWR#k60!#=#>/Vb;]yA5<GWI5`6u&+
 ;6b'@y|8w"wB;4/e!7wYYrcqdJFY,~%Gk_4]cq$Ei/7<j&N3ah(m`ku?pX.&+~:_/wC~dwn^)MizBG
 !pE^+iDQQ1yC6^,)YDKkxDd!T>\I~93>J<_`<4)A{':UrE

To set this you can do:

git config --global --add format.headers ''
git config --global --edit

and then add the string in double quotes, remembering to escape characters in the X-Face as git-config(1) Manual Page says:

Double quote " and backslash \ characters in variable values must be escaped: use \" for " and \\ for \.

The following escape sequences (beside \" and \\) are recognized: \n for newline character (NL), \t for horizontal tabulation (HT, TAB) and \b for backspace (BS). No other char escape sequence, nor octal char sequences are valid.

Which in my case gives:

[format]
	headers = "X-Face: z*RaLf`X<@C75u6Ig9}{oW$H;1_\\2t5)({*|jhM<pyWR#k60!#=#>/Vb;]yA5<GWI5`6u&+\n ;6b'@y|8w\"wB;4/e!7wYYrcqdJFY,~%Gk_4]cq$Ei/7<j&N3ah(m`ku?pX.&+~:_/wC~dwn^)MizBG\n !pE^+iDQQ1yC6^,)YDKkxDd!T>\\I~93>J<_`<4)A{':UrE\n"

Now the recipients can see my X-Face in my patches, provided that their MUA can decode it...

Note: please don't copy and paste this X-Face blindly, this is my X-Face, you want to have your very own.

Appending a signature to the cover letter

If you are using the Vim editor to compose the cover letter and annotate patches it is very easy to make it add your signature to the first mail in your patchset.

Download my signature_block.vim into ~/.vim/plugin/ and add these lines to your ~/.vimrc:

  " Append a signature block to cover letters generated with git-format-patch
  autocmd BufRead 0000-cover-letter.patch silent call AddSignature('~/.signature') | w
  autocmd BufRead 0000-cover-letter.patch autocmd! BufRead 0000-cover-letter.patch

Now the first time you open a file named 0000-cover-letter.patch your signature (any text in ~/.signature, in this case) will be appended automatically.