.\" 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" "2024-06-14" "0.14.2" .SH NAME B4 \- Work with code submissions in a public-inbox archive .SH SYNOPSIS .sp b4 {mbox,am,shazam,pr,diff,ty,kr,prep,send,trailers} [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\(aqs written to make it simpler to participate in patch\-based workflows, like those used in the Linux kernel development. .sp The name \(dqb4\(dq was chosen for ease of typing and because B\-4 was the precursor to Lore and Data in the Star Trek universe. .sp Full documentation is available on \&. .SH SUBCOMMANDS .sp Maintainer\-oriented: .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 \fIty\fP: Create templated replies for processed patches and pull requests .IP \(bu 2 \fIdiff\fP: Show range\-diff style diffs between patch versions .IP \(bu 2 \fIkr\fP: (STUB) Operate on patatt\-compatible keyrings .UNINDENT .sp Contributor\-oriented: .INDENT 0.0 .IP \(bu 2 \fIprep\fP: prepare your series for submission .IP \(bu 2 \fItrailers\fP: retrieve and apply code\-review trailers .IP \(bu 2 \fIsend\fP: send your series for review on distribution lists .UNINDENT .sp For full options and what they do, please see \fBb4 \-\-help\fP and \fBb4 subcommand \-\-help\fP\&. .SS b4 mbox .sp This command allows retrieving entire threads from a remote public\-inbox instance. You can open the resulting mbox file with most mail clients for actions like replying to conversations or reviewing patch submissions. .sp You can provide the message either as a msgid, as full URL to a public\-inbox archive, or you can pipe it on stdin. .sp For options and their descriptions, see \fBb4 mbox \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 mbox [msgid]\fP Download a thread from the default public\-inbox server and save it in the current directory as a .mbox file. .TP .B \fBb4 mbox \-m ~/Mail [msgid]\fP Download a thread from your ~/Mail folder and save it in the current directlry as a .mbox file. .TP .B \fBb4 mbox \-fo ~/Mail [public\-inbox\-url]\fP Download the thread from this public\-inbox server, and add it to your existing mailbox, filtering out any dupes already in your mailbox folder. .UNINDENT .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 \(dqgit am\(dq 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 .sp Note: Unless you intend to do some preparatory work on the series before applying it to the git repository (e.g. a 3\-way merge), you should consider using \fBb4 shazam\fP to apply the retrieved series. .sp For options and their descriptions, see \fBb4 am \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 am \-sl [msgid]\fP Download a thread from the default public\-inbox server, apply any follow\-up trailers, add your own Signed\-Off\-By trailer plus a Link: trailer indicating the origin of the patch, then save the resulting \&.mbox file in the current directory ready to be applied by \(dqgit am\(dq. .TP .B \fBb4 am \-sl \-P 1\-3 [msgid]\fP Same as the previous example, but pick only patches 1,2,3 from the entire series. .TP .B \fBb4 am \-3 [msgid]\fP Download the series and prepare the local git tree for a 3\-way merge by ensuring that all index blobs exist. .TP .B \fBb4 am \-\-check [msgid]\fP Download the series and show if it passes the checks. You can specify the command using the \fBb4.am\-perpatch\-check\-cmd\fP configuration option. For the Linux kernel, the default will be the most common \fBcheckpatch.pl\fP set of options. .UNINDENT .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, ready to review and merge. B4 uses the cover letter 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\&. B4 automatically opens up the editor allowing you to edit the merge commit message. .sp Note: the \fB\-M\fP and \fB\-H\fP options work best for series that have the \fBbase\-commit\fP info matching an object in your local tree. .sp For options and their descriptions, see \fBb4 shazam \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 shazam \-sl \-M [msgid]\fP Download a thread from the default public\-inbox server, apply any follow\-up trailers, add your own Signed\-Off\-By trailer plus a Link: trailer with the origin of the patch, then merge this commit to the current git repository using the cover letter as the merge commit template. .TP .B \fBb4 shazam \-sl \-M \-\-merge\-base v6.4\-rc4 [msgid]\fP Same as the previous example, but forces the merge\-base to be the commit\-ish object provided instead of the one listed in the patch series itself. .UNINDENT .SS b4 pr .sp This command is for working with pull requests submitted using \fBgit\-request\-pull\fP\&. It provides the following benefits as opposed to using git directly: .INDENT 0.0 .IP \(bu 2 it can check if the pull is already applied before performing a git fetch .IP \(bu 2 it checks the signature on the tag or tip commit specified in the pull request .IP \(bu 2 it can track applied pull requests and send replies to submitters using \fBb4 ty\fP .UNINDENT .sp For options and their descriptions, see \fBb4 pr \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 pr [msgid]\fP Download the message with the pull\-request and apply it to the current git tree. .UNINDENT .SS b4 ty .sp If you\(aqve retrieved and applied some patches to your tree, you should be able to fire up the “auto\-thankanator”, which uses patch\-id and commit subject tracking to figure out which series from those you have retrieved you already applied to your tree. The process is usually pretty fast and fairly accurate. .sp To send mails directly using \fB\-S\fP, you should have a configured \fB[sendemail]\fP section somewhere in your applicable git configuration files. By default, \fBb4 ty\fP writes out .thanks files in the current directly that you can edit and sent out using a command like \fBmutt \-f thanks.file\fP\&. .sp For options and their descriptions, see \fBb4 ty \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 ty \-a \-S\fP Locate any retrieved series that you have applied to the current git repository and send out thanks to all members of the conversation. .TP .B \fBb4 ty \-a \-S \-\-dry\-run\fP Same as above, but instead of actually sending it out show what the message is going to be, first. .UNINDENT .SS b4 diff .sp The diff subcommand allows comparing two different revisions of the same patch series using \fBgit range\-diff\fP\&. Note, that in order to perform the range\-diff comparison, both revisions need to cleanly apply to the current tree, which may not always be possible to achieve. .sp For options and their descriptions, see \fBb4 diff \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 diff [msgid\-of\-vN]\fP Retrieves the thread matching the msgid specified and attempts to auto\-locate the previous version of the series. If successful, shows the output of \fBgit range\-diff\fP comparing the patch differences. .UNINDENT .SS b4 kr .sp This subcommand allows maintaining a local keyring of contributor keys. .sp Note: this part of b4 is under active development with improvements planned for the near future. .sp For options and their descriptions, see \fBb4 kr \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 kr \-\-show\-keys [msgid]\fP Retrieve the thread specified and show any cryptographic keys used to attest the patches. .UNINDENT .SS b4 prep, trailers, send .sp These commands allow preparing and submitting a patch series for review on the mailing list. Full documentation is available online at the following address: .sp .sp For options, see the output of \fBb4 prep \-\-help\fP, \fBb4 trailers \-\-help\fP and \fBb4 send \-\-help\fP\&. .sp \fIExamples\fP .INDENT 0.0 .TP .B \fBb4 prep \-n my\-new\-feature \-f v6.4\-rc4\fP Start a new branch, forking it from the tag \fBv6.4\-rc4\fP, and prepare it for adding more patches. .TP .B \fBb4 prep \-\-edit\-cover\fP Edit the cover letter for the current series. This step isn\(aqt required for most single\-patch submissions. .TP .B \fBb4 prep \-\-auto\-to\-cc\fP Find all addresses that need to receive a copy of the patch series submission and add them to the cover letter. .TP .B \fBb4 prep \-\-check\fP Run the configured checks on your series to identify any potential problems. For Linux kernel, this runs \fBcheckpatch.pl\fP with the recommended set of parameters. .TP .B \fBb4 send \-o /tmp/outdir\fP Generate the patches that b4 is going to send out and save them into the directory specified. This allows you to review the series before actually sending them. .TP .B \fBb4 send \-\-preview\-to [addr1@example.com addr2@example.com]\fP Send a \(dqpreview\(dq version of the series for someone to check before submitting it upstream. .TP .B \fBb4 trailers \-u\fP Retrieve any code\-review trailers provided for your series and apply them to the current branch. .UNINDENT .SH CONFIGURATION .sp B4 configuration is handled via git\-config(1), so you can store it in either the toplevel \fB$HOME/.gitconfig\fP file, or in a per\-repository \&.git/config file if your workflow changes per project. .sp To see configuration options available, see online documentation at .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 \&. .SH SUPPORT .sp Please email with support requests, or browse the list archive at \&. .SH AUTHOR mricon@kernel.org License: GPLv2+ .SH COPYRIGHT The Linux Foundation and contributors .\" Generated by docutils manpage writer. .