path: root/man/b4.5

.\" 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
.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 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
   #
   # 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.
.