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
.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)
.UNINDENT
.SH SUBCOMMAND OPTIONS
.SS b4 mbox
.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
.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
.SH B4 SHAZAM
.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] [\-\-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
.BI \-\-guess\-lookback \ GUESSDAYS
(use with \-H) 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
usage: b4 attest [\-h] patchfile [patchfile ...]
.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 positional arguments:
patchfile             Patches to attest
.UNINDENT
.sp
\fIExample\fP: b4 attest outgoing/*.patch
.SS b4 pr
.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
.sp
usage: b4 diff [\-h] [\-g GITDIR] [\-p USEPROJECT] [\-C] [\-v WANTVERS [WANTVERS ...]] [\-n] [\-o OUTDIFF] [\-c] [\-m AMBOX AMBOX] [msgid]
.INDENT 0.0
.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
.sp
usage: b4 kr [\-h] [\-p USEPROJECT] [\-m LOCALMBOX] [\-C] [\-\-show\-keys] [msgid]
.INDENT 0.0
.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
   # 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.
.