Package: b4
Author:mricon@kernel.orgDate:2024-02-15Copyright:The Linux Foundation and contributorsLicense:GPLv2+Version:0.13.0Manual section:5SYNOPSISb4 {mbox,am,shazam,pr,diff,ty,kr,prep,send,trailers} [options]DESCRIPTIONThis 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 onhttps://b4.docs.kernel.org/.SUBCOMMANDSMaintainer-oriented:mbox: Download a thread as an mbox fileam: Create an mbox file that is ready to git-amshazam: Apply patch series to git repositoriespr: Work with pull requestsdiff: Show range-diff style diffs between patch versionsty: Create templated replies for processed patches and pull requestskr: (EXPERIMENTAL) Operate on patatt-compatible keyringsContributor-oriented:prep: (EXPERIMENTAL) prepare your series for submissionsend: (EXPERIMENTAL) send your series for review on distribution liststrailers: (EXPERIMENTAL) retrieve and apply code-review trailersOPTIONS-h,--helpshow this help message and exit-d,--debugAdd more debugging info to the output (default: False)-q,--quietOutput critical information only (default: False)-n,--no-interactiveDo not ask any interactive questions (default: False)--offline-modeDo not perform any network queries (default: False)--no-stdinDisable TTY detection for stdin (default: False)SUBCOMMAND OPTIONSb4 mboxThis 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 messageoptions:-h,--helpshow this help message and exit-pUSEPROJECT,--use-projectUSEPROJECTUse a specific project instead of default (linux-mm, linux-hardening, etc)-mLOCALMBOX,--use-local-mboxLOCALMBOXInstead of grabbing a thread from lore, process this mbox file (or - for stdin)--stdin-pipe-sepSTDIN_PIPE_SEPWhen accepting messages on stdin, split using this pipe separator string-C,--no-cacheDo not use local cache--single-messageOnly retrieve the message matching the msgid and ignore the rest of the thread-oOUTDIR,--outdirOUTDIROutput into this directory (or use - to output mailbox contents to stdout)-c,--check-newer-revisionsCheck if newer patch revisions exist-nWANTNAME,--mbox-nameWANTNAMEFilename to name the mbox destination-M,--save-as-maildirSave as maildir (avoids mbox format ambiguities)-f,--filter-dupesWhen adding messages to existing maildir, filter out duplicates-rMBOX,--refetchMBOXRefetch all messages in specified mbox with their original headersExample: b4 mbox20200313231252.64999-1-keescook@chromium.orgb4 amThis 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-cas well)check DKIM signatures and patatt attestation on all patches and code
review messagescollate all submitted code-review trailers (Reviewed-by, Acked-by,
etc) and put them into the commit messageadd 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 messageoptions:-h,--helpshow this help message and exit-pUSEPROJECT,--use-projectUSEPROJECTUse a specific project instead of default (linux-mm, linux-hardening, etc)-mLOCALMBOX,--use-local-mboxLOCALMBOXInstead of grabbing a thread from lore, process this mbox file (or - for stdin)--stdin-pipe-sepSTDIN_PIPE_SEPWhen accepting messages on stdin, split using this pipe separator string-C,--no-cacheDo not use local cache--single-messageOnly retrieve the message matching the msgid and ignore the rest of the thread-oOUTDIR,--outdirOUTDIROutput into this directory (or use - to output mailbox contents to stdout)-c,--check-newer-revisionsCheck if newer patch revisions exist-nWANTNAME,--mbox-nameWANTNAMEFilename to name the mbox destination-M,--save-as-maildirSave as maildir (avoids mbox format ambiguities)--single-messageOnly retrieve the message matching the msgid and ignore the rest of the thread-vWANTVER,--use-versionWANTVERGet a specific version of the patch/series-S,--sloppy-trailersApply trailers without email address match checking-T,--no-add-trailersDo not add or sort any trailers-s,--add-my-sobAdd your own signed-off-by to every patch-l,--add-linkAdd a Link: with message-id lookup URL to every patch-PCHERRYPICK,--cherry-pickCHERRYPICKCherry-pick a subset of patches (e.g. “-P 1-2,4,6-”, “-P _” to use just the msgid specified, or “-Pglobbing” to match on commit subject)--cc-trailersCopy all Cc’d addresses into Cc: trailers--no-parentBreak thread at the msgid specified and ignore any parent messages--allow-unicode-control-charsAllow unicode control characters (very rarely legitimate)-Q,--quilt-readySave patches in a quilt-ready folder-g,--guess-baseTry 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-lookbackGUESSDAYSWhen guessing base, go back this many days from the patch date (default: 2 weeks)-3,--prep-3wayPrepare for a 3-way merge (tries to ensure that all index blobs exist by making a fake commit range)--no-coverDo not save the cover letter (on by default when using -o -)--no-partial-rerollDo not reroll partial series when detectedExample: b4 am20200313231252.64999-1-keescook@chromium.orgb4 shazamThis is very similar tob4 am, but will also apply patches
directly to the current git tree usinggit am. Alternatively, when
used with-H, it can fetch the patch series intoFETCH_HEADas
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-Minstead 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 messageoptions:-h,--helpshow this help message and exit-pUSEPROJECT,--use-projectUSEPROJECTUse a specific project instead of default (linux-mm, linux-hardening, etc)-mLOCALMBOX,--use-local-mboxLOCALMBOXInstead of grabbing a thread from lore, process this mbox file (or - for stdin)--stdin-pipe-sepSTDIN_PIPE_SEPWhen accepting messages on stdin, split using this pipe separator string-C,--no-cacheDo not use local cache--single-messageOnly retrieve the message matching the msgid and ignore the rest of the thread-vWANTVER,--use-versionWANTVERGet a specific version of the patch/series-S,--sloppy-trailersApply trailers without email address match checking-T,--no-add-trailersDo not add or sort any trailers-s,--add-my-sobAdd your own signed-off-by to every patch-l,--add-linkAdd a Link: with message-id lookup URL to every patch-PCHERRYPICK,--cherry-pickCHERRYPICKCherry-pick a subset of patches (e.g. “-P 1-2,4,6-”, “-P _” to use just the msgid specified, or “-Pglobbing” to match on commit subject)--cc-trailersCopy all Cc’d addresses into Cc: trailers--no-parentBreak thread at the msgid specified and ignore any parent messages--allow-unicode-control-charsAllow unicode control characters (very rarely legitimate)-H,--make-fetch-headAttempt to treat series as a pull request and fetch it into FETCH_HEAD-M,--mergeAttempt to merge series as if it were a pull request (execs git-merge)--guess-lookbackGUESSDAYS(use with -H or -M) When guessing base, go back this many days from the patch date (default: 3 weeks)--merge-baseCOMMIT(use with -H or -M) Force this base when mergingExample: b4 shazam -H20200313231252.64999-1-keescook@chromium.orgb4 prThis command is for working with pull requests submitted usinggit-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 messageoptional arguments:-h,--helpshow this help message and exit-gGITDIR,--gitdirGITDIROperate on this git tree instead of current dir-bBRANCH,--branchBRANCHCheck out FETCH_HEAD into this branch after fetching-c,--checkCheck if pull request has already been applied-e,--explodeConvert a pull request into an mbox full of patches-oOUTMBOX,--output-mboxOUTMBOXSave exploded messages into this mailbox (default: msgid.mbx)-fMAILFROM,--from-addrMAILFROMUse this From: in exploded messages (use with -e)Example: b4 pr202003292120.2BDCB41@keescookb4 tyusage: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,--helpshow this help message and exit-gGITDIR,--gitdirGITDIROperate on this git tree instead of current dir-oOUTDIR,--outdirOUTDIRWrite thanks files into this dir (default=.)-l,--listList pull requests and patch series you have retrieved-tTHANK_FOR,--thank-forTHANK_FORGenerate thankyous for specific entries from -l (e.g.: 1,3-5,7-; or “all”)-dDISCARD,--discardDISCARDDiscard specific messages from -l (e.g.: 1,3-5,7-; or “all”)-a,--autoUse the Auto-Thankanator gun to figure out what got applied/merged-bBRANCH,--branchBRANCHThe branch to check against, instead of current--sinceSINCEThe –since option to use when auto-matching patches (default=1.week)-S,--send-emailSend email instead of writing out .thanks files--dry-runPrint out emails instead of sending them--pw-set-statePW_STATESet this patchwork state instead of default (use with -a, -t or -d)NoteTo 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-runb4 diffusage: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 -moptional arguments:-h,--helpshow this help message and exit-gGITDIR,--gitdirGITDIROperate on this git tree instead of current dir-pUSEPROJECT,--use-projectUSEPROJECTUse a specific project instead of guessing (linux-mm, linux-hardening, etc)-C,--no-cacheDo 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-diffDo not generate a diff, just show the command to do it-oOUTDIFF,--output-diffOUTDIFFSave diff into this file instead of outputting to stdout-c,--colorForce color output even when writing to file-m AMBOX AMBOX, –compare-am-mboxes AMBOX AMBOXCompare two mbx files prepared with “b4 am”Example: b4 diff20200526205322.23465-1-mic@digikod.netb4 krusage:b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [–show-keys] [msgid]positional arguments:msgid                 Message ID to process, or pipe a raw messageoptional arguments:-h,--helpshow this help message and exit-pUSEPROJECT,--use-projectUSEPROJECTUse a specific project instead of guessing (linux-mm, linux-hardening, etc)-mLOCALMBOX,--use-local-mboxLOCALMBOXInstead of grabbing a thread from lore, process this mbox file (or - for stdin)--stdin-pipe-sepSTDIN_PIPE_SEPWhen accepting messages on stdin, split using this pipe separator string-C,--no-cacheDo not use local cache--show-keysShow all developer keys from the threadExample: b4 kr –show-keys20210521184811.617875-1-konstantin@linuxfoundation.orgb4 prepusage: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,--helpshow this help message and exit-c,--auto-to-ccAutomatically populate cover letter trailers with To and Cc addresses-pOUTPUT_DIR,--format-patchOUTPUT_DIROutput prep-tracked commits as patches--edit-coverEdit the cover letter in your defined $EDITOR (or core.editor)--show-revisionShow current series revision number--force-revisionNForce revision to be this number instead--compare-tovNDisplay a range-diff to previously sent revision N--manual-rerollCOVER_MSGIDMark 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 branchesCreate new branch:Create a new branch for working on patch series-nNEW_SERIES_NAME,--newNEW_SERIES_NAMECreate a new branch for working on a patch series-fFORK_POINT,--fork-pointFORK_POINTWhen creating a new branch, use this fork point instead of HEAD-FMSGID,--from-threadMSGIDWhen creating a new branch, use this threadEnroll existing branch:Enroll existing branch for prep work-eENROLL_BASE,--enrollENROLL_BASEEnroll current branch, using the passed tag, branch, or commit as fork baseb4 sendusage: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,--helpshow this help message and exit-d,--dry-runDo 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-oOUTPUT_DIR,--output-dirOUTPUT_DIRDo not send, write raw messages to this directory (forces –dry-run)--reflectSend everything to yourself instead of the actual recipients--no-trailer-to-ccDo 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-tooRemove yourself from the To: or Cc: list–resend [vN]Resend a previously sent version of the series--no-signDo not add the cryptographic attestation signature headerWeb submission:Authenticate with the web submission endpoint--web-auth-newInitiate a new web authentication request--web-auth-verifyVERIFY_TOKENSubmit the token received via verification emailb4 trailersusage:b4 trailers [-h] [-u] [-S] [-F MSGID] [–since SINCE]options:-h,--helpshow this help message and exit-u,--updateUpdate branch commits with latest received trailers-S,--sloppy-trailersApply trailers without email address match checking-FMSGID,--trailers-fromMSGIDLook for trailers in the thread with this msgid instead of using the series change-id--sinceSINCEThe –since option to use with -F when auto-matching patches (default=1.month)-mLOCALMBOX,--use-local-mboxLOCALMBOXInstead of grabbing a thread from lore, process this mbox file (or - for stdin)--stdin-pipe-sepSTDIN_PIPE_SEPWhen accepting messages on stdin, split using this pipe separator string-C,--no-cacheDo not use local cacheCONFIGURATIONB4 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 athttps://b4.docs.kernel.org/en/latest/config.htmlPROXYING REQUESTSCommands making remote HTTP requests may be configured to use a proxy by
setting theHTTPS_PROXYenvironment variable, as described inhttps://docs.python-requests.org/en/latest/user/advanced/#proxies.SUPPORTPlease emailtools@kernel.orgwith support requests, or browse the list
archive athttps://lore.kernel.org/tools.