.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "B4" 5 "2022-06-16" "0.9.0" "" .SH NAME B4 \- Work with code submissions in a public-inbox archive .SH SYNOPSIS .sp b4 {mbox,am,shazam,pr,diff,ty,kr} [options] .SH DESCRIPTION .sp 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. .sp 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. .SH SUBCOMMANDS .INDENT 0.0 .IP \(bu 2 \fImbox\fP: Download a thread as an mbox file .IP \(bu 2 \fIam\fP: Create an mbox file that is ready to git\-am .IP \(bu 2 \fIshazam\fP: Apply patch series to git repositories .IP \(bu 2 \fIpr\fP: Work with pull requests .IP \(bu 2 \fIdiff\fP: Show range\-diff style diffs between patch versions .IP \(bu 2 \fIty\fP: Create templated replies for processed patches and pull requests .IP \(bu 2 \fIkr\fP (EXPERIMENTAL) Operate on patatt\-compatible keyrings .IP \(bu 2 \fIattest\fP: (DEPRECATED) Add cryptographic attestation to patches .UNINDENT .SH OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .B \-d\fP,\fB \-\-debug Add more debugging info to the output (default: False) .TP .B \-q\fP,\fB \-\-quiet Output critical information only (default: False) .TP .B \-n\fP,\fB \-\-no\-interactive Do not ask any interactive questions (default: False) .UNINDENT .SH SUBCOMMAND OPTIONS .SS b4 mbox .sp 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. .INDENT 0.0 .TP .B usage: b4 mbox [\-h] [\-p USEPROJECT] [\-m LOCALMBOX] [\-C] [\-o OUTDIR] [\-c] [\-n WANTNAME] [\-M] [\-f] [msgid] .TP .B positional arguments: msgid Message ID to process, or pipe a raw message .TP .B options: .INDENT 7.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-p \ USEPROJECT\fR,\fB \ \-\-use\-project \ USEPROJECT Use a specific project instead of default (linux\-mm, linux\-hardening, etc) .TP .BI \-m \ LOCALMBOX\fR,\fB \ \-\-use\-local\-mbox \ LOCALMBOX Instead of grabbing a thread from lore, process this mbox file (or \- for stdin) .TP .B \-C\fP,\fB \-\-no\-cache Do not use local cache .TP .BI \-o \ OUTDIR\fR,\fB \ \-\-outdir \ OUTDIR Output into this directory (or use \- to output mailbox contents to stdout) .TP .B \-c\fP,\fB \-\-check\-newer\-revisions Check if newer patch revisions exist .TP .BI \-n \ WANTNAME\fR,\fB \ \-\-mbox\-name \ WANTNAME Filename to name the mbox destination .TP .B \-M\fP,\fB \-\-save\-as\-maildir Save as maildir (avoids mbox format ambiguities) .TP .B \-f\fP,\fB \-\-filter\-dupes When adding messages to existing maildir, filter out duplicates .UNINDENT .UNINDENT .sp \fIExample\fP: b4 mbox \fI\%20200313231252.64999\-1\-keescook@chromium.org\fP .SS b4 am .sp 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: .INDENT 0.0 .IP \(bu 2 pick the latest submitted version of the series (it can check for newer threads using \fB\-c\fP as well) .IP \(bu 2 check DKIM signatures and patatt attestation on all patches and code review messages .IP \(bu 2 collate all submitted code\-review trailers (Reviewed\-by, Acked\-by, etc) and put them into the commit message .IP \(bu 2 add your own Signed\-off\-by trailer (with \fB\-s\fP) .IP \(bu 2 reroll series from partial updates (e.g. someone submits a v2 of a single patch instead of rerolling the entire series) .IP \(bu 2 guess where in the tree history the patches belong, if the exact commit\-base is not specified (with \fB\-g\fP) .IP \(bu 2 prepare the tree for a 3\-way merge (with \fB\-3\fP) .IP \(bu 2 cherry\-pick a subset of patches from a large series (with \fB\-P\fP) .UNINDENT .INDENT 0.0 .TP .B 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] .TP .B positional arguments: msgid Message ID to process, or pipe a raw message .TP .B options: .INDENT 7.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-p \ USEPROJECT\fR,\fB \ \-\-use\-project \ USEPROJECT Use a specific project instead of default (linux\-mm, linux\-hardening, etc) .TP .BI \-m \ LOCALMBOX\fR,\fB \ \-\-use\-local\-mbox \ LOCALMBOX Instead of grabbing a thread from lore, process this mbox file (or \- for stdin) .TP .B \-C\fP,\fB \-\-no\-cache Do not use local cache .TP .BI \-o \ OUTDIR\fR,\fB \ \-\-outdir \ OUTDIR Output into this directory (or use \- to output mailbox contents to stdout) .TP .B \-c\fP,\fB \-\-check\-newer\-revisions Check if newer patch revisions exist .TP .BI \-n \ WANTNAME\fR,\fB \ \-\-mbox\-name \ WANTNAME Filename to name the mbox destination .TP .B \-M\fP,\fB \-\-save\-as\-maildir Save as maildir (avoids mbox format ambiguities) .TP .BI \-v \ WANTVER\fR,\fB \ \-\-use\-version \ WANTVER Get a specific version of the patch/series .TP .B \-t\fP,\fB \-\-apply\-cover\-trailers Apply trailers sent to the cover letter to all patches .TP .B \-S\fP,\fB \-\-sloppy\-trailers Apply trailers without email address match checking .TP .B \-T\fP,\fB \-\-no\-add\-trailers Do not add or sort any trailers .TP .B \-s\fP,\fB \-\-add\-my\-sob Add your own signed\-off\-by to every patch .TP .B \-l\fP,\fB \-\-add\-link Add a Link: with message\-id lookup URL to every patch .TP .BI \-P \ CHERRYPICK\fR,\fB \ \-\-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 \fIglobbing\fP" to match on commit subject) .TP .B \-\-cc\-trailers Copy all Cc\(aqd addresses into Cc: trailers .TP .B \-\-no\-parent Break thread at the msgid specified and ignore any parent messages .TP .B \-\-allow\-unicode\-control\-chars Allow unicode control characters (very rarely legitimate) .TP .B \-Q\fP,\fB \-\-quilt\-ready Save patches in a quilt\-ready folder .TP .B \-g\fP,\fB \-\-guess\-base Try to guess the base of the series (if not specified) .UNINDENT .INDENT 7.0 .TP .B \-b GUESSBRANCH [GUESSBRANCH ...], \-\-guess\-branch GUESSBRANCH [GUESSBRANCH ...] When guessing base, restrict to this branch (use with \-g) .UNINDENT .INDENT 7.0 .TP .BI \-\-guess\-lookback \ GUESSDAYS When guessing base, go back this many days from the patch date (default: 2 weeks) .TP .B \-3\fP,\fB \-\-prep\-3way Prepare for a 3\-way merge (tries to ensure that all index blobs exist by making a fake commit range) .TP .B \-\-no\-cover Do not save the cover letter (on by default when using \-o \-) .TP .B \-\-no\-partial\-reroll Do not reroll partial series when detected .UNINDENT .UNINDENT .sp \fIExample\fP: b4 am \fI\%20200313231252.64999\-1\-keescook@chromium.org\fP .SS b4 shazam .sp This is very similar to \fBb4 am\fP, but will also apply patches directly to the current git tree using \fBgit am\fP\&. Alternatively, when used with \fB\-H\fP, it can fetch the patch series into \fBFETCH_HEAD\fP 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. .sp If you want to automatically invoke git\-merge, you can use \fB\-M\fP instead of \fB\-H\fP\&. .INDENT 0.0 .TP .B 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] .TP .B positional arguments: msgid Message ID to process, or pipe a raw message .TP .B options: .INDENT 7.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-p \ USEPROJECT\fR,\fB \ \-\-use\-project \ USEPROJECT Use a specific project instead of default (linux\-mm, linux\-hardening, etc) .TP .BI \-m \ LOCALMBOX\fR,\fB \ \-\-use\-local\-mbox \ LOCALMBOX Instead of grabbing a thread from lore, process this mbox file (or \- for stdin) .TP .B \-C\fP,\fB \-\-no\-cache Do not use local cache .TP .BI \-v \ WANTVER\fR,\fB \ \-\-use\-version \ WANTVER Get a specific version of the patch/series .TP .B \-t\fP,\fB \-\-apply\-cover\-trailers Apply trailers sent to the cover letter to all patches .TP .B \-S\fP,\fB \-\-sloppy\-trailers Apply trailers without email address match checking .TP .B \-T\fP,\fB \-\-no\-add\-trailers Do not add or sort any trailers .TP .B \-s\fP,\fB \-\-add\-my\-sob Add your own signed\-off\-by to every patch .TP .B \-l\fP,\fB \-\-add\-link Add a Link: with message\-id lookup URL to every patch .TP .BI \-P \ CHERRYPICK\fR,\fB \ \-\-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 \fIglobbing\fP" to match on commit subject) .TP .B \-\-cc\-trailers Copy all Cc\(aqd addresses into Cc: trailers .TP .B \-\-no\-parent Break thread at the msgid specified and ignore any parent messages .TP .B \-\-allow\-unicode\-control\-chars Allow unicode control characters (very rarely legitimate) .TP .B \-H\fP,\fB \-\-make\-fetch\-head Attempt to treat series as a pull request and fetch it into FETCH_HEAD .TP .B \-M\fP,\fB \-\-merge Attempt to merge series as if it were a pull request (execs git\-merge) .TP .BI \-\-guess\-lookback \ GUESSDAYS (use with \-H or \-M) When guessing base, go back this many days from the patch date (default: 3 weeks) .UNINDENT .UNINDENT .sp \fIExample\fP: b4 shazam \-H \fI\%20200313231252.64999\-1\-keescook@chromium.org\fP .SS b4 attest .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBThis subcommand is deprecated and will be removed in a future version of b4.\fP .sp This functionality is now implemented via an auxiliary library called "patatt". You may instead install and use patatt directly with the same results. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B usage: b4 attest [\-h] patchfile [patchfile ...] .TP .B positional arguments: patchfile Patches to attest .UNINDENT .sp \fIExample\fP: b4 attest outgoing/*.patch .SS b4 pr .sp This command is for working with pull requests submitted using \fBgit\-request\-pull\fP\&. .INDENT 0.0 .TP .B usage: command.py pr [\-h] [\-g GITDIR] [\-b BRANCH] [\-c] [\-e] [\-o OUTMBOX] [msgid] .TP .B positional arguments: msgid Message ID to process, or pipe a raw message .TP .B optional arguments: .INDENT 7.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-g \ GITDIR\fR,\fB \ \-\-gitdir \ GITDIR Operate on this git tree instead of current dir .TP .BI \-b \ BRANCH\fR,\fB \ \-\-branch \ BRANCH Check out FETCH_HEAD into this branch after fetching .TP .B \-c\fP,\fB \-\-check Check if pull request has already been applied .TP .B \-e\fP,\fB \-\-explode Convert a pull request into an mbox full of patches .TP .BI \-o \ OUTMBOX\fR,\fB \ \-\-output\-mbox \ OUTMBOX Save exploded messages into this mailbox (default: msgid.mbx) .TP .B \-l\fP,\fB \-\-retrieve\-links Attempt to retrieve any Link: URLs (use with \-e) .TP .BI \-f \ MAILFROM\fR,\fB \ \-\-from\-addr \ MAILFROM Use this From: in exploded messages (use with \-e) .UNINDENT .UNINDENT .sp \fIExample\fP: b4 pr \fI\%202003292120.2BDCB41@keescook\fP .SS b4 ty .INDENT 0.0 .TP .B 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] .TP .B optional arguments: .INDENT 7.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-g \ GITDIR\fR,\fB \ \-\-gitdir \ GITDIR Operate on this git tree instead of current dir .TP .BI \-o \ OUTDIR\fR,\fB \ \-\-outdir \ OUTDIR Write thanks files into this dir (default=.) .TP .B \-l\fP,\fB \-\-list List pull requests and patch series you have retrieved .TP .BI \-t \ THANK_FOR\fR,\fB \ \-\-thank\-for \ THANK_FOR Generate thankyous for specific entries from \-l (e.g.: 1,3\-5,7\-; or "all") .TP .BI \-d \ DISCARD\fR,\fB \ \-\-discard \ DISCARD Discard specific messages from \-l (e.g.: 1,3\-5,7\-; or "all") .TP .B \-a\fP,\fB \-\-auto Use the Auto\-Thankanator gun to figure out what got applied/merged .TP .BI \-b \ BRANCH\fR,\fB \ \-\-branch \ BRANCH The branch to check against, instead of current .TP .BI \-\-since \ SINCE The \-\-since option to use when auto\-matching patches (default=1.week) .TP .B \-S\fP,\fB \-\-send\-email Send email instead of writing out .thanks files .TP .B \-\-dry\-run Print out emails instead of sending them .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To send mails directly using \-S, you should have a configured [sendemail] section somewhere in your applicable git configuration files (global or in\-tree). .UNINDENT .UNINDENT .sp \fIExample\fP: b4 ty \-aS \-\-dry\-run .SS b4 diff .INDENT 0.0 .TP .B usage: b4 diff [\-h] [\-g GITDIR] [\-p USEPROJECT] [\-C] [\-v WANTVERS [WANTVERS ...]] [\-n] [\-o OUTDIFF] [\-c] [\-m AMBOX AMBOX] [msgid] .TP .B positional arguments: msgid Message ID to process, pipe a raw message, or use \-m .UNINDENT .sp optional arguments: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-g \ GITDIR\fR,\fB \ \-\-gitdir \ GITDIR Operate on this git tree instead of current dir .TP .BI \-p \ USEPROJECT\fR,\fB \ \-\-use\-project \ USEPROJECT Use a specific project instead of guessing (linux\-mm, linux\-hardening, etc) .TP .B \-C\fP,\fB \-\-no\-cache Do not use local cache .UNINDENT .INDENT 0.0 .TP .B \-v WANTVERS [WANTVERS ...], \-\-compare\-versions WANTVERS [WANTVERS ...] Compare specific versions instead of latest and one before that, e.g. \-v 3 5 .UNINDENT .INDENT 0.0 .TP .B \-n\fP,\fB \-\-no\-diff Do not generate a diff, just show the command to do it .TP .BI \-o \ OUTDIFF\fR,\fB \ \-\-output\-diff \ OUTDIFF Save diff into this file instead of outputting to stdout .TP .B \-c\fP,\fB \-\-color Force color output even when writing to file .UNINDENT .INDENT 0.0 .TP .B \-m AMBOX AMBOX, \-\-compare\-am\-mboxes AMBOX AMBOX Compare two mbx files prepared with "b4 am" .UNINDENT .UNINDENT .UNINDENT .sp \fIExample\fP: b4 diff \fI\%20200526205322.23465\-1\-mic@digikod.net\fP .SS b4 kr .INDENT 0.0 .TP .B usage: b4 kr [\-h] [\-p USEPROJECT] [\-m LOCALMBOX] [\-C] [\-\-show\-keys] [msgid] .TP .B positional arguments: msgid Message ID to process, or pipe a raw message .TP .B optional arguments: .INDENT 7.0 .TP .B \-h\fP,\fB \-\-help show this help message and exit .TP .BI \-p \ USEPROJECT\fR,\fB \ \-\-use\-project \ USEPROJECT Use a specific project instead of guessing (linux\-mm, linux\-hardening, etc) .TP .BI \-m \ LOCALMBOX\fR,\fB \ \-\-use\-local\-mbox \ LOCALMBOX Instead of grabbing a thread from lore, process this mbox file (or \- for stdin) .TP .B \-C\fP,\fB \-\-no\-cache Do not use local cache .TP .B \-\-show\-keys Show all developer keys from the thread .UNINDENT .UNINDENT .sp \fIExample\fP: b4 kr \-\-show\-keys \fI\%20210521184811.617875\-1\-konstantin@linuxfoundation.org\fP .SH CONFIGURATION .sp 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. .sp Default configuration, with explanations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [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\(aqll use what we find in # git\-config for gpg.program; and if that\(aqs not set, # we\(aqll 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, example@example.com .ft P .fi .UNINDENT .UNINDENT .SH PROXYING REQUESTS .sp Commands making remote HTTP requests may be configured to use a proxy by setting the \fBHTTPS_PROXY\fP environment variable, as described in \fI\%https://docs.python\-requests.org/en/latest/user/advanced/#proxies\fP\&. .SH SUPPORT .sp Please email \fI\%tools@linux.kernel.org\fP with support requests, or browse the list archive at \fI\%https://lore.kernel.org/tools\fP\&. .SH AUTHOR mricon@kernel.org License: GPLv2+ .SH COPYRIGHT The Linux Foundation and contributors .\" Generated by docutils manpage writer. .