B4(5) B4(5)

B4 - Work with code submissions in a public-inbox archive

b4 {mbox,am,shazam,pr,diff,ty,kr,prep,send,trailers} [options]

This is a helper utility to work with patches and pull requests made available via a public-inbox archive like lore.kernel.org. It is written to make it easier to participate in a patch-based workflows, like those used in the Linux kernel development.

The name "b4" was chosen for ease of typing and because B-4 was the precursor to Lore and Data in the Star Trek universe.

Full documentation is available on https://b4.docs.kernel.org/.

Maintainer-oriented:

  • mbox: Download a thread as an mbox file
  • am: Create an mbox file that is ready to git-am
  • shazam: Apply patch series to git repositories
  • pr: Work with pull requests
  • diff: Show range-diff style diffs between patch versions
  • ty: Create templated replies for processed patches and pull requests
  • kr: (EXPERIMENTAL) Operate on patatt-compatible keyrings

Contributor-oriented:

  • prep: (EXPERIMENTAL) prepare your series for submission
  • send: (EXPERIMENTAL) send your series for review on distribution lists
  • trailers: (EXPERIMENTAL) retrieve and apply code-review trailers

show this help message and exit
-d, --debug
Add more debugging info to the output (default: False)
Output critical information only (default: False)
-n, --no-interactive
Do not ask any interactive questions (default: False)
Do not perform any network queries (default: False)
Disable TTY detection for stdin (default: False)

This command allows retrieving entire threads from a remote public-inbox instance. The resulting mbox file can then be opened with most MUA clients for actions like replying to conversations or reviewing patch submissions.

b4 mbox [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR] [-c] [-n WANTNAME] [-M] [-f] [msgid]
msgid Message ID to process, or pipe a raw message
show this help message and exit
Use a specific project instead of default (linux-mm, linux-hardening, etc)
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
When accepting messages on stdin, split using this pipe separator string
Do not use local cache
Only retrieve the message matching the msgid and ignore the rest of the thread
Output into this directory (or use - to output mailbox contents to stdout)
Check if newer patch revisions exist
Filename to name the mbox destination
Save as maildir (avoids mbox format ambiguities)
-f, --filter-dupes
When adding messages to existing maildir, filter out duplicates
Refetch all messages in specified mbox with their original headers


Example: b4 mbox 20200313231252.64999-1-keescook@chromium.org

This command allows retrieving threads from a public-inbox instance and preparing them for applying to a git repository using the "git am" command. It will automatically perform the following operations:

  • pick the latest submitted version of the series (it can check for newer threads using -c as well)
  • check DKIM signatures and patatt attestation on all patches and code review messages
  • collate all submitted code-review trailers (Reviewed-by, Acked-by, etc) and put them into the commit message
  • add your own Signed-off-by trailer (with -s)
  • reroll series from partial updates (e.g. someone submits a v2 of a single patch instead of rerolling the entire series)
  • guess where in the tree history the patches belong, if the exact commit-base is not specified (with -g)
  • prepare the tree for a 3-way merge (with -3)
  • cherry-pick a subset of patches from a large series (with -P)

b4 am [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR] [-c] [-n WANTNAME] [-M] [-v WANTVER] [-t] [-S] [-T] [-s] [-l] [-P CHERRYPICK] [--cc-trailers] [--no-parent] [--allow-unicode-control-chars] [-Q] [-g] [-b GUESSBRANCH [GUESSBRANCH ...]] [--guess-lookback GUESSDAYS] [-3] [--no-cover] [--no-partial-reroll] [msgid]
msgid Message ID to process, or pipe a raw message
show this help message and exit
Use a specific project instead of default (linux-mm, linux-hardening, etc)
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
When accepting messages on stdin, split using this pipe separator string
Do not use local cache
Only retrieve the message matching the msgid and ignore the rest of the thread
Output into this directory (or use - to output mailbox contents to stdout)
Check if newer patch revisions exist
Filename to name the mbox destination
Save as maildir (avoids mbox format ambiguities)
Only retrieve the message matching the msgid and ignore the rest of the thread
Get a specific version of the patch/series
Apply trailers without email address match checking
Do not add or sort any trailers
Add your own signed-off-by to every patch
Add a Link: with message-id lookup URL to every patch
Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P _" to use just the msgid specified, or "-P globbing" to match on commit subject)
Copy all Cc'd addresses into Cc: trailers
Break thread at the msgid specified and ignore any parent messages
Allow unicode control characters (very rarely legitimate)
Save patches in a quilt-ready folder
-g, --guess-base
Try to guess the base of the series (if not specified)

-b GUESSBRANCH [GUESSBRANCH ...], --guess-branch GUESSBRANCH [GUESSBRANCH ...]
When guessing base, restrict to this branch (use with -g)

When guessing base, go back this many days from the patch date (default: 2 weeks)
-3, --prep-3way
Prepare for a 3-way merge (tries to ensure that all index blobs exist by making a fake commit range)
Do not save the cover letter (on by default when using -o -)
Do not reroll partial series when detected


Example: b4 am 20200313231252.64999-1-keescook@chromium.org

This is very similar to b4 am, but will also apply patches directly to the current git tree using git am. Alternatively, when used with -H, it can fetch the patch series into FETCH_HEAD as if it were a pull request, so it can be reviewed and merged. In this case, the cover letter is used as a template for the merge commit.

If you want to automatically invoke git-merge, you can use -M instead of -H.

b4 shazam [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-v WANTVER] [-t] [-S] [-T] [-s] [-l] [-P CHERRYPICK] [--cc-trailers] [--no-parent] [--allow-unicode-control-chars] [-H | -M] [--guess-lookback GUESSDAYS] [msgid]
msgid Message ID to process, or pipe a raw message
show this help message and exit
Use a specific project instead of default (linux-mm, linux-hardening, etc)
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
When accepting messages on stdin, split using this pipe separator string
Do not use local cache
Only retrieve the message matching the msgid and ignore the rest of the thread
Get a specific version of the patch/series
Apply trailers without email address match checking
Do not add or sort any trailers
Add your own signed-off-by to every patch
Add a Link: with message-id lookup URL to every patch
Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P _" to use just the msgid specified, or "-P globbing" to match on commit subject)
Copy all Cc'd addresses into Cc: trailers
Break thread at the msgid specified and ignore any parent messages
Allow unicode control characters (very rarely legitimate)
Attempt to treat series as a pull request and fetch it into FETCH_HEAD
Attempt to merge series as if it were a pull request (execs git-merge)
(use with -H or -M) When guessing base, go back this many days from the patch date (default: 3 weeks)
(use with -H or -M) Force this base when merging


Example: b4 shazam -H 20200313231252.64999-1-keescook@chromium.org

This command is for working with pull requests submitted using git-request-pull.

b4 pr [-h] [-g GITDIR] [-b BRANCH] [-c] [-e] [-o OUTMBOX] [msgid]
msgid Message ID to process, or pipe a raw message
show this help message and exit
Operate on this git tree instead of current dir
Check out FETCH_HEAD into this branch after fetching
Check if pull request has already been applied
-e, --explode
Convert a pull request into an mbox full of patches
Save exploded messages into this mailbox (default: msgid.mbx)
Use this From: in exploded messages (use with -e)


Example: b4 pr 202003292120.2BDCB41@keescook

b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-t THANK_FOR [THANK_FOR ...]] [-d DISCARD [DISCARD ...]] [-a] [-b BRANCH] [--since SINCE] [-S] [--dry-run]
show this help message and exit
Operate on this git tree instead of current dir
Write thanks files into this dir (default=.)
List pull requests and patch series you have retrieved
Generate thankyous for specific entries from -l (e.g.: 1,3-5,7-; or "all")
Discard specific messages from -l (e.g.: 1,3-5,7-; or "all")
Use the Auto-Thankanator gun to figure out what got applied/merged
The branch to check against, instead of current
The --since option to use when auto-matching patches (default=1.week)
Send email instead of writing out .thanks files
Print out emails instead of sending them
Set this patchwork state instead of default (use with -a, -t or -d)


NOTE:

To send mails directly using -S, you should have a configured [sendemail] section somewhere in your applicable git configuration files (global or in-tree).


Example: b4 ty -aS --dry-run

b4 diff [-h] [-g GITDIR] [-p USEPROJECT] [-C] [-v WANTVERS [WANTVERS ...]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid]
msgid Message ID to process, pipe a raw message, or use -m

optional arguments:

show this help message and exit
Operate on this git tree instead of current dir
Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
Do not use local cache

-v WANTVERS [WANTVERS ...], --compare-versions WANTVERS [WANTVERS ...]
Compare specific versions instead of latest and one before that, e.g. -v 3 5

-n, --no-diff
Do not generate a diff, just show the command to do it
Save diff into this file instead of outputting to stdout
Force color output even when writing to file

-m AMBOX AMBOX, --compare-am-mboxes AMBOX AMBOX
Compare two mbx files prepared with "b4 am"



Example: b4 diff 20200526205322.23465-1-mic@digikod.net

b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [--show-keys] [msgid]
msgid Message ID to process, or pipe a raw message
show this help message and exit
Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
When accepting messages on stdin, split using this pipe separator string
Do not use local cache
Show all developer keys from the thread


Example: b4 kr --show-keys 20210521184811.617875-1-konstantin@linuxfoundation.org

b4 prep [-h] [-c | -p OUTPUT_DIR | --edit-cover | --show-revision | --force-revision N | --compare-to vN | --manual-reroll COVER_MSGID | --set-prefixes PREFIX [PREFIX ...] | --show-info [PARAM] ] | [ --cleanup [BRANCHNAME] ] [-n NEW_SERIES_NAME] [-f FORK_POINT] [-F MSGID] [-e ENROLL_BASE]
show this help message and exit
Automatically populate cover letter trailers with To and Cc addresses
Output prep-tracked commits as patches
Edit the cover letter in your defined $EDITOR (or core.editor)
Show current series revision number
Force revision to be this number instead
Display a range-diff to previously sent revision N
Mark current revision as sent and reroll (requires cover letter msgid)

Extra prefixes to add to [PATCH] (e.g.: RFC mydrv)
Show series info in a format that can be passed to other tools
Archive and delete obsolete prep-managed branches

Create a new branch for working on patch series
Create a new branch for working on a patch series
When creating a new branch, use this fork point instead of HEAD
When creating a new branch, use this thread

Enroll existing branch for prep work
Enroll current branch, using the passed tag, branch, or commit as fork base


b4 send [-h] [-d | -o OUTPUT_DIR | --preview-to ADDR [ADDR ...] | --reflect] [--no-trailer-to-cc] [--to ADDR [ADDR ...]] [--cc ADDR [ADDR ...]] [--not-me-too] [--resend [vN]] [--no-sign] [--web-auth-new] [--web-auth-verify VERIFY_TOKEN]
show this help message and exit
-d, --dry-run
Do not send, just dump out raw smtp messages to the stdout

Send everything for a pre-review to specified addresses instead of actual recipients

Do not send, write raw messages to this directory (forces --dry-run)
Send everything to yourself instead of the actual recipients
Do not add any addresses found in the cover or patch trailers to To: or Cc:

Addresses to add to the To: list
Addresses to add to the Cc: list

Remove yourself from the To: or Cc: list

Resend a previously sent version of the series

Do not add the cryptographic attestation signature header

Authenticate with the web submission endpoint
Initiate a new web authentication request
Submit the token received via verification email


b4 trailers [-h] [-u] [-S] [-F MSGID] [--since SINCE]
show this help message and exit
Update branch commits with latest received trailers
Apply trailers without email address match checking
Look for trailers in the thread with this msgid instead of using the series change-id
The --since option to use with -F when auto-matching patches (default=1.month)
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
When accepting messages on stdin, split using this pipe separator string
Do not use local cache


B4 configuration is handled via git-config(1), so you can store it in either the toplevel $HOME/.gitconfig file, or in a per-repository .git/config file if your workflow changes per project.

To see configuration options available, see online documentation at https://b4.docs.kernel.org/en/latest/config.html

Commands making remote HTTP requests may be configured to use a proxy by setting the HTTPS_PROXY environment variable, as described in https://docs.python-requests.org/en/latest/user/advanced/#proxies.

Please email tools@kernel.org with support requests, or browse the list archive at https://lore.kernel.org/tools.

mricon@kernel.org

License: GPLv2+

The Linux Foundation and contributors

2024-02-15 0.13.0