b4 0.9.1

A tool to work with public-inbox and patch archives

Author:

[e-mail]

Date:

2022-06-16

Copyright:

The Linux Foundation and contributors

License:

GPLv2+

Version:

0.9.0

Manual section:

5

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 [e-mail]

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 [e-mail]

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 [e-mail]

b4 attest

Note

This subcommand is deprecated and will be removed in a future version of b4.

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

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

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 [e-mail]

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 [e-mail]

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, [e-mail]

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 [e-mail] with support requests, or browse the list archive at https://lore.kernel.org/tools.