B4

b4 is a great tool designed to simplify handling patch series for email-based projects. Linux and Git both fit this description (b4 does too, what a surprise, right?).

The documentation is great, and you can get up and running in almost no time. I won’t try to explain its features (that’s what the documentation is for), but I will highlight my brief experience with the tool and the reasons I think everyone should at least consider using it (specially newbies).

Background

Before trying b4, I had already played a little bit with manually generating patches and sending them via email “manually”. It is not particularly great but it’s not that bad, so I thought I didn’t need anything else. After all, that’s how hardcore people¹ work, right?

However, I was left with the feeling that handling the different patch versions was tedious. The first time I sent a patch for review I ended up doing the following:

1. I produced a v1
2. I got review, modified the patch and sent out a v2. After rebasing and such I “lost”² the v1
3. Repeat N times.

What I ended up having is a folder for a patch series full of .patch files, cover letters, and responses to feedback. It didn’t look great, and it was annoying. I could only imagine how horrible everything would look like if I worked on n patches at the same time.

Naturally, you can overcome these limitations by devising your own workflow and being organized, but that takes time and practice. Perhaps somebody else has had the same problem and solved it already?

Managing the different versions of a patch

b4 handles your patch series with a branch. You choose their name, but they are created as b4/your-patch-name. This branch will evolve, but every time you send it for review, b4 will create tags in the form of sent/id-for-vN to keep track³ of old versions. I’m guessing this is what enables b4 prep --compare-to vN which is a nice wrapper over git range-diff.

b4 recently got a new option (--range-diff-opts) to pass arguments to git range-diff. As the patch points out, a nice example for this is --creation-factor which might be > necessary to do proper range-diffing for very small patches. Git detects those as “different” very quickly nice feature. Thanks Antonin Godard :)

Addressing reviews and documentating a patch’s evolution

Properly describing how your patch has evolved across versions is very important. It is very likely that your reviewer sees hundreds(?) of patches in a week. He won’t remember what your patch was, but he can quickly remember if he was “okeysh” with it, asked you to change something and you actually did.

b4 generates nice boilerplate for you to edit:

1Changes in vN:
2- *Some strings I don't remember telling you to explain your changes*
3- ...
4- Link to vN-1

which is great because

1. You won’t forget to fill these (and if you do, it will be obvious that it was a mistake and you just resend the patch)
2. It fetches those Links for you.

Conclusions

b4 is very useful. If you don’t have a lot of experience with email-based projects I’m guessing it is very likely that it will be very helpful to you. Give it a try!

Appendix

I’m participating in the Linux Kernel Mentorship Program, that’s why I decided to try b4 (I didn’t have a reason to use it b4⁴). In this program you are supposed to send your patches to whoever is appropriate and to your mentor and mentees mailing list. I kind of stressed about this thinking that I would sometimes forget to do this, but b4 had my back. Putting

1[b4]
2    send-series-to = a@b.c,d@e.f,...
3    send-series-cc = i@j.k,x@y.z,...

into the .git/config of your Linux clone takes care of this (naturally, you don’t have to use both).