table of contents
B4(5) | B4(5) |
NAME¶
B4 - Work with code submissions in a public-inbox archive
SYNOPSIS¶
b4 {mbox,am,shazam,pr,diff,ty,kr} [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.
SUBCOMMANDS¶
- 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
- attest: (DEPRECATED) Add cryptographic attestation to patches
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)
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)
- -C, --no-cache
- Do not use local cache
- -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
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)
- -C, --no-cache
- Do not use local cache
- -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)
- -v WANTVER, --use-version WANTVER
- Get a specific version of the patch/series
- -t, --apply-cover-trailers
- Apply trailers sent to the cover letter to all patches
- -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)
- -C, --no-cache
- Do not use local cache
- -v WANTVER, --use-version WANTVER
- Get a specific version of the patch/series
- -t, --apply-cover-trailers
- Apply trailers sent to the cover letter to all patches
- -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)
Example: b4 shazam -H 20200313231252.64999-1-keescook@chromium.org
b4 attest¶
NOTE:
This functionality is now implemented via an auxiliary library called "patatt". You may instead install and use patatt directly with the same results.
- usage:
- b4 attest [-h] patchfile [patchfile ...]
- positional arguments:
- patchfile Patches to attest
Example: b4 attest outgoing/*.patch
b4 pr¶
This command is for working with pull requests submitted using git-request-pull.
- usage:
- command.py 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)
- -l, --retrieve-links
- Attempt to retrieve any Link: URLs (use with -e)
- -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
NOTE:
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)
- -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
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.
Default configuration, with explanations:
[b4]
# Where to look up threads by message id
midmask = https://lore.kernel.org/r/%s
#
# When recording Link: trailers, use this mask
linkmask = https://lore.kernel.org/r/%s
#
# When duplicate messages exist, use the following order to decide
# which list-id is likely to have the least mangled version. Default
# preference is listed below, in the order of lists most likely to
# preserve proper DKIM validation. Use shell-style globbing and
# separate multiple entries with commas. Must end with ,*
listid-preference = *.feeds.kernel.org,*.linux.dev,*.kernel.org,*
#
# Set to "yes" to save maildirs instead of mailboxes
# This will help avoid mboxo/mboxrd format inconsistencies between
# public-inbox, python, and git
save-maildirs = no
#
# When processing thread trailers, sort them in this order.
# Can use shell-globbing and must end with ,*
# Some sorting orders:
#trailer-order=link*,fixes*,cc*,reported*,suggested*,original*,co-*,tested*,reviewed*,acked*,signed-off*,*
#trailer-order = fixes*,reported*,suggested*,original*,co-*,signed-off*,tested*,reviewed*,acked*,cc*,link*,*
trailer-order = _preserve_
#
# Attestation-checking configuration parameters
# off: do not bother checking attestation
# check: print an attaboy when attestation is found
# softfail: print a warning when no attestation found
# hardfail: exit with an error when no attestation found
attestation-policy = softfail
#
# Perform DKIM attestation?
attestation-check-dkim = yes
#
# When showing attestation check results, do you like "fancy" (color, unicode)
# or simple markers?
attestation-checkmarks = fancy
#
# How long before we consider attestation to be too old?
attestation-staleness-days = 30
#
# You can point this at a non-default home dir, if you like, or leave out to
# use the OS default.
attestation-gnupghome = None
#
# If this is not set, we'll use what we find in
# git-config for gpg.program; and if that's not set,
# we'll use "gpg" and hope for the best
gpgbin = None
#
# How long to keep downloaded threads in cache (minutes)?
cache-expire = 10
# Used when creating summaries for b4 ty, and can be set to a value like
# thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
# See this page for more info on convenient git.kernel.org shorterners:
# https://korg.wiki.kernel.org/userdoc/git-url-shorterners
thanks-commit-url-mask = None
# See thanks-pr-template.example. If not set, a default template will be used.
thanks-pr-template = None
# See thanks-am-template.example. If not set, a default template will be used.
thanks-am-template = None
# additional flags to pass to "git am" when we run "b4 shazam"
shazam-am-flags = None
# additional flags to pass to "git merge" when we run "b4 shazam -M"
shazam-merge-flags = --signoff
# Used when preparing merge messages from cover letters. See shazam-merge-template.example
shazam-merge-template = None
# Use to exclude certain mail addresses from ever being added to auto-generated mail
# Separate multiple entries using comma (spaces are ignored), shell-style globbing accepted
email-exclude = *@codeaurora.org, example@example.com
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@linux.kernel.org with support requests, or browse the list archive at https://lore.kernel.org/tools.
AUTHOR¶
mricon@kernel.org
License: GPLv2+
COPYRIGHT¶
The Linux Foundation and contributors
2022-06-16 | 0.9.0 |