Skip to main content

A tool to work with public-inbox and patch archives

Project description

Author:

mricon@kernel.org

Date:
2023-01-19
License:

GPLv2+

Version:
0.12.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

-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

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

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

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

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

Show current series info in a column-parseable format

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] [–reflect] [–no-trailer-to-cc] [–to TO [TO …]] [–cc CC [CC …]] [–not-me-too] [–resend [RESEND]] [–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

-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 TO [TO …]

Addresses to add to the To: list

–cc CC [CC …]

Addresses to add to the Cc: list

--not-me-too

Remove yourself from the To: or Cc: list

–resend [RESEND]

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

b4-0.12.4.tar.gz (106.6 kB view hashes)

Uploaded source

Built Distribution

b4-0.12.4-py3-none-any.whl (103.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page