b4 - Man Page

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

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

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

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

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)

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

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:

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

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

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

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

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