MyFirstContribution: recommend the use of b4
The b4 tool originates from the Linux kernel community and is intended to help mailing-list based workflows. It automates a lot of the annoying bookkeeping tasks that contributors typically need to do: tracking the list of recipients, Message-IDs, range-diffs and the like. In addition to that, b4 also has many other subcommands that help the maintainer and reviewers. The Git project uses the same infrastructure as the kernel, so this tool is also a very good fit for us. Adapt "MyFirstContribution" to explicitly recommend its use. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Patrick Steinhardt committed
Jun 15, 2026 at 14:59 UTC
efe4ac70647c62152c37f2f247404c9dfd494ed5
2 files changed
+93
-5
Documentation/MyFirstContribution.adoc
+89
-3
@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not
833
be merged.
834
----
835
836
-At this point the tutorial diverges, in order to demonstrate two
836
+At this point the tutorial diverges, in order to demonstrate three
837
different methods of formatting your patchset and getting it reviewed.
838
839
The first method to be covered is GitGitGadget, which is useful for those
@@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some
845
setup which can change depending on your system and will not be covered in this
846
tutorial.
847
848
+The third method to be covered is `b4`, which builds on top of `git
849
+format-patch` and `git send-email`. This method is the recommended way to
850
+submit patches via mail as it automates a lot of the bookkeeping required by
851
+`git send-email`.
852
+
853
Regardless of which method you choose, your engagement with reviewers will be
849
-the same; the review process will be covered after the sections on GitGitGadget
850
-and `git send-email`.
854
+the same; the review process will be covered after the sections on GitGitGadget,
855
+`git send-email` and `b4`.
856
857
[[howto-ggg]]
858
== Sending Patches via GitGitGadget
@@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644
1301
2.21.0.392.gf8f6787159e-goog
1302
----
1303
1304
+[[howto-b4]]
1305
+== Sending Patches with `b4`
1306
+
1307
+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.
1308
+It automates much of the bookkeeping involved in sending a patch series to a
1309
+mailing-list-based project.
1310
+
1311
+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.
1312
+
1313
+[[prep-b4]]
1314
+=== Preparing a Patch Series
1315
+
1316
+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch
1317
+you have been working on, run:
1318
+
1319
+----
1320
+$ b4 prep --enroll master
1321
+----
1322
+
1323
+This enrolls the current branch, using `master` as the base of the topic. `b4`
1324
+manages the cover letter as part of the branch, so you can edit it at any time
1325
+with:
1326
+
1327
+----
1328
+$ b4 prep --edit-cover
1329
+----
1330
+
1331
+The cover letter not only tracks the content of the top-level mail, but also
1332
+the set of recipients. You can add recipients by adding `To:` and `Cc:`
1333
+trailer lines.
1334
+
1335
+[[send-b4]]
1336
+=== Sending the Patches
1337
+
1338
+Before sending the series out for real, you can inspect what `b4` would send by
1339
+passing `--dry-run`:
1340
+
1341
+----
1342
+$ b4 send --dry-run
1343
+----
1344
+
1345
+Once you are happy with the result, send the series with:
1346
+
1347
+----
1348
+$ b4 send
1349
+----
1350
+
1351
+[[v2-b4]]
1352
+=== Sending v2
1353
+
1354
+When you are ready to send a new iteration of your series, refine your
1355
+patches as usual using linkgit:git-rebase[1]. Note that you typically want to
1356
+rebase on top of the cover letter. You can configure an alias to enable easy
1357
+rebases going forward:
1358
+
1359
+---
1360
+$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
1361
+$ git b4-rebase -i
1362
+---
1363
+
1364
+Before sending out the new version you should also update the cover letter with
1365
+`b4 prep --edit-cover` to note the relevant changes compared to the previous
1366
+version. You can inspect the changes between the two versions with `b4 prep
1367
+--compare-to=v1`.
1368
+
1369
+Same as with the first version, you can use `b4 send` to send out the second
1370
+version. `b4` automatically bumps the version to `v2`, generates the range-diff
1371
+against the previous iteration, and threads the new series as a reply to the
1372
+cover letter of the first version.
1373
+
1374
+[[configure-b4]]
1375
+=== Configure b4
1376
+
1377
+`b4` can be configured via linkgit:git-config[1]. In addition to that, projects
1378
+can have their own set of defaults in `.b4-config` in the root tree, which also
1379
+uses Git's config format. The user's configuration always takes precedence over
1380
+the per-project defaults.
1381
+
1382
+Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]
1383
+for more information on the available options.
1384
+
1385
[[now-what]]
1386
== My Patch Got Emailed - Now What?
1387
Documentation/SubmittingPatches
+4
-2
@@ -573,8 +573,10 @@ your existing e-mail client (often optimized for "multipart/*" MIME
573
type e-mails) might render your patches unusable.
574
575
NOTE: Here we outline the procedure using `format-patch` and
576
-`send-email`, but you can instead use GitGitGadget to send in your
577
-patches (see link:MyFirstContribution.html[MyFirstContribution]).
576
+`send-email`, but you can instead use GitGitGadget or `b4` to send in
577
+your patches (see link:MyFirstContribution.html[MyFirstContribution]).
578
+Contributors are encouraged to use `b4`, which automates much of the
579
+bookkeeping that is otherwise done by hand.
580
581
People on the Git mailing list need to be able to read and
582
comment on the changes you are submitting. It is important for