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.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

b4.linkmask 

B4 uses this setting to construct the URL in the Link: trailers. If you want a shorter option, you can also use https://msgid.link/%s, which is an alias for lore.kernel.org.

Default: https://lore.kernel.org/%s

b4.linktrailermask 

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

New in version v0.13.

Changed in version v0.14: You can now pass the -i command-line switch instead of -l to automatically insert the Message-ID trailer.

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.midmask 

Specifies the server from where to retrieve the messages specified by their message-id.

Default: https://lore.kernel.org/%s

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.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.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

Server failover settings

B4 uses the liblore library for all access to public-inbox servers. Liblore reads its own settings from the [lore] section of git config (not [b4]). These settings are shared by all tools that use liblore, so configuring them once benefits b4 and any other liblore-based applications.

When one or more fallback origins are configured, liblore automatically retries a request on the next origin whenever a connection error, timeout, or HTTP 5xx response occurs. HTTP 4xx errors are not retried, since they indicate a missing resource rather than a server problem. Cache keys always use the canonical URL regardless of which mirror actually served the response.

Example ~/.gitconfig:

[lore]
    fallback = https://tor.lore.kernel.org
    fallback = https://sea.lore.kernel.org
    autoprobe = true
    useragentplus = 550e8400-e29b-41d4-a716-446655440000

lore.autoprobe 

When set to true, b4 probes all configured origins on the first HTTP request and reorders them by response latency, putting the fastest mirror first. Probe results are cached to disk for lore.probettl seconds so that subsequent runs are fast. Probing only makes sense when at least one lore.fallback is configured.

Default: false

New in version v0.16.

lore.fallback 

Origin URL prefix (scheme://host) of a mirror to try when the primary server is unreachable or returns a server error. This option can be specified multiple times; mirrors are tried in the order listed before falling back to the canonical server. Only the origin (scheme and host) is used — the path from the primary URL is preserved automatically.

Example:

[lore]
    fallback = https://tor.lore.kernel.org
    fallback = http://mymirror.local

Default: None

New in version v0.16.

lore.probetimeout 

Per-origin timeout in seconds for latency probes. Origins that do not respond within this time are treated as unreachable and moved to the end of the list.

Default: 5.0

New in version v0.16.

lore.probettl 

How long probe results stay valid, in seconds. After this time the cached results expire and the next request that triggers a probe performs a fresh measurement.

Default: 3600

New in version v0.16.

lore.useragentplus 

A unique identifier appended to the User-Agent header as b4/version+IDENTIFIER. This allows server operators to identify and prioritize known installations. Typically a UUID.

Example:

[lore]
    useragentplus = 550e8400-e29b-41d4-a716-446655440000

Default: None

New in version v0.16.

`am` and `shazam` settings

These settings control b4 am and b4 shazam behavior.

b4.am-perpatch-check-cmd 

The command to use when running --check. The command is run once for each patch to check. The patch file to check is piped through stdin. If this config is defined multiple times, all commands will be run. If this config is not defined and b4 finds scripts/checkpatch.pl at the top of your git tree, it uses the command shown below by default.

Default: ./scripts/checkpatch.pl -q --terse --no-summary --mailback

New in version v0.14.

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 with b4 shazam -M.

Default: --signoff

b4.shazam-merge-template 

Path to a template to use when creating a merge commit. Take the following as example content for this file:

# Lines starting with '#' will be removed before invoking git-merge
# This is the first line (title) of the merge
# ${seriestitle}: will be a cleaned up subject of the cover
#                 letter or the first patch in the series.
# ${patch_or_series}: will say "patch" if a single patch or
#                     "patch series" if more than one
Merge ${patch_or_series} "${seriestitle}"

${authorname} <${authoremail}> says:

# This will be the entirety of the cover letter minus anything
# below the "-- \n" signature line. You will almost certainly
# want to edit it down to only include the relevant info.
${covermessage}

# This will contain a lore link to the patches in question
Link: ${midurl}
# git-merge will append any additional information here, depending
# on the flags you used to invoke it (e.g. --log, --signoff, etc)

Default: None

Attestation settings

b4.attestation-check-dkim 

Controls whether to perform DKIM attestation checks.

Default: yes

b4.attestation-dns-resolvers 

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

New in version v0.14.

b4.attestation-gnupghome 

Sets GNUPGHOME before running PGP attestation checks that rely on GnuPG.

Default: None

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 fail

Default: softfail

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.gpgbin 

Full path to a different binary to use for gpg. B4 also checks the gpg.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.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 to b4 send and b4 ty. See man git-send-email for info about sendemail identities.

Default: None

b4.thanks-am-template 

Full paths to the templates to use when generating thank-you messages for contributors. Take the following as example content for this file:

# Lines starting with '#' will be removed
# You can have two different templates for responding to
# pull requests and for responding to patch series, though
# in reality the difference will probably be one word:
# "merged/pulled" vs. "applied".
# Keeping it short and sweet is preferred.
#
On ${sentdate}, ${fromname} wrote:
# quote will be limited to 5-6 lines, respecting paragraphs
${quote}

# You can also use ${branch} and ${treename} if you set
# b4.thanks-treename in your config, e.g.:
#Applied to ${treename} (${branch}), thanks!
#
# If you track multiple remotes in the same repo, then you can add
# the following values to [remote], to be loaded when you run
# b4 ty -b foo/branchname:
# [remote "foo"]
#   url = https://...
#   fetch = ...
#   b4-treename = uname/sound.git
#   b4-commit-url-mask = https://git.kernel.org/uname/sound/c/%.8s
Applied to ${branch}, thanks!

# for patch series, the summary is a list of each patch with a link
# to the commit id in your tree, so you probably want to set
# b4.thanks-commit-url-mask in gitconfig to a value like:
# [b4]
#   thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
#
# Check this page for info on convenient URL shorteners:
# https://korg.wiki.kernel.org/userdoc/git-url-shorterners
${summary}

Best regards,
-- 
# if ~/.signature exists, it will be put here, otherwise
# the contents will be "user.name <user.email>" from gitconfig
${signature}

Default: None

b4.thanks-commit-url-mask 

Used when creating summaries for b4 ty and the review TUI thank-you flow. 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.

When this option is set, the review TUI’s thank-you preview offers a Queue option that stores the message for delayed delivery. Queued messages are held until their commit URL resolves (via HTTP HEAD), so you can push your commits before the thank-you is sent. See thanks_queue for details.

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-email 

The email to use in the From: header when sending thank-you notes. By default, b4 uses user.email. For example:

thanks-from-email = thanks-bot@example.com

Default: None

New in version v0.13.

b4.thanks-from-name 

The name to use in the From: header when sending thank-you notes. By default, b4 uses user.name. For example:

thanks-from-name = Project Foo Thanks Bot

Default: None

New in version v0.13.

b4.thanks-pr-template 

Full paths to the templates to use when generating thank-you messages for contributors. Take the following as example content for this file:

# Lines starting with '#' will be removed
# You can have two different templates for responding to
# pull requests and for responding to patch series, though
# in reality the difference will probably be one word:
# "merged/pulled" vs. "applied".
# Keeping it short and sweet is preferred.
#
On ${sentdate}, ${fromname} wrote:
# quote will be limited to 5-6 lines, respecting paragraphs
${quote}

# You can also use ${branch} and ${treename} if you set
# b4.thanks-treename in your config, e.g.:
#Merged into ${treename} (${branch}), thanks!
#
# If you track multiple remotes in the same repo, then you can add
# the following values to [remote], to be loaded when you run
# b4 ty -b foo/branchname:
# [remote "foo"]
#   url = https://...
#   fetch = ...
#   b4-treename = uname/sound.git
#   b4-commit-url-mask = https://git.kernel.org/uname/sound/c/%.8s
Merged into ${branch}, thanks!

# for pull requests, the summary is a one-liner with the merge commit,
# so you probably want to set b4.thanks-commit-url-mask in gitconfig
# to a value like:
# [b4]
#   thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
#
# Check this page for info on convenient URL shorteners:
# https://korg.wiki.kernel.org/userdoc/git-url-shorterners
${summary}

Best regards,
-- 
# if ~/.signature exists, it will be put here, otherwise
# the contents will be "user.name <user.email>" from gitconfig
${signature}

Default: None

b4.thanks-treename 

Name of the tree to use in the thank-you templates.

Default: None

b4.ty-send-email 

When set, tells b4 ty to send email directly instead of writing out .thanks files.

Default: no

New in version v0.11.

`review` settings (alpha)

These settings control b4 review TUI behaviour.

Warning

b4 review is a technology preview. These configuration options may change in incompatible ways between releases.

b4.review-agent-command 

The command to invoke for AI-assisted review (triggered by the a keybinding). Both this option and b4.review-agent-prompt-path must be set for the agent feature to be available.

Default: None

New in version v0.15.

b4.review-agent-prompt-path 

Path to a file containing the prompt to use with the review agent. Both this option and b4.review-agent-command must be set for the agent feature to be available. A sample prompt is included in misc/agent-reviewer.md in the b4 source tree and can be adapted to your project’s review guidelines.

Default: None

New in version v0.15.

b4.review-default-take-method 

The default take method to pre-select in the Take dialog. Valid values are merge, linear, and cherry-pick. If not set, no method is pre-selected.

Default: None

New in version v0.15.

b4.review-no-patatt-sign 

Instructs b4 not to patatt-sign outgoing review emails (review replies, follow-up replies, and thank-you messages). This mirrors the b4.send-no-patatt-sign option for b4 send. Can also be set per-session with the --no-sign flag on b4 review tui.

Default: no

New in version v0.15.

b4.review-perpatch-check-cmd 

Command to run once per patch when CI checks are triggered (c in the tracking list). Each patch is piped to stdin as an RFC 2822 message. The command must print a JSON array of result objects to stdout (see CI check integration). If this option is defined multiple times, all commands are run. If it is not defined and b4 finds scripts/checkpatch.pl at the top of your git tree, checkpatch.pl is used automatically. When Patchwork is configured (b4.pw-url and b4.pw-project), Patchwork CI results are also fetched automatically.

The special value _builtin_checkpatch invokes the built-in checkpatch handler without forking a subprocess.

Default: None

New in version v0.15.

b4.review-series-check-cmd 

Command to run once per series when CI checks are triggered (c in the tracking list). The cover letter (or first patch if there is no cover) is piped to stdin as an RFC 2822 message. Same JSON protocol as b4.review-perpatch-check-cmd. If defined multiple times, all commands are run.

Default: None

New in version v0.15.

b4.review-target-branch 

The default target branch to use when taking patches. This is also used in the notification shown when the TUI is launched from a review branch, to tell you which branch to switch to for the tracking list. If not set, b4 falls back to master or main.

This option supports multiple values. When multiple branches are configured (e.g. sound/for-next and regulator/for-next), all of them appear in the suggestion list for the take dialog and the t keybinding in the tracking TUI. When exactly one value is configured, it is used as the automatic default; when two or more are configured, the per-series target (set via t) takes priority instead.

Default: None

New in version v0.15.

b4.review-tui-disable-mouse 

Disable mouse support in the review TUI. When set, the terminal’s native text selection works normally instead of being captured by the TUI. Can also be set per-session with --no-mouse on b4 review tui.

Default: no

New in version v0.15.

b4.sashiko-url 

Base URL of a sashiko.dev instance to use for AI-powered code review. When set, b4 automatically queries the sashiko API for review findings as part of CI checks and integrates sashiko inline review comments into the diff view. Inline comments appear attributed to sashiko.dev with a provenance link back to the sashiko web interface.

Example:

sashiko-url = https://sashiko.dev

Default: None

New in version v0.15.

Patchwork integration settings

If your project uses a patchwork server, setting these allows you to integrate your b4 workflow with patchwork.

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

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 or b4 shazam automatically set the review status of the retrieved patches. For example:

pw-review-state = under-review

Default: None

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

Contributor-oriented settings

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}: the git shortlog output for the series
${diffstat}: the git diff --stat output for the series
${range_diff}: the git 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

b4.prep-perpatch-check-cmd 

The command to use when running --check. The command is run once for each patch to check. The patch file to check is piped through stdin. If this config is defined multiple times, all commands will be run. If this config is not defined and b4 finds scripts/checkpatch.pl at the top of your git tree, it uses the command shown below by default.

Default: ./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile

New in version v0.14.

b4.prep-post-rewrite-hook 

A command to run after a successful history rewrite on a prep branch. A non-zero exit status is logged as a warning but does not undo the rewrite:

[b4]
prep-post-rewrite-hook = stg repair

Default: None

New in version v0.15.

b4.prep-pre-flight-checks 

You can use this to turn off some or all pre-flight checks that b4 runs prior to sending out patches. To cancel all checks:

[b4]
prep-pre-flight-checks = disable-all

To turn off specific checks, list each one of them, separated by comma:

[b4]
prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking

New in version v0.14.

b4.prep-pre-rewrite-hook 

A command to run before any operation that rewrites history on a prep branch (e.g. updating the cover letter, applying trailers, or enrolling with the commit strategy). If the command exits with a non-zero status, the operation is aborted. This is useful for tools like Stacked Git that maintain their own branch state:

[b4]
prep-pre-rewrite-hook = stg commit --all

Default: None

New in version v0.15.

b4.send-auto-cc-cmd 

The command to use for obtaining the list of “Cc:” recipients. The command is run once for each patch in the series. Each patch file is piped through stdin. If b4 finds scripts/get_maintainer.pl at the top of your git tree, it uses the command shown below by default.

Default: scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom

b4.send-auto-to-cmd 

The command to use for obtaining the list of “To:” recipients. The command is run once for each patch in the series. Each patch file is piped through stdin. If b4 finds scripts/get_maintainer.pl at the top of your git tree, it uses the command shown below by default.

Default: scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol

b4.send-endpoint-web 

The web submission endpoint to use. See Authenticating with the web submission endpoint.

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-prefixes 

Extra prefixes to add to [PATCH] (e.g. RFC mydrv).

This setting can be replaced for a series with b4 prep --set-prefixes.

Default: None

New in version v0.11.

b4.send-presubject 

Identifiers to include before [PATCH]. These must be enclosed with brackets. For example:

[b4]
send-presubject = "[myproject]"

This setting can be replaced for a series with b4 prep --set-presubject.

Default: None

New in version v0.15.

b4.send-same-thread 

When sending a new version of a series, send it in the same thread as the previous version. The config supports the following values:

yes, true, y: B4 sends the first message of the new series as a reply to the previous version’s cover letter.
shallow: B4 sends the first message of the new series as a reply to the first version’s cover letter.
no: B4 does not send the new version of the series in the same thread as any previous version.

Default: no

New in version v0.13.

Changed in version v0.15: Added shallow config value.

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-series-to 

A comma-separated list of addresses to always add to the “To:” header. See Prepare the list of recipients.

Default: None

To document

b4.gh-api-key : Deliberately undocumented because the feature is incomplete and poorly tested.

Configuration options

Per-project defaults

Configuration options

Core options

Server failover settings

am and shazam settings

Attestation settings

ty settings

review settings (alpha)

Patchwork integration settings

Contributor-oriented settings

To document

`am` and `shazam` settings

`ty` settings

`review` settings (alpha)