B4
==
----------------------------------------------------
Work with code submissions in a public-inbox archive
----------------------------------------------------

:Author:    mricon@kernel.org
: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)

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