[PATCH 0/2] Documentation: recommend the use of b4

[PATCH 0/2] Documentation: recommend the use of b4

[Patrick Steinhardt]

Hi,

this small patch series wires up b4 in Git and recommends the use
thereof via "MyFirstContribution", as discussed in [1].

Thanks!

Patrick

[1]: <xmqqik81xpqx.fsf@gitster.g>

---
Patrick Steinhardt (2):
      b4: introduce configuration for the Git project
      Documentation/MyFirstContribution: recommend the use of b4

 .b4-config                             |  3 ++
 .b4-cover-template                     | 11 +++++
 Documentation/MyFirstContribution.adoc | 81 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 4 files changed, 96 insertions(+), 5 deletions(-)


---
base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0
change-id: 20260602-pks-b4-31cc20d7f84b

[PATCH 1/2] b4: introduce configuration for the Git project

[Patrick Steinhardt]

We're about to extend our documentation to recommend b4 for sending
patch series ot the mailing list. Prepare for this by introducing a b4
configuration so that the tool knows to honor our preferences. For now,
this configuration does two things:

  - It configures "send-same-thread = shallow", which tells b4 to always
    send subsequent versions of the same patch series as a reply to the
    cover letter of the first version.

  - It configures "prep-cover-template", which tells b4 to use a custom
    template for the cover letter. The most important change compared to
    the default template is that our custom template also includes a
    range-diff.

There's potentially more things that we may want to configure going
forward, like for example auto-configuration of folks to Cc on certain
patches. But these two tweaks feel like a good place to start.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 .b4-config         |  3 +++
 .b4-cover-template | 11 +++++++++++
 2 files changed, 14 insertions(+)

diff --git a/.b4-config b/.b4-config
new file mode 100644
index 0000000000..14124728ce
--- /dev/null
+++ b/.b4-config
@@ -0,0 +1,3 @@
+[b4]
+send-same-thread = shallow
+prep-cover-template = ./.b4-cover-template
diff --git a/.b4-cover-template b/.b4-cover-template
new file mode 100644
index 0000000000..ab864933b5
--- /dev/null
+++ b/.b4-cover-template
@@ -0,0 +1,11 @@
+${cover}
+
+---
+${shortlog}
+
+${diffstat}
+
+${range_diff}
+---
+base-commit: ${base_commit}
+${prerequisites}

-- 
2.54.0.1064.gd145956f57.dirty

[PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4

[Patrick Steinhardt]

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>
---
 Documentation/MyFirstContribution.adoc | 81 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 2 files changed, 82 insertions(+), 5 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index b9fdefce02..2e50111d89 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not
 be merged.
 ----
 
-At this point the tutorial diverges, in order to demonstrate two
+At this point the tutorial diverges, in order to demonstrate three
 different methods of formatting your patchset and getting it reviewed.
 
 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
 setup which can change depending on your system and will not be covered in this
 tutorial.
 
+The third method to be covered is `b4`, which builds on top of `git
+format-patch` and `git send-email`. This method is the recommended way to
+submit patches via mail as it automates a lot of the bookkeeping required by
+`git send-email`.
+
 Regardless of which method you choose, your engagement with reviewers will be
-the same; the review process will be covered after the sections on GitGitGadget
-and `git send-email`.
+the same; the review process will be covered after the sections on GitGitGadget,
+`git send-email` and `b4`.
 
 [[howto-ggg]]
 == Sending Patches via GitGitGadget
@@ -1296,6 +1301,76 @@ index 88f126184c..38da593a60 100644
 2.21.0.392.gf8f6787159e-goog
 ----
 
+[[howto-b4]]
+== Sending Patches with `b4`
+
+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.
+It automates much of the bookkeeping involved in sending a patch series to a
+mailing-list-based project.
+
+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.
+
+[[prep-b4]]
+=== Preparing a Patch Series
+
+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch
+you have been working on, run:
+
+----
+$ b4 prep --enroll master
+----
+
+This enrolls the current branch, using `master` as the base of the topic. `b4`
+manages the cover letter as part of the branch, so you can edit it at any time
+with:
+
+----
+$ b4 prep --edit-cover
+----
+
+The cover letter not only tracks the content of the top-level mail, but also
+the set of recipients. You can add recipients by adding `To:` and `Cc:`
+trailer lines.
+
+[[send-b4]]
+=== Sending the Patches
+
+Before sending the series out for real, you can inspect what `b4` would send by
+passing `--dry-run`:
+
+----
+$ b4 send --dry-run
+----
+
+Once you are happy with the result, send the series with:
+
+----
+$ b4 send
+----
+
+[[v2-b4]]
+=== Sending v2
+
+When you are ready to send a new iteration of your series, refine your
+patches as usual using linkgit:git-rebase[1]. Note that you typically want to
+rebase on top of the cover letter. You can configure an alias to enable easy
+rebases going forward:
+
+---
+$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
+$ git b4-rebase -i
+---
+
+Before sending out the new version you should also update the cover letter with
+`b4 prep --edit-cover` to note the relevant changes compared to the previous
+version. You can inspect the changes between the two versions with `b4 prep
+--compare-to=v1`.
+
+Same as with the first version, you can use `b4 send` to send out the second
+version. `b4` automatically bumps the version to `v2`, generates the range-diff
+against the previous iteration, and threads the new series as a reply to the
+cover letter of the first version.
+
 [[now-what]]
 == My Patch Got Emailed - Now What?
 
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d570184ec8..99427e1ee1 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -573,8 +573,10 @@ your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
 
 NOTE: Here we outline the procedure using `format-patch` and
-`send-email`, but you can instead use GitGitGadget to send in your
-patches (see link:MyFirstContribution.html[MyFirstContribution]).
+`send-email`, but you can instead use GitGitGadget or `b4` to send in
+your patches (see link:MyFirstContribution.html[MyFirstContribution]).
+Contributors are encouraged to use `b4`, which automates much of the
+bookkeeping that is otherwise done by hand.
 
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for

-- 
2.54.0.1064.gd145956f57.dirty

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> We're about to extend our documentation to recommend b4 for sending
> patch series ot the mailing list. Prepare for this by introducing a b4
> configuration so that the tool knows to honor our preferences. For now,
> this configuration does two things:
>
>   - It configures "send-same-thread = shallow", which tells b4 to always
>     send subsequent versions of the same patch series as a reply to the
>     cover letter of the first version.
>
>   - It configures "prep-cover-template", which tells b4 to use a custom
>     template for the cover letter. The most important change compared to
>     the default template is that our custom template also includes a
>     range-diff.
>
> There's potentially more things that we may want to configure going
> forward, like for example auto-configuration of folks to Cc on certain
> patches. But these two tweaks feel like a good place to start.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>  .b4-config         |  3 +++
>  .b4-cover-template | 11 +++++++++++
>  2 files changed, 14 insertions(+)

Shipping a sample like ".b4-config.sample" that users who opt-in can
copy-and-edit into the final name ".b4-config" is OK, but I'd rather
not to ship the configuration files that the users would want to edit
(hence making the tree dirty).

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Patrick Steinhardt]

On Tue, Jun 02, 2026 at 10:32:23PM +0900, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > We're about to extend our documentation to recommend b4 for sending
> > patch series ot the mailing list. Prepare for this by introducing a b4
> > configuration so that the tool knows to honor our preferences. For now,
> > this configuration does two things:
> >
> >   - It configures "send-same-thread = shallow", which tells b4 to always
> >     send subsequent versions of the same patch series as a reply to the
> >     cover letter of the first version.
> >
> >   - It configures "prep-cover-template", which tells b4 to use a custom
> >     template for the cover letter. The most important change compared to
> >     the default template is that our custom template also includes a
> >     range-diff.
> >
> > There's potentially more things that we may want to configure going
> > forward, like for example auto-configuration of folks to Cc on certain
> > patches. But these two tweaks feel like a good place to start.
> >
> > Signed-off-by: Patrick Steinhardt <ps@pks.im>
> > ---
> >  .b4-config         |  3 +++
> >  .b4-cover-template | 11 +++++++++++
> >  2 files changed, 14 insertions(+)
> 
> Shipping a sample like ".b4-config.sample" that users who opt-in can
> copy-and-edit into the final name ".b4-config" is OK, but I'd rather
> not to ship the configuration files that the users would want to edit
> (hence making the tree dirty).

I think shipping this as-is makes sense though, as it allows us to make
b4 behave the way we want it to without the user having to do anything.
If users actually want to reconfigure those values they can by saying
`git config set b4.<foobar>`, as the repository-local configuration will
override whatever `.b4-config` has.

Patrick

Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4

[Weijie Yuan]

Hi Patrick and Junio,

Just so happens that I just submitted my first patch. At this point, I
may or should be the target audience for this document.

I personally watched Patrick's videos with Scott Chacon[1] first, and I
reviewed them many times until I could do those "manual" git operations.

> +Contributors are encouraged to use `b4`, which automates much of the
> +bookkeeping that is otherwise done by hand.

So for statement like this and with my personal experience, I would say
b4 is a more suitable option for senior contributors, as they already
know, for example, what Message-ID and range-diffs are. But apparently,
whose who use forges may not know.

Back to the patch, I think regarding b4 as a more advanced contribution
way for those who had contributed via mailing lists for more than one
time is a better expression or formulation. Here I mean "b4 prep", other
usage like "b4 mbox" and "b4 am" are of course more basic, and be
mentioned as tips when interacting with Git mailing list.

A bit too wordy, in conclusion: Suggest that new contributors master
classic git operations first. When they are familiar with those process,
b4 might be a good option.

Thanks!
--
[1] https://www.youtube.com/watch?v=mjYac9SwIK0&t=1s (Part 1)

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Ramsay Jones]

On 02/06/2026 2:32 pm, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
>> We're about to extend our documentation to recommend b4 for sending
>> patch series ot the mailing list. Prepare for this by introducing a b4
>> configuration so that the tool knows to honor our preferences. For now,
>> this configuration does two things:
>>
>>   - It configures "send-same-thread = shallow", which tells b4 to always
>>     send subsequent versions of the same patch series as a reply to the
>>     cover letter of the first version.
>>
>>   - It configures "prep-cover-template", which tells b4 to use a custom
>>     template for the cover letter. The most important change compared to
>>     the default template is that our custom template also includes a
>>     range-diff.
>>
>> There's potentially more things that we may want to configure going
>> forward, like for example auto-configuration of folks to Cc on certain
>> patches. But these two tweaks feel like a good place to start.
>>
>> Signed-off-by: Patrick Steinhardt <ps@pks.im>
>> ---
>>  .b4-config         |  3 +++
>>  .b4-cover-template | 11 +++++++++++
>>  2 files changed, 14 insertions(+)
> 
> Shipping a sample like ".b4-config.sample" that users who opt-in can
> copy-and-edit into the final name ".b4-config" is OK, but I'd rather
> not to ship the configuration files that the users would want to edit
> (hence making the tree dirty).
> 

Hmm, for those of us not in the know, perhaps mention the b4 documentation
at 'b4.docs.kernel.org' (which includes how to install b4 ... ;) ).

ATB,
Ramsay Jones

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Tuomas Ahola]

Patrick Steinhardt <ps@pks.im> wrote:

> We're about to extend our documentation to recommend b4 for sending
> patch series ot the mailing list. Prepare for this by introducing a b4

s/ot/to/

> configuration so that the tool knows to honor our preferences. For now,
> this configuration does two things:
> 
>   - It configures "send-same-thread = shallow", which tells b4 to always
>     send subsequent versions of the same patch series as a reply to the
>     cover letter of the first version.
> 

Huh?  Doesn't MyFirstContribution speak *against* shallow threading?

	        [...]  make sure to replace it with the correct Message-ID for your
	**previous cover letter** - that is, if you're sending v2, use the Message-ID
	from v1; if you're sending v3, use the Message-ID from v2.

Besides, GitGitGadget also employs that kind of nested threading, if I'm
not mistaken.

Thanks.

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Weijie Yuan]

On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:
> Huh?  Doesn't MyFirstContribution speak *against* shallow threading?
>
> 	        [...]  make sure to replace it with the correct Message-ID for your
> 	**previous cover letter** - that is, if you're sending v2, use the Message-ID
> 	from v1; if you're sending v3, use the Message-ID from v2.

I don't get it. Doesn't shallow threading means every following patches
are replying to the cover letter? Replying to the previous one is
--chain-reply-to, if I'm not mistaken.

Thanks.

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Junio C Hamano]

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

> On 02/06/2026 2:32 pm, Junio C Hamano wrote:
>> Patrick Steinhardt <ps@pks.im> writes:
>> 
>>> We're about to extend our documentation to recommend b4 for sending
>>> patch series ot the mailing list. Prepare for this by introducing a b4
>>> configuration so that the tool knows to honor our preferences. For now,
>>> this configuration does two things:
>>> ...
>> (hence making the tree dirty).
>
> Hmm, for those of us not in the know, perhaps mention the b4 documentation
> at 'b4.docs.kernel.org' (which includes how to install b4 ... ;) ).

Thanks for raising an excellent point.

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Patrick Steinhardt]

On Wed, Jun 03, 2026 at 11:59:48AM +0900, Junio C Hamano wrote:
> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
> 
> > On 02/06/2026 2:32 pm, Junio C Hamano wrote:
> >> Patrick Steinhardt <ps@pks.im> writes:
> >> 
> >>> We're about to extend our documentation to recommend b4 for sending
> >>> patch series ot the mailing list. Prepare for this by introducing a b4
> >>> configuration so that the tool knows to honor our preferences. For now,
> >>> this configuration does two things:
> >>> ...
> >> (hence making the tree dirty).
> >
> > Hmm, for those of us not in the know, perhaps mention the b4 documentation
> > at 'b4.docs.kernel.org' (which includes how to install b4 ... ;) ).
> 
> Thanks for raising an excellent point.

I already refer to the docs in the second commit. Let me maybe reorder
them so that we first show how it's used before tweaking it.

Patrick

Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4

[Patrick Steinhardt]

On Wed, Jun 03, 2026 at 12:09:16AM +0800, Weijie Yuan wrote:
> > +Contributors are encouraged to use `b4`, which automates much of the
> > +bookkeeping that is otherwise done by hand.
> 
> So for statement like this and with my personal experience, I would say
> b4 is a more suitable option for senior contributors, as they already
> know, for example, what Message-ID and range-diffs are. But apparently,
> whose who use forges may not know.

I think it's perfectly suitable for newcomers, too. It automates so many
of the concepts that a contributor has to learn way less about mailing
list specific concepts, which reduces the learning curve.

> Back to the patch, I think regarding b4 as a more advanced contribution
> way for those who had contributed via mailing lists for more than one
> time is a better expression or formulation. Here I mean "b4 prep", other
> usage like "b4 mbox" and "b4 am" are of course more basic, and be
> mentioned as tips when interacting with Git mailing list.
> 
> A bit too wordy, in conclusion: Suggest that new contributors master
> classic git operations first. When they are familiar with those process,
> b4 might be a good option.

Ah, that's what you're hinting at. So you mean to say that folks should
first understand the basics before basically automating all of the parts
for them?

I guess I can see where you're coming from, but I'm not sure I agree
with this a 100%. My main goal is to make it easier for new community
members to contribute to Git, and that means that we should automate all
the hard parts as far as possible. This saves those new contributors
from frustration, and it means that reviewers on the mailing list won't
have to teach every single new contributor about how they should thread
the mails, generate range-diffs and the like.

So in the end, it saves both their and our time, but the learning
opportunity is of course a bit diminished. I'd gladly accept that
tradeoff though.

Thanks for your input!

Patrick

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Patrick Steinhardt]

On Wed, Jun 03, 2026 at 10:12:22AM +0800, Weijie Yuan wrote:
> On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:
> > Huh?  Doesn't MyFirstContribution speak *against* shallow threading?
> >
> > 	        [...]  make sure to replace it with the correct Message-ID for your
> > 	**previous cover letter** - that is, if you're sending v2, use the Message-ID
> > 	from v1; if you're sending v3, use the Message-ID from v2.
> 
> I don't get it. Doesn't shallow threading means every following patches
> are replying to the cover letter? Replying to the previous one is
> --chain-reply-to, if I'm not mistaken.

Shallow threading basically means that all patches are sent as a
response to the current cover letter, and the current cover letter is
always attached to the cover letter of the _first_ version.

So this quote is definitely at odds with the configuration I have
proposed. It's actually quite surprising to me that we recommend deep
threading -- I personally find it extremely hard to navigate as the
nesting eventually gets way too deep.

You know -- I'll include a patch that changes the wording there to also
use shallow nesting, mostly to kick off a discussion and arrive at a
decision there.

Thanks!

Patrick

[PATCH v2 0/3] Documentation: recommend the use of b4

[Patrick Steinhardt]

Hi,

this small patch series wires up b4 in Git and recommends the use
thereof via "MyFirstContribution", as discussed in [1].

Changes in v2:
  - Reorder commits so that the b4 docs are added first.
  - Add a section that highlights how to configure b4, and that points
    out that the per-project defaults can be overridden via Git
    configuration.
  - Add a patch to MyFirstContribution that recommends shallow
    threading. I mostly intend this to be a discussion starter so that
    the `.b4-config` file matches our preferred threading style.
  - Fix a typo.
  - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im

Thanks!

Patrick

[1]: <xmqqik81xpqx.fsf@gitster.g>

---
Patrick Steinhardt (3):
      Documentation/MyFirstContribution: recommend shallow threading
      Documentation/MyFirstContribution: recommend the use of b4
      b4: introduce configuration for the Git project

 .b4-config                             |  6 +++
 .b4-cover-template                     | 11 ++++
 Documentation/MyFirstContribution.adoc | 96 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 4 files changed, 112 insertions(+), 7 deletions(-)

Range-diff versus v1:

-:  ---------- > 1:  359ce9ec24 Documentation/MyFirstContribution: recommend shallow threading
2:  55fffeb8f8 ! 2:  ce9aa56846 Documentation/MyFirstContribution: recommend the use of b4
    @@ Documentation/MyFirstContribution.adoc: index 88f126184c..38da593a60 100644
     +version. `b4` automatically bumps the version to `v2`, generates the range-diff
     +against the previous iteration, and threads the new series as a reply to the
     +cover letter of the first version.
    ++
    ++[[configure-b4]]
    ++=== Configure b4
    ++
    ++`b4` can be configured via linkgit:git-config[1]. In addition to that, projects
    ++can have their own set of defaults in `.b4-config` in the root tree, which also
    ++uses Git's config format. The user's configuration always takes precedence over
    ++the per-project defaults.
    ++
    ++Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]
    ++for more information on the available options.
     +
      [[now-what]]
      == My Patch Got Emailed - Now What?
1:  0fe6cf8511 ! 3:  e2bf7b6e46 b4: introduce configuration for the Git project
    @@ Commit message
         b4: introduce configuration for the Git project
     
         We're about to extend our documentation to recommend b4 for sending
    -    patch series ot the mailing list. Prepare for this by introducing a b4
    +    patch series to the mailing list. Prepare for this by introducing a b4
         configuration so that the tool knows to honor our preferences. For now,
         this configuration does two things:
     
    @@ Commit message
         forward, like for example auto-configuration of folks to Cc on certain
         patches. But these two tweaks feel like a good place to start.
     
    +    Note that these values only serve as defaults, and users may want to
    +    tweak those defaults based on their own preference. Luckily, users can
    +    do that without having to touch `.b4-config` at all, as b4 allows them
    +    to override values via Git configuration:
    +
    +        ```
    +        $ git config set b4.prep-cover-template /does/not/exist
    +        $ b4 send --dry-run
    +        ERROR: prep-cover-template says to use x, but it does not exist
    +        ```
    +
    +    So this gives users an easy way to override our defaults without having
    +    to touch ".b4-config", which would dirty the tree.
    +
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
      ## .b4-config (new) ##
     @@
    ++# Note that these are default values that you can tweak via the typical
    ++# git-config(1) machinery. You thus shouldn't ever have to change this file.
    ++# See also https://b4.docs.kernel.org/en/latest/config.html.
     +[b4]
     +send-same-thread = shallow
     +prep-cover-template = ./.b4-cover-template

---
base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0
change-id: 20260602-pks-b4-31cc20d7f84b

[PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading

[Patrick Steinhardt]

The "MyFirstContribution" document recommends the use of deep threading:
every cover letter of subsequent iterations shall be linked to the cover
letter of the preceding version. The result of this is that eventually,
threads with many versions are getting nested so deep that it becomes
hard to follow.

Adapt the recommendation to instead propose shallow threading: instead
of linking the cover letter to the previous cover letter, the user is
supposed to always link it to the first cover letter. This still makes
it easy to follow the iterations, but has the benefit of nesting to a
much shallower level.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index b9fdefce02..069020196c 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1227,8 +1227,8 @@ Message-ID: <foo.12345.author@example.com>
 
 Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
 below as well; make sure to replace it with the correct Message-ID for your
-**previous cover letter** - that is, if you're sending v2, use the Message-ID
-from v1; if you're sending v3, use the Message-ID from v2.
+**first cover letter** - that is, for any subsequent version that you send,
+always use the Message-ID from v1.
 
 While you're looking at the email, you should also note who is CC'd, as it's
 common practice in the mailing list to keep all CCs on a thread. You can add

-- 
2.54.0.1064.gd145956f57.dirty

[PATCH v2 2/3] Documentation/MyFirstContribution: recommend the use of b4

[Patrick Steinhardt]

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>
---
 Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 2 files changed, 93 insertions(+), 5 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 069020196c..fc0b06ae67 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not
 be merged.
 ----
 
-At this point the tutorial diverges, in order to demonstrate two
+At this point the tutorial diverges, in order to demonstrate three
 different methods of formatting your patchset and getting it reviewed.
 
 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
 setup which can change depending on your system and will not be covered in this
 tutorial.
 
+The third method to be covered is `b4`, which builds on top of `git
+format-patch` and `git send-email`. This method is the recommended way to
+submit patches via mail as it automates a lot of the bookkeeping required by
+`git send-email`.
+
 Regardless of which method you choose, your engagement with reviewers will be
-the same; the review process will be covered after the sections on GitGitGadget
-and `git send-email`.
+the same; the review process will be covered after the sections on GitGitGadget,
+`git send-email` and `b4`.
 
 [[howto-ggg]]
 == Sending Patches via GitGitGadget
@@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644
 2.21.0.392.gf8f6787159e-goog
 ----
 
+[[howto-b4]]
+== Sending Patches with `b4`
+
+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.
+It automates much of the bookkeeping involved in sending a patch series to a
+mailing-list-based project.
+
+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.
+
+[[prep-b4]]
+=== Preparing a Patch Series
+
+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch
+you have been working on, run:
+
+----
+$ b4 prep --enroll master
+----
+
+This enrolls the current branch, using `master` as the base of the topic. `b4`
+manages the cover letter as part of the branch, so you can edit it at any time
+with:
+
+----
+$ b4 prep --edit-cover
+----
+
+The cover letter not only tracks the content of the top-level mail, but also
+the set of recipients. You can add recipients by adding `To:` and `Cc:`
+trailer lines.
+
+[[send-b4]]
+=== Sending the Patches
+
+Before sending the series out for real, you can inspect what `b4` would send by
+passing `--dry-run`:
+
+----
+$ b4 send --dry-run
+----
+
+Once you are happy with the result, send the series with:
+
+----
+$ b4 send
+----
+
+[[v2-b4]]
+=== Sending v2
+
+When you are ready to send a new iteration of your series, refine your
+patches as usual using linkgit:git-rebase[1]. Note that you typically want to
+rebase on top of the cover letter. You can configure an alias to enable easy
+rebases going forward:
+
+---
+$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
+$ git b4-rebase -i
+---
+
+Before sending out the new version you should also update the cover letter with
+`b4 prep --edit-cover` to note the relevant changes compared to the previous
+version. You can inspect the changes between the two versions with `b4 prep
+--compare-to=v1`.
+
+Same as with the first version, you can use `b4 send` to send out the second
+version. `b4` automatically bumps the version to `v2`, generates the range-diff
+against the previous iteration, and threads the new series as a reply to the
+cover letter of the first version.
+
+[[configure-b4]]
+=== Configure b4
+
+`b4` can be configured via linkgit:git-config[1]. In addition to that, projects
+can have their own set of defaults in `.b4-config` in the root tree, which also
+uses Git's config format. The user's configuration always takes precedence over
+the per-project defaults.
+
+Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]
+for more information on the available options.
+
 [[now-what]]
 == My Patch Got Emailed - Now What?
 
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d570184ec8..99427e1ee1 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -573,8 +573,10 @@ your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
 
 NOTE: Here we outline the procedure using `format-patch` and
-`send-email`, but you can instead use GitGitGadget to send in your
-patches (see link:MyFirstContribution.html[MyFirstContribution]).
+`send-email`, but you can instead use GitGitGadget or `b4` to send in
+your patches (see link:MyFirstContribution.html[MyFirstContribution]).
+Contributors are encouraged to use `b4`, which automates much of the
+bookkeeping that is otherwise done by hand.
 
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for

-- 
2.54.0.1064.gd145956f57.dirty

[PATCH v2 3/3] b4: introduce configuration for the Git project

[Patrick Steinhardt]

We're about to extend our documentation to recommend b4 for sending
patch series to the mailing list. Prepare for this by introducing a b4
configuration so that the tool knows to honor our preferences. For now,
this configuration does two things:

  - It configures "send-same-thread = shallow", which tells b4 to always
    send subsequent versions of the same patch series as a reply to the
    cover letter of the first version.

  - It configures "prep-cover-template", which tells b4 to use a custom
    template for the cover letter. The most important change compared to
    the default template is that our custom template also includes a
    range-diff.

There's potentially more things that we may want to configure going
forward, like for example auto-configuration of folks to Cc on certain
patches. But these two tweaks feel like a good place to start.

Note that these values only serve as defaults, and users may want to
tweak those defaults based on their own preference. Luckily, users can
do that without having to touch `.b4-config` at all, as b4 allows them
to override values via Git configuration:

    ```
    $ git config set b4.prep-cover-template /does/not/exist
    $ b4 send --dry-run
    ERROR: prep-cover-template says to use x, but it does not exist
    ```

So this gives users an easy way to override our defaults without having
to touch ".b4-config", which would dirty the tree.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 .b4-config         |  6 ++++++
 .b4-cover-template | 11 +++++++++++
 2 files changed, 17 insertions(+)

diff --git a/.b4-config b/.b4-config
new file mode 100644
index 0000000000..fd4fb56b6d
--- /dev/null
+++ b/.b4-config
@@ -0,0 +1,6 @@
+# Note that these are default values that you can tweak via the typical
+# git-config(1) machinery. You thus shouldn't ever have to change this file.
+# See also https://b4.docs.kernel.org/en/latest/config.html.
+[b4]
+send-same-thread = shallow
+prep-cover-template = ./.b4-cover-template
diff --git a/.b4-cover-template b/.b4-cover-template
new file mode 100644
index 0000000000..ab864933b5
--- /dev/null
+++ b/.b4-cover-template
@@ -0,0 +1,11 @@
+${cover}
+
+---
+${shortlog}
+
+${diffstat}
+
+${range_diff}
+---
+base-commit: ${base_commit}
+${prerequisites}

-- 
2.54.0.1064.gd145956f57.dirty

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Weijie Yuan]

On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:
> So this quote is definitely at odds with the configuration I have
> proposed. It's actually quite surprising to me that we recommend deep
> threading -- I personally find it extremely hard to navigate as the
> nesting eventually gets way too deep.

Sorry I'm a little confused. The example thread at git-scm.com:

https://git-scm.com/docs/MyFirstContribution#ready-to-share

Isn't this actually supporting shallow nesting?

> It's actually quite surprising to me that we recommend deep
> threading -- I personally find it extremely hard to navigate as the
> nesting eventually gets way too deep.

In my understanding, deep threading == --chain-reply-to, so can you
point out where do Git recommend deep threading? I always thought Git
supports shallow threading.

Thanks! And please forgive me if I am wrong :-)

Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4

[Weijie Yuan]

On Wed, Jun 03, 2026 at 08:54:56AM +0200, Patrick Steinhardt wrote:
> Ah, that's what you're hinting at. So you mean to say that folks should
> first understand the basics before basically automating all of the parts
> for them?
>
> I guess I can see where you're coming from, but I'm not sure I agree
> with this a 100%. My main goal is to make it easier for new community
> members to contribute to Git, and that means that we should automate all
> the hard parts as far as possible. This saves those new contributors
> from frustration, and it means that reviewers on the mailing list won't
> have to teach every single new contributor about how they should thread
> the mails, generate range-diffs and the like.
>
> So in the end, it saves both their and our time, but the learning
> opportunity is of course a bit diminished. I'd gladly accept that
> tradeoff though.

Yeah, after I expressed my opinion, I also felt a bit conflicted though.
So I also agree with your intension.

Make an inappropriate metaphor: some usage of b4 and magit are "Porcelain"
to Git. Whether how you are good at using those porcelains like magit or
lazygit, in the end, you will eventually have to face git cli one day.

So the same for b4. If we list these three methods equally and
simultaneously, the logic might be not that correct.

Your proposal:

           contribution workflow
                    |
    -------------------------------------
    |                 |                 |
    v                 v                 v
GitGitGadget   traditional email        b4
```

But I would frame it more like this:

           contribution workflow
                    |
        -------------------------
        |                       |
        v                       v
 GitGitGadget        traditional email workflow
                                      \
                                       \
                                       b4

For exmaple, If I am at this page the fisrt time:
    https://git-scm.com/docs/MyFirstContribution
And, I see these 3 ways, okay, I choose b4.

After installing b4 and reading some manuals, I would wonder: what's
cover letter? what's Message-ID? So after a while, I would still have to
learn those stuff and how b4 indeed optimize those complicated process.

So, to put it another way.. b4 is developed for high-level maintainers,
who are apparently familiar with traditional ways. Therefore b4 saves
their time. But for some beginers like me, I still have to know those
concepts first.

But yeah, there are definitely some people would happily accept b4 and
contribute easily. Thus, I agree this tradeoff.

--
Sent before reading v2, hope there's no conflict :-)

Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4

[Weijie Yuan]

That said, my ideas may be too nitpicking.  Overall, I do
think that introducing b4 support would be a good thing.

Thanks for the replies, and for bearing with my questions/comments.

Weijie Yuan

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Weijie Yuan]

On Wed, Jun 03, 2026 at 03:51:21PM +0800, Weijie Yuan wrote:
> On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:
> > So this quote is definitely at odds with the configuration I have
> > proposed. It's actually quite surprising to me that we recommend deep
> > threading -- I personally find it extremely hard to navigate as the
> > nesting eventually gets way too deep.
>
> Sorry I'm a little confused. The example thread at git-scm.com:
>
> https://git-scm.com/docs/MyFirstContribution#ready-to-share
>
> Isn't this actually supporting shallow nesting?
>
> > It's actually quite surprising to me that we recommend deep
> > threading -- I personally find it extremely hard to navigate as the
> > nesting eventually gets way too deep.
>
> In my understanding, deep threading == --chain-reply-to, so can you
> point out where do Git recommend deep threading? I always thought Git
> supports shallow threading.
>
> Thanks! And please forgive me if I am wrong :-)

Ah, I know you mean the deep nesting of cover letters, sorry, now I
know.

Thanks!

Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading

[Tuomas Ahola]

Patrick Steinhardt <ps@pks.im> wrote:

> The "MyFirstContribution" document recommends the use of deep threading:
> every cover letter of subsequent iterations shall be linked to the cover
> letter of the preceding version. The result of this is that eventually,
> threads with many versions are getting nested so deep that it becomes
> hard to follow.
> 
> Adapt the recommendation to instead propose shallow threading: instead
> of linking the cover letter to the previous cover letter, the user is
> supposed to always link it to the first cover letter. This still makes
> it easy to follow the iterations, but has the benefit of nesting to a
> much shallower level.
> 
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>  Documentation/MyFirstContribution.adoc | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index b9fdefce02..069020196c 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -1227,8 +1227,8 @@ Message-ID: <foo.12345.author@example.com>
>  
>  Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
>  below as well; make sure to replace it with the correct Message-ID for your
> -**previous cover letter** - that is, if you're sending v2, use the Message-ID
> -from v1; if you're sending v3, use the Message-ID from v2.
> +**first cover letter** - that is, for any subsequent version that you send,
> +always use the Message-ID from v1.
>  
>  While you're looking at the email, you should also note who is CC'd, as it's
>  common practice in the mailing list to keep all CCs on a thread. You can add
> 
> -- 
> 2.54.0.1064.gd145956f57.dirty

If we adapt this change to the guidance, let's fix also other places of the
document that talk about replying to the previous cover letter.

-----8<-----

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 069020196c..bf64a211bd 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -790,7 +790,7 @@ We can note a few things:
   v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of
   three patches in the second iteration. Each iteration is sent with a new cover
   letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
-  previous iteration (more on that below).
+  first iteration (more on that below).
 
 NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without
 _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,
@@ -1214,7 +1214,7 @@ between your last version and now, if it's something significant. You do not
 need the exact same body in your second cover letter; focus on explaining to
 reviewers the changes you've made that may not be as visible.
 
-You will also need to go and find the Message-ID of your previous cover letter.
+You will also need to go and find the Message-ID of your original cover letter.
 You can either note it when you send the first series, from the output of `git
 send-email`, or you can look it up on the
 https://lore.kernel.org/git[mailing list]. Find your cover letter in the

Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading

[Weijie Yuan]

I'm afraid there will be some chaos.

As mentioned earlier, GitGitGadget now supports deep nesting of
iterations, if b4 changes while GitGitGadget doesn't, it would be
inconsistent in the archive. So, negotiation is necessary here.

As I know, b4 can generate a cover letter containing "Changes with vn",
e.g. in [PATCH v5 00/10], there would be Changes with v4, v3, v2, v1. In
this case, it is semantically correct that the cover letter of v5 is
replying-to the cover letter of v1.

But in traditional way, it seems that the norm is put a range-diff in
the cover letter. In this case, chain-reply-to makes more sence to me:
e.g. The cover letter contains the range-diff against v2, so cover
letter v3 is pointing to cover letter v2. (I don't know whether
git format-patch accepts several --range-diff or not, but if so, I
guess it might be painful to typing several refs, or copy and paste
from previous cover letter) Therefore, if git format-patch could
generate cover letter containing all the changes with v4/v3/v2/v1 as b4
does, it would be consistent, and semantically correct to pointing to
the first cover letter.

Do we need to consider backward compatibility here? ;-)

Thanks!

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[SZEDER Gábor]

On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:
> On Wed, Jun 03, 2026 at 10:12:22AM +0800, Weijie Yuan wrote:
> > On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:
> > > Huh?  Doesn't MyFirstContribution speak *against* shallow threading?
> > >
> > > 	        [...]  make sure to replace it with the correct Message-ID for your
> > > 	**previous cover letter** - that is, if you're sending v2, use the Message-ID
> > > 	from v1; if you're sending v3, use the Message-ID from v2.
> > 
> > I don't get it. Doesn't shallow threading means every following patches
> > are replying to the cover letter? Replying to the previous one is
> > --chain-reply-to, if I'm not mistaken.
> 
> Shallow threading basically means that all patches are sent as a
> response to the current cover letter, and the current cover letter is
> always attached to the cover letter of the _first_ version.

No, in Git shallow threading means that all patches are sent as a
respose to the current cover letter, period.  It has nothing to do
with whether the current cover letter is sent as a reply to the cover
letter of the first or the previous version.

> So this quote is definitely at odds with the configuration I have
> proposed. It's actually quite surprising to me that we recommend deep
> threading -- I personally find it extremely hard to navigate as the
> nesting eventually gets way too deep.

Deep threading means that every mail is a reply to the previous one.
Again, it has nothing to do with the relation of the current cover
letter and the previous cover letters.

Therefore, we do not recommend deep threading.

> You know -- I'll include a patch that changes the wording there to also
> use shallow nesting, mostly to kick off a discussion and arrive at a
> decision there.

Re: [PATCH 1/2] b4: introduce configuration for the Git project

[Weijie Yuan]

On Wed, Jun 03, 2026 at 01:07:33PM +0200, SZEDER Gábor wrote:
> No, in Git shallow threading means that all patches are sent as a
> respose to the current cover letter, period.  It has nothing to do
> with whether the current cover letter is sent as a reply to the cover
> letter of the first or the previous version.

Thanks, agree

> Deep threading means that every mail is a reply to the previous one.
> Again, it has nothing to do with the relation of the current cover
> letter and the previous cover letters.
>
> Therefore, we do not recommend deep threading.

So the same reason with Patrick?

Thanks