A tool to work with public-inbox and patch archives
Project description
- Date:
- 2024-02-15
- Copyright:
- The Linux Foundation and contributors
- License:
GPLv2+
- Version:
- 0.13.0
- Manual section:
5
SYNOPSIS
b4 {mbox,am,shazam,pr,diff,ty,kr,prep,send,trailers} [options]
DESCRIPTION
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/.
SUBCOMMANDS
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
OPTIONS
- -h, --help
show this help message and exit
- -d, --debug
Add more debugging info to the output (default: False)
- -q, --quiet
Output critical information only (default: False)
- -n, --no-interactive
Do not ask any interactive questions (default: False)
- --offline-mode
Do not perform any network queries (default: False)
- --no-stdin
Disable TTY detection for stdin (default: False)
SUBCOMMAND OPTIONS
b4 mbox
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.
- usage:
b4 mbox [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR] [-c] [-n WANTNAME] [-M] [-f] [msgid]
- positional arguments:
msgid Message ID to process, or pipe a raw message
- options:
- -h, --help
show this help message and exit
- -p USEPROJECT, --use-project USEPROJECT
Use a specific project instead of default (linux-mm, linux-hardening, etc)
- -m LOCALMBOX, --use-local-mbox LOCALMBOX
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
- --stdin-pipe-sep STDIN_PIPE_SEP
When accepting messages on stdin, split using this pipe separator string
- -C, --no-cache
Do not use local cache
- --single-message
Only retrieve the message matching the msgid and ignore the rest of the thread
- -o OUTDIR, --outdir OUTDIR
Output into this directory (or use - to output mailbox contents to stdout)
- -c, --check-newer-revisions
Check if newer patch revisions exist
- -n WANTNAME, --mbox-name WANTNAME
Filename to name the mbox destination
- -M, --save-as-maildir
Save as maildir (avoids mbox format ambiguities)
- -f, --filter-dupes
When adding messages to existing maildir, filter out duplicates
- -r MBOX, --refetch MBOX
Refetch all messages in specified mbox with their original headers
Example: b4 mbox 20200313231252.64999-1-keescook@chromium.org
b4 am
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)
- usage:
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]
- positional arguments:
msgid Message ID to process, or pipe a raw message
- options:
- -h, --help
show this help message and exit
- -p USEPROJECT, --use-project USEPROJECT
Use a specific project instead of default (linux-mm, linux-hardening, etc)
- -m LOCALMBOX, --use-local-mbox LOCALMBOX
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
- --stdin-pipe-sep STDIN_PIPE_SEP
When accepting messages on stdin, split using this pipe separator string
- -C, --no-cache
Do not use local cache
- --single-message
Only retrieve the message matching the msgid and ignore the rest of the thread
- -o OUTDIR, --outdir OUTDIR
Output into this directory (or use - to output mailbox contents to stdout)
- -c, --check-newer-revisions
Check if newer patch revisions exist
- -n WANTNAME, --mbox-name WANTNAME
Filename to name the mbox destination
- -M, --save-as-maildir
Save as maildir (avoids mbox format ambiguities)
- --single-message
Only retrieve the message matching the msgid and ignore the rest of the thread
- -v WANTVER, --use-version WANTVER
Get a specific version of the patch/series
- -S, --sloppy-trailers
Apply trailers without email address match checking
- -T, --no-add-trailers
Do not add or sort any trailers
- -s, --add-my-sob
Add your own signed-off-by to every patch
- -l, --add-link
Add a Link: with message-id lookup URL to every patch
- -P CHERRYPICK, --cherry-pick CHERRYPICK
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)
- --cc-trailers
Copy all Cc’d addresses into Cc: trailers
- --no-parent
Break thread at the msgid specified and ignore any parent messages
- --allow-unicode-control-chars
Allow unicode control characters (very rarely legitimate)
- -Q, --quilt-ready
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)
- --guess-lookback GUESSDAYS
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)
- --no-cover
Do not save the cover letter (on by default when using -o -)
- --no-partial-reroll
Do not reroll partial series when detected
Example: b4 am 20200313231252.64999-1-keescook@chromium.org
b4 shazam
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.
- usage:
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]
- positional arguments:
msgid Message ID to process, or pipe a raw message
- options:
- -h, --help
show this help message and exit
- -p USEPROJECT, --use-project USEPROJECT
Use a specific project instead of default (linux-mm, linux-hardening, etc)
- -m LOCALMBOX, --use-local-mbox LOCALMBOX
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
- --stdin-pipe-sep STDIN_PIPE_SEP
When accepting messages on stdin, split using this pipe separator string
- -C, --no-cache
Do not use local cache
- --single-message
Only retrieve the message matching the msgid and ignore the rest of the thread
- -v WANTVER, --use-version WANTVER
Get a specific version of the patch/series
- -S, --sloppy-trailers
Apply trailers without email address match checking
- -T, --no-add-trailers
Do not add or sort any trailers
- -s, --add-my-sob
Add your own signed-off-by to every patch
- -l, --add-link
Add a Link: with message-id lookup URL to every patch
- -P CHERRYPICK, --cherry-pick CHERRYPICK
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)
- --cc-trailers
Copy all Cc’d addresses into Cc: trailers
- --no-parent
Break thread at the msgid specified and ignore any parent messages
- --allow-unicode-control-chars
Allow unicode control characters (very rarely legitimate)
- -H, --make-fetch-head
Attempt to treat series as a pull request and fetch it into FETCH_HEAD
- -M, --merge
Attempt to merge series as if it were a pull request (execs git-merge)
- --guess-lookback GUESSDAYS
(use with -H or -M) When guessing base, go back this many days from the patch date (default: 3 weeks)
- --merge-base COMMIT
(use with -H or -M) Force this base when merging
Example: b4 shazam -H 20200313231252.64999-1-keescook@chromium.org
b4 pr
This command is for working with pull requests submitted using git-request-pull.
- usage:
b4 pr [-h] [-g GITDIR] [-b BRANCH] [-c] [-e] [-o OUTMBOX] [msgid]
- positional arguments:
msgid Message ID to process, or pipe a raw message
- optional arguments:
- -h, --help
show this help message and exit
- -g GITDIR, --gitdir GITDIR
Operate on this git tree instead of current dir
- -b BRANCH, --branch BRANCH
Check out FETCH_HEAD into this branch after fetching
- -c, --check
Check if pull request has already been applied
- -e, --explode
Convert a pull request into an mbox full of patches
- -o OUTMBOX, --output-mbox OUTMBOX
Save exploded messages into this mailbox (default: msgid.mbx)
- -f MAILFROM, --from-addr MAILFROM
Use this From: in exploded messages (use with -e)
Example: b4 pr 202003292120.2BDCB41@keescook
b4 ty
- usage:
b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-t THANK_FOR [THANK_FOR …]] [-d DISCARD [DISCARD …]] [-a] [-b BRANCH] [–since SINCE] [-S] [–dry-run]
- optional arguments:
- -h, --help
show this help message and exit
- -g GITDIR, --gitdir GITDIR
Operate on this git tree instead of current dir
- -o OUTDIR, --outdir OUTDIR
Write thanks files into this dir (default=.)
- -l, --list
List pull requests and patch series you have retrieved
- -t THANK_FOR, --thank-for THANK_FOR
Generate thankyous for specific entries from -l (e.g.: 1,3-5,7-; or “all”)
- -d DISCARD, --discard DISCARD
Discard specific messages from -l (e.g.: 1,3-5,7-; or “all”)
- -a, --auto
Use the Auto-Thankanator gun to figure out what got applied/merged
- -b BRANCH, --branch BRANCH
The branch to check against, instead of current
- --since SINCE
The –since option to use when auto-matching patches (default=1.week)
- -S, --send-email
Send email instead of writing out .thanks files
- --dry-run
Print out emails instead of sending them
- --pw-set-state PW_STATE
Set this patchwork state instead of default (use with -a, -t or -d)
Example: b4 ty -aS –dry-run
b4 diff
- usage:
b4 diff [-h] [-g GITDIR] [-p USEPROJECT] [-C] [-v WANTVERS [WANTVERS …]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid]
- positional arguments:
msgid Message ID to process, pipe a raw message, or use -m
optional arguments:
- -h, --help
show this help message and exit
- -g GITDIR, --gitdir GITDIR
Operate on this git tree instead of current dir
- -p USEPROJECT, --use-project USEPROJECT
Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
- -C, --no-cache
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
- -o OUTDIFF, --output-diff OUTDIFF
Save diff into this file instead of outputting to stdout
- -c, --color
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
- usage:
b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [–show-keys] [msgid]
- positional arguments:
msgid Message ID to process, or pipe a raw message
- optional arguments:
- -h, --help
show this help message and exit
- -p USEPROJECT, --use-project USEPROJECT
Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
- -m LOCALMBOX, --use-local-mbox LOCALMBOX
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
- --stdin-pipe-sep STDIN_PIPE_SEP
When accepting messages on stdin, split using this pipe separator string
- -C, --no-cache
Do not use local cache
- --show-keys
Show all developer keys from the thread
Example: b4 kr –show-keys 20210521184811.617875-1-konstantin@linuxfoundation.org
b4 prep
- usage:
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]
- options:
- -h, --help
show this help message and exit
- -c, --auto-to-cc
Automatically populate cover letter trailers with To and Cc addresses
- -p OUTPUT_DIR, --format-patch OUTPUT_DIR
Output prep-tracked commits as patches
- --edit-cover
Edit the cover letter in your defined $EDITOR (or core.editor)
- --show-revision
Show current series revision number
- --force-revision N
Force revision to be this number instead
- --compare-to vN
Display a range-diff to previously sent revision N
- --manual-reroll COVER_MSGID
Mark current revision as sent and reroll (requires cover letter msgid)
- –set-prefixes PREFIX [PREFIX …]
Extra prefixes to add to [PATCH] (e.g.: RFC mydrv)
- –show-info [PARAM]
Show series info in a format that can be passed to other tools
- –cleanup [BRANCHNAME]
Archive and delete obsolete prep-managed branches
- Create new branch:
Create a new branch for working on patch series
- -n NEW_SERIES_NAME, --new NEW_SERIES_NAME
Create a new branch for working on a patch series
- -f FORK_POINT, --fork-point FORK_POINT
When creating a new branch, use this fork point instead of HEAD
- -F MSGID, --from-thread MSGID
When creating a new branch, use this thread
- Enroll existing branch:
Enroll existing branch for prep work
- -e ENROLL_BASE, --enroll ENROLL_BASE
Enroll current branch, using the passed tag, branch, or commit as fork base
b4 send
- usage:
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]
- options:
- -h, --help
show this help message and exit
- -d, --dry-run
Do not send, just dump out raw smtp messages to the stdout
- –preview-to ADDR [ADDR …]
Send everything for a pre-review to specified addresses instead of actual recipients
- -o OUTPUT_DIR, --output-dir OUTPUT_DIR
Do not send, write raw messages to this directory (forces –dry-run)
- --reflect
Send everything to yourself instead of the actual recipients
- --no-trailer-to-cc
Do not add any addresses found in the cover or patch trailers to To: or Cc:
- –to ADDR [ADDR …]
Addresses to add to the To: list
- –cc ADDR [ADDR …]
Addresses to add to the Cc: list
- --not-me-too
Remove yourself from the To: or Cc: list
- –resend [vN]
Resend a previously sent version of the series
- --no-sign
Do not add the cryptographic attestation signature header
- Web submission:
Authenticate with the web submission endpoint
- --web-auth-new
Initiate a new web authentication request
- --web-auth-verify VERIFY_TOKEN
Submit the token received via verification email
b4 trailers
- usage:
b4 trailers [-h] [-u] [-S] [-F MSGID] [–since SINCE]
- options:
- -h, --help
show this help message and exit
- -u, --update
Update branch commits with latest received trailers
- -S, --sloppy-trailers
Apply trailers without email address match checking
- -F MSGID, --trailers-from MSGID
Look for trailers in the thread with this msgid instead of using the series change-id
- --since SINCE
The –since option to use with -F when auto-matching patches (default=1.month)
- -m LOCALMBOX, --use-local-mbox LOCALMBOX
Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
- --stdin-pipe-sep STDIN_PIPE_SEP
When accepting messages on stdin, split using this pipe separator string
- -C, --no-cache
Do not use local cache
CONFIGURATION
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
PROXYING REQUESTS
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.
SUPPORT
Please email tools@kernel.org with support requests, or browse the list archive at https://lore.kernel.org/tools.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.