Configuration options
B4 doesn’t have a separate configuration file but uses git-config
to
retrieve a set of b4-specific settings. This means that you can have three
levels of b4 configuration:
system-wide, in
/etc/gitconfig
per-user, in
$HOME/.gitconfig
per-repo, in
somerepo/.git/config
Since the purpose of b4 is to work with git repositories, this allows
the usual fall-through configuration, with local settings specified in
.git/config
overriding the global defaults.
You can also use the command-line switch -c/--config
to override
specific options, for example:
b4 --config b4.midmask=https://some.host/%s
Per-project defaults
A project may ship their own b4 configuration file with some defaults,
located at the top-level of the git tree. If you’re not sure where a
configuration option is coming from, see if there is a .b4-config
file in the repository you’re currently using.
Configuration options
All settings are under the b4
section. For example, to set the
b4.midmask
option, add the following section to the relevant git
config file:
[b4]
midmask = https://some.host/%s
Core options
These options control many of the core features of b4.
b4.midmask
Specifies the server from where to retrieve the messages specified by their message-id.
Default:
https://lore.kernel.org/%s
b4.linkmask
B4 uses this setting to construct the URL in the
Link:
trailers. If you want a shorter option, you can also usehttps://msgid.link/%s
, which is an alias for lore.kernel.org.Default:
https://lore.kernel.org/%s
b4.searchmask
B4 uses this setting to query and retrieve threads matching specific search terms. For example, it can retrieve trailer updates using the series
change-id
identifier.Default:
https://lore.kernel.org/all/?x=m&t=1&q=%s
b4.linktrailermask
(v0.13+)Overrides the format of the
Link:
trailer, in case you want to call it something other than “Link.” For example, some projects use “Message-Id” trailers instead:linktrailermask = Message-Id: <%s>
The
%s
is the placeholder for the message-id.Default:
Link: https://lore.kernel.org/%s
b4.listid-preference
Sometimes messages with the same message-id can have different contents, because some servers modify message bodies to inject list subscription information. B4 attempts to de-duplicate the results using the
List-Id
header. You may use this parameter to specify the order of preference, using comma-separated strings with shell-style wildcard globbing.Default:
*.feeds.kernel.org, *.linux.dev,*.kernel.org,*
b4.save-maildirs
The “mbox” file format is actually several incompatible standards, such as “mboxo” vs. “mboxrd.” Setting this option can avoid potential problems by saving retrieved threads as Maildirs.
Default:
no
b4.trailer-order
This lets you control the order of trailers that get added to your own custody section of the commit message. By default, b4 applies these trailers in the order received. However, if you want to list trailers in a specific order, you can try something like:
trailer-order = link*,fixes*,acked*,reviewed*,tested*,*
The “chain of custody” is an important concept in patch-based code review process. Each “Signed-off-by” trailer indicates where the custody section of previous reviewer ends and the new one starts. Your own custody section is always between the previous-to-last “Signed-off-by” trailer, if any, and the bottom of the trailer section. For example:
Fixes: abcde (Commit info) Suggested-by: Alex Reporter <alex.reporter@example.com> Signed-off-by: Betty Developer <betty.developer@example.com> Acked-by: Chandra Acker <chandra.acker@example.com> Reviewed-by: Debby Reviewer <debby.reviewer@example.com> Signed-off-by: Ezri Submaintainer <ezri.submaintainer@example.com> Link: https://msgid.link/some@thing.foo Tested-by: Finn Tester <finn.tester@example.com> Signed-off-by: Your Name <your.name@example.com>
Your custody section is beneath “Ezri Submaintainer,” so the only trailers considered for reordering are “Link” and “Tested-by.” Your own Signed-off-by trailer is always at the bottom of your own custody section.
Default:
*
b4.trailers-ignore-from
A comma-separated list of addresses that b4 should always ignore when applying follow-up trailers. This is useful when dealing with reports generated by some automated bots. For example:
trailers-ignore-from = lkp@intel.com, someotherbot@example.org
Default:
None
b4.cache-expire
B4 caches retrieved threads for 10 minutes. This option allows tweaking the time that the cache remains valid. Many commands also allow a
--no-cache
flag to force b4 to perform remote lookups.Default:
10
shazam
settings
These settings control how b4 shazam
applies patches to your tree.
b4.shazam-am-flags
Additional flags to pass to
git am
when applying patches.Default:
None
b4.shazam-merge-flags
Additional flags to pass to
git merge
when performing a merge withb4 shazam -M
Default:
--signoff
b4.shazam-merge-template
Path to a template to use when creating a merge commit. See
shazam-merge-template.example
for an example.Default:
None
Attestation settings
b4.attestation-policy
B4 supports domain-level and end-to-end attestation of patches using the patatt library. There are four different operation modes:
off
: don’t bother checking attestation at all
softfail
: print green marks when attestation is passing and red marks when it’s failing
hardfail
: exit with an error when any attestation checks failDefault:
softfail
b4.attestation-check-dkim
Controls whether to perform DKIM attestation checks.
Default:
yes
b4.attestation-dns-resolvers
(v0.14+)You can specify your own DNS servers if you are on a company network and your OS-provided resolvers aren’t able to perform domain key lookups. For example, to use Google DNS servers:
attestation-dns-resolvers = 8.8.8.8, 8.8.4.4
Default:
None
b4.attestation-staleness-days
Ignore attestation signatures that are more than this many days old. This helps avoid a class of attacks when someone re-sends old patches that contain known security bugs.
Default:
30
b4.attestation-gnupghome
Sets
GNUPGHOME
before running PGP attestation checks that rely on GnuPG.Default:
None
b4.gpgbin
Full path to a different binary to use for
gpg
. B4 also checks thegpg.program
setting, and uses that value, if found.Default:
None
b4.keyringsrc
See
patatt
for details on how to configure keyrings. For example, you can clone the kernel.org pgp keys repository and use it for attestation:git clone https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git
Then set the following in your
~/.gitconfig
:[b4] keyringsrc = ~/path/to/pgpkeys/.keyring
Default:
None
ty
settings
b4.thanks-pr-template
,b4.thanks-am-template
Full paths to the templates to use when generating thank-you messages for contributors. See example templates provided with the project.
Default:
None
b4.thanks-commit-url-mask
Used when creating summaries for
b4 ty
, and can be a value like:thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
If not set, b4 falls back to using commit hashes.
Note
See this page for more info on convenient git.kernel.org short URLs: https://korg.docs.kernel.org/git-url-shorteners.html
Default:
None
b4.thanks-from-name
(v0.13+)The name to use in the
From:
header when sending thank-you notes. By default, b4 usesuser.name
. For example:thanks-from-name = Project Foo Thanks Bot
Default:
None
b4.thanks-from-email
(v0.13+)The email to use in the
From:
header when sending thank-you notes. By default, b4 usesuser.email
. For example:thanks-from-email = thanks-bot@example.com
Default:
None
b4.thanks-treename
Name of the tree to use in the thank-you templates.
Default:
None
b4.email-exclude
A list of addresses to always exclude from the message recipients. Expects a comma-separated list with shell-style globbing. E.g.:
email-exclude = *@codeaurora.org, *@obsolete.example.com
Default:
None
b4.sendemail-identity
The
sendemail
identity to use when sending mail directly with b4. This setting applies tob4 send
andb4 ty
. Seeman git-send-email
for info about sendemail identities.Default:
None
b4.ty-send-email
(v0.11+)When set, tells
b4 ty
to send email directly instead of writing out.thanks
files.Default:
no
Patchwork integration settings
If your project uses a patchwork server, setting these allows you to integrate your b4 workflow with patchwork.
b4.pw-url
The URL of your patchwork server. Note, that this should point at the top-level of your patchwork installation and not at the project patch listing. For example:
pw-url = https://patchwork.kernel.org/
Default:
None
b4.pw-key
The API key from your user profile to use when authenticating with the patchwork server.
Default:
None
b4.pw-project
The name of the patchwork project, exactly as seen in the URL sub-path. For example:
pw-project = linux-usb
Default:
None
b4.pw-review-state
Enabling this option makes
b4 am
orb4 shazam
automatically set the review status of the retrieved patches. For example:pw-review-state = under-review
Default:
None
b4.pw-accept-state
Enabling this option makes
b4 ty
set the status of any applied patches to the specified state. For example:pw-accept-state = accepted
Default:
None
b4.pw-discard-state
Enabling this option makes
b4 ty -d
set the status of any matching patches to the specified state. For example:pw-discard-state = rejected
Default:
None
Contributor-oriented settings
b4.send-endpoint-web
The web submission endpoint to use. See Authenticating with the web submission endpoint.
Default:
None
b4.send-series-to
A comma-separated list of addresses to always add to the “To:” header. See Prepare the list of recipients.
Default:
None
b4.send-series-cc
A comma-separated list of addresses to always add to the “Cc:” header. See Prepare the list of recipients.
Default:
None
b4.send-no-patatt-sign
Instructs b4 not to sign patches with patatt before sending them. Note, that using the web submission endpoint requires using signed patches.
Default:
no
b4.send-auto-to-cmd
The command to use for obtaining the list of “To:” recipients. Has no effect if the specified script isn’t present in the repository.
Default:
scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol
b4.send-auto-cc-cmd
The command to use for obtaining the list of Cc: recipients. Has no effect if the specified script isn’t present in the repository.
Default::
scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom
b4.send-same-thread
(v0.13+)When sending a new version of a series, send it in the same thread as the previous version. B4 sends the first message of the new series as a reply to the previous version’s cover letter.
Default:
no
b4.prep-cover-strategy
Alternative cover letter storage strategy to use, in case you don’t want to use the default
commit
strategy. See Cover letter strategies.Default:
commit
b4.prep-cover-template
Path to the template to use for the cover letter. The template supports the following tokens:
${cover}
: the content of the cover letter itself${shortlog}
: thegit shortlog
output for the series${diffstat}
: thegit diff --stat
output for the series${range_diff}
: thegit range-diff
output against the previous revision of the series${base_commit}
: the base commit of the series${change_id}
: the change-id of the series${signature}
: your signature, either from~/.signature
if found, or from your Git config
Default:
None
To document
b4.gh-api-key
Deliberately undocumented because the feature is incomplete and poorly tested.