1B4(5) B4(5)
2
6 B4 - Work with code submissions in a public-inbox archive
7
9 b4 {mbox,am,shazam,pr,diff,ty,kr,prep,send,trailers} [options]
10
12 This is a helper utility to work with patches and pull requests made
13 available via a public-inbox archive like lore.kernel.org. It is writ‐
14 ten to make it easier to participate in a patch-based workflows, like
15 those used in the Linux kernel development.
16 The name "b4" was chosen for ease of typing and because B-4 was the
18 precursor to Lore and Data in the Star Trek universe.
19 Full documentation is available on https://b4.docs.kernel.org/.
21
23 Maintainer-oriented:
24 • mbox: Download a thread as an mbox file
26 • am: Create an mbox file that is ready to git-am
28 • shazam: Apply patch series to git repositories
30 • pr: Work with pull requests
32 • diff: Show range-diff style diffs between patch versions
34 • ty: Create templated replies for processed patches and pull requests
36 • kr: (EXPERIMENTAL) Operate on patatt-compatible keyrings
38 Contributor-oriented:
40 • prep: (EXPERIMENTAL) prepare your series for submission
42 • send: (EXPERIMENTAL) send your series for review on distribution
44 lists
45 • trailers: (EXPERIMENTAL) retrieve and apply code-review trailers
47
49 -h, --help
50 show this help message and exit
51 -d, --debug
53 Add more debugging info to the output (default: False)
54 -q, --quiet
56 Output critical information only (default: False)
57 -n, --no-interactive
59 Do not ask any interactive questions (default: False)
60
62 b4 mbox
63 This command allows retrieving entire threads from a remote public-in‐
64 box instance. The resulting mbox file can then be opened with most MUA
65 clients for actions like replying to conversations or reviewing patch
66 submissions.
67 usage: b4 mbox [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR]
69 [-c] [-n WANTNAME] [-M] [-f] [msgid]
70 positional arguments:
72 msgid Message ID to process, or pipe a raw mes‐
73 sage
74 options:
76 -h, --help
78 show this help message and exit
79 -p USEPROJECT, --use-project USEPROJECT
81 Use a specific project instead of default (linux-mm,
82 linux-hardening, etc)
83 -m LOCALMBOX, --use-local-mbox LOCALMBOX
85 Instead of grabbing a thread from lore, process this mbox
86 file (or - for stdin)
87 -C, --no-cache
89 Do not use local cache
90 -o OUTDIR, --outdir OUTDIR
92 Output into this directory (or use - to output mailbox
93 contents to stdout)
94 -c, --check-newer-revisions
96 Check if newer patch revisions exist
97 -n WANTNAME, --mbox-name WANTNAME
99 Filename to name the mbox destination
100 -M, --save-as-maildir
102 Save as maildir (avoids mbox format ambiguities)
103 -f, --filter-dupes
105 When adding messages to existing maildir, filter out du‐
106 plicates
107 Example: b4 mbox 20200313231252.64999-1-keescook@chromium.org
109 b4 am
111 This command allows retrieving threads from a public-inbox instance and
112 preparing them for applying to a git repository using the "git am" com‐
113 mand. It will automatically perform the following operations:
114 • pick the latest submitted version of the series (it can check for
116 newer threads using -c as well)
117 • check DKIM signatures and patatt attestation on all patches and code
119 review messages
120 • collate all submitted code-review trailers (Reviewed-by, Acked-by,
122 etc) and put them into the commit message
123 • add your own Signed-off-by trailer (with -s)
125 • reroll series from partial updates (e.g. someone submits a v2 of a
127 single patch instead of rerolling the entire series)
128 • guess where in the tree history the patches belong, if the exact com‐
130 mit-base is not specified (with -g)
131 • prepare the tree for a 3-way merge (with -3)
133 • cherry-pick a subset of patches from a large series (with -P)
135 usage: b4 am [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR] [-c]
137 [-n WANTNAME] [-M] [-v WANTVER] [-t] [-S] [-T] [-s] [-l] [-P
138 CHERRYPICK] [--cc-trailers] [--no-parent] [--allow-unicode-con‐
139 trol-chars] [-Q] [-g] [-b GUESSBRANCH [GUESSBRANCH ...]]
140 [--guess-lookback GUESSDAYS] [-3] [--no-cover] [--no-par‐
141 tial-reroll] [msgid]
142 positional arguments:
144 msgid Message ID to process, or pipe a raw mes‐
145 sage
146 options:
148 -h, --help
150 show this help message and exit
151 -p USEPROJECT, --use-project USEPROJECT
153 Use a specific project instead of default (linux-mm,
154 linux-hardening, etc)
155 -m LOCALMBOX, --use-local-mbox LOCALMBOX
157 Instead of grabbing a thread from lore, process this mbox
158 file (or - for stdin)
159 -C, --no-cache
161 Do not use local cache
162 -o OUTDIR, --outdir OUTDIR
164 Output into this directory (or use - to output mailbox
165 contents to stdout)
166 -c, --check-newer-revisions
168 Check if newer patch revisions exist
169 -n WANTNAME, --mbox-name WANTNAME
171 Filename to name the mbox destination
172 -M, --save-as-maildir
174 Save as maildir (avoids mbox format ambiguities)
175 -v WANTVER, --use-version WANTVER
177 Get a specific version of the patch/series
178 -t, --apply-cover-trailers
180 Apply trailers sent to the cover letter to all patches
181 -S, --sloppy-trailers
183 Apply trailers without email address match checking
184 -T, --no-add-trailers
186 Do not add or sort any trailers
187 -s, --add-my-sob
189 Add your own signed-off-by to every patch
190 -l, --add-link
192 Add a Link: with message-id lookup URL to every patch
193 -P CHERRYPICK, --cherry-pick CHERRYPICK
195 Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P
196 _" to use just the msgid specified, or "-P globbing" to
197 match on commit subject)
198 --cc-trailers
200 Copy all Cc'd addresses into Cc: trailers
201 --no-parent
203 Break thread at the msgid specified and ignore any parent
204 messages
205 --allow-unicode-control-chars
207 Allow unicode control characters (very rarely legitimate)
208 -Q, --quilt-ready
210 Save patches in a quilt-ready folder
211 -g, --guess-base
213 Try to guess the base of the series (if not specified)
214 -b GUESSBRANCH [GUESSBRANCH ...], --guess-branch GUESSBRANCH
216 [GUESSBRANCH ...]
217 When guessing base, restrict to this branch (use with -g)
218 --guess-lookback GUESSDAYS
220 When guessing base, go back this many days from the patch
221 date (default: 2 weeks)
222 -3, --prep-3way
224 Prepare for a 3-way merge (tries to ensure that all index
225 blobs exist by making a fake commit range)
226 --no-cover
228 Do not save the cover letter (on by default when using -o
229 -)
230 --no-partial-reroll
232 Do not reroll partial series when detected
233 Example: b4 am 20200313231252.64999-1-keescook@chromium.org
235 b4 shazam
237 This is very similar to b4 am, but will also apply patches directly to
238 the current git tree using git am. Alternatively, when used with -H, it
239 can fetch the patch series into FETCH_HEAD as if it were a pull re‐
240 quest, so it can be reviewed and merged. In this case, the cover letter
241 is used as a template for the merge commit.
242 If you want to automatically invoke git-merge, you can use -M instead
244 of -H.
245 usage: b4 shazam [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-v WANTVER]
247 [-t] [-S] [-T] [-s] [-l] [-P CHERRYPICK] [--cc-trailers]
248 [--no-parent] [--allow-unicode-control-chars] [-H | -M]
249 [--guess-lookback GUESSDAYS] [msgid]
250 positional arguments:
252 msgid Message ID to process, or pipe a raw mes‐
253 sage
254 options:
256 -h, --help
258 show this help message and exit
259 -p USEPROJECT, --use-project USEPROJECT
261 Use a specific project instead of default (linux-mm,
262 linux-hardening, etc)
263 -m LOCALMBOX, --use-local-mbox LOCALMBOX
265 Instead of grabbing a thread from lore, process this mbox
266 file (or - for stdin)
267 -C, --no-cache
269 Do not use local cache
270 -v WANTVER, --use-version WANTVER
272 Get a specific version of the patch/series
273 -t, --apply-cover-trailers
275 Apply trailers sent to the cover letter to all patches
276 -S, --sloppy-trailers
278 Apply trailers without email address match checking
279 -T, --no-add-trailers
281 Do not add or sort any trailers
282 -s, --add-my-sob
284 Add your own signed-off-by to every patch
285 -l, --add-link
287 Add a Link: with message-id lookup URL to every patch
288 -P CHERRYPICK, --cherry-pick CHERRYPICK
290 Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P
291 _" to use just the msgid specified, or "-P globbing" to
292 match on commit subject)
293 --cc-trailers
295 Copy all Cc'd addresses into Cc: trailers
296 --no-parent
298 Break thread at the msgid specified and ignore any parent
299 messages
300 --allow-unicode-control-chars
302 Allow unicode control characters (very rarely legitimate)
303 -H, --make-fetch-head
305 Attempt to treat series as a pull request and fetch it
306 into FETCH_HEAD
307 -M, --merge
309 Attempt to merge series as if it were a pull request (ex‐
310 ecs git-merge)
311 --guess-lookback GUESSDAYS
313 (use with -H or -M) When guessing base, go back this many
314 days from the patch date (default: 3 weeks)
315 Example: b4 shazam -H 20200313231252.64999-1-keescook@chromium.org
317 b4 pr
319 This command is for working with pull requests submitted using git-re‐
320 quest-pull.
321 usage: command.py pr [-h] [-g GITDIR] [-b BRANCH] [-c] [-e] [-o OUTM‐
323 BOX] [msgid]
324 positional arguments:
326 msgid Message ID to process, or pipe a raw mes‐
327 sage
328 optional arguments:
330 -h, --help
332 show this help message and exit
333 -g GITDIR, --gitdir GITDIR
335 Operate on this git tree instead of current dir
336 -b BRANCH, --branch BRANCH
338 Check out FETCH_HEAD into this branch after fetching
339 -c, --check
341 Check if pull request has already been applied
342 -e, --explode
344 Convert a pull request into an mbox full of patches
345 -o OUTMBOX, --output-mbox OUTMBOX
347 Save exploded messages into this mailbox (default: ms‐
348 gid.mbx)
349 -l, --retrieve-links
351 Attempt to retrieve any Link: URLs (use with -e)
352 -f MAILFROM, --from-addr MAILFROM
354 Use this From: in exploded messages (use with -e)
355 Example: b4 pr 202003292120.2BDCB41@keescook
357 b4 ty
359 usage: b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-t THANK_FOR [THANK_FOR
360 ...]] [-d DISCARD [DISCARD ...]] [-a] [-b BRANCH] [--since
361 SINCE] [-S] [--dry-run]
362 optional arguments:
364 -h, --help
366 show this help message and exit
367 -g GITDIR, --gitdir GITDIR
369 Operate on this git tree instead of current dir
370 -o OUTDIR, --outdir OUTDIR
372 Write thanks files into this dir (default=.)
373 -l, --list
375 List pull requests and patch series you have retrieved
376 -t THANK_FOR, --thank-for THANK_FOR
378 Generate thankyous for specific entries from -l (e.g.:
379 1,3-5,7-; or "all")
380 -d DISCARD, --discard DISCARD
382 Discard specific messages from -l (e.g.: 1,3-5,7-; or
383 "all")
384 -a, --auto
386 Use the Auto-Thankanator gun to figure out what got ap‐
387 plied/merged
388 -b BRANCH, --branch BRANCH
390 The branch to check against, instead of current
391 --since SINCE
393 The --since option to use when auto-matching patches (de‐
394 fault=1.week)
395 -S, --send-email
397 Send email instead of writing out .thanks files
398 --dry-run
400 Print out emails instead of sending them
401 NOTE:
403 To send mails directly using -S, you should have a configured
404 [sendemail] section somewhere in your applicable git configuration
405 files (global or in-tree).
406 Example: b4 ty -aS --dry-run
408 b4 diff
410 usage: b4 diff [-h] [-g GITDIR] [-p USEPROJECT] [-C] [-v WANTVERS
411 [WANTVERS ...]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid]
412 positional arguments:
414 msgid Message ID to process, pipe a raw message,
415 or use -m
416 optional arguments:
418 -h, --help
420 show this help message and exit
421 -g GITDIR, --gitdir GITDIR
423 Operate on this git tree instead of current dir
424 -p USEPROJECT, --use-project USEPROJECT
426 Use a specific project instead of guessing (linux-mm,
427 linux-hardening, etc)
428 -C, --no-cache
430 Do not use local cache
431 -v WANTVERS [WANTVERS ...], --compare-versions WANTVERS [WANTVERS
433 ...]
434 Compare specific versions instead of latest and one before
435 that, e.g. -v 3 5
436 -n, --no-diff
438 Do not generate a diff, just show the command to do it
439 -o OUTDIFF, --output-diff OUTDIFF
441 Save diff into this file instead of outputting to stdout
442 -c, --color
444 Force color output even when writing to file
445 -m AMBOX AMBOX, --compare-am-mboxes AMBOX AMBOX
447 Compare two mbx files prepared with "b4 am"
448 Example: b4 diff 20200526205322.23465-1-mic@digikod.net
450 b4 kr
452 usage: b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [--show-keys]
453 [msgid]
454 positional arguments:
456 msgid Message ID to process, or pipe a raw mes‐
457 sage
458 optional arguments:
460 -h, --help
462 show this help message and exit
463 -p USEPROJECT, --use-project USEPROJECT
465 Use a specific project instead of guessing (linux-mm,
466 linux-hardening, etc)
467 -m LOCALMBOX, --use-local-mbox LOCALMBOX
469 Instead of grabbing a thread from lore, process this mbox
470 file (or - for stdin)
471 -C, --no-cache
473 Do not use local cache
474 --show-keys
476 Show all developer keys from the thread
477 Example: b4 kr --show-keys
479 20210521184811.617875-1-konstantin@linuxfoundation.org
480 b4 prep
482 usage: b4 prep [-h] [-c | -p OUTPUT_DIR | --edit-cover | --show-revi‐
483 sion | --force-revision N | --manual-reroll COVER_MSGID] [-n
484 NEW_SERIES_NAME] [-f FORK_POINT] [-F MSGID] [-e ENROLL_BASE]
485 options:
487 -h, --help
489 show this help message and exit
490 -c, --auto-to-cc
492 Automatically populate cover letter trailers with To and
493 Cc addresses
494 -p OUTPUT_DIR, --format-patch OUTPUT_DIR
496 Output prep-tracked commits as patches
497 --edit-cover
499 Edit the cover letter in your defined $EDITOR (or
500 core.editor)
501 --show-revision
503 Show current series revision number
504 --force-revision N
506 Force revision to be this number instead
507 --manual-reroll COVER_MSGID
509 Mark current revision as sent and reroll (requires cover
510 letter msgid)
511 Create new branch:
513 Create a new branch for working on patch series
514 -n NEW_SERIES_NAME, --new NEW_SERIES_NAME
516 Create a new branch for working on a patch series
517 -f FORK_POINT, --fork-point FORK_POINT
519 When creating a new branch, use this fork point instead
520 of HEAD
521 -F MSGID, --from-thread MSGID
523 When creating a new branch, use this thread
524 Enroll existing branch:
526 Enroll existing branch for prep work
527 -e ENROLL_BASE, --enroll ENROLL_BASE
529 Enroll current branch, using the passed tag, branch, or
530 commit as fork base
531 b4 send
533 usage: b4 send [-h] [-d] [-o OUTPUT_DIR] [--prefixes PREFIXES [PREFIXES
534 ...]] [--no-trailer-to-cc] [--hide-cover-to-cc] [--to TO [TO
535 ...]] [--cc CC [CC ...]] [--not-me-too] [--resend RESEND]
536 [--no-sign] [--web-auth-new] [--web-auth-verify VERIFY_TOKEN]
537 options:
539 -h, --help
541 show this help message and exit
542 -d, --dry-run
544 Do not send, just dump out raw smtp messages to the std‐
545 out
546 -o OUTPUT_DIR, --output-dir OUTPUT_DIR
548 Do not send, write raw messages to this directory (forces
549 --dry-run)
550 --prefixes PREFIXES [PREFIXES ...]
552 Prefixes to add to PATCH (e.g. RFC, WIP)
553 --no-trailer-to-cc
555 Do not add any addresses found in the cover or patch
556 trailers to To: or Cc:
557 --hide-cover-to-cc
559 Hide To: and Cc: entries from the cover letter trailers
560 (but still send to them)
561 --to TO [TO ...]
563 Addresses to add to the To: list
564 --cc CC [CC ...]
566 Addresses to add to the Cc: list
567 --not-me-too
569 Remove yourself from the To: or Cc: list
570 --resend RESEND
572 Resend a previously sent version of the series
573 --no-sign
575 Do not add the cryptographic attestation signature header
576 Web submission:
578 Authenticate with the web submission endpoint
579 --web-auth-new
581 Initiate a new web authentication request
582 --web-auth-verify VERIFY_TOKEN
584 Submit the token received via verification email
585 b4 trailers
587 usage: b4 trailers [-h] [-u] [-S] [-F MSGID] [--since SINCE]
588 options:
590 -h, --help
592 show this help message and exit
593 -u, --update
595 Update branch commits with latest received trailers
596 -S, --sloppy-trailers
598 Apply trailers without email address match checking
599 -F MSGID, --trailers-from MSGID
601 Look for trailers in the thread with this msgid instead
602 of using the series change-id
603 --since SINCE
605 The --since option to use with -F when auto-matching
606 patches (default=1.month)
607
609 B4 configuration is handled via git-config(1), so you can store it in
610 either the toplevel $HOME/.gitconfig file, or in a per-repository
611 .git/config file if your workflow changes per project.
612 To see configuration options available, see online documentation at
614 https://b4.docs.kernel.org/en/latest/config.html
615
617 Commands making remote HTTP requests may be configured to use a proxy
618 by setting the HTTPS_PROXY environment variable, as described in
619 https://docs.python-requests.org/en/latest/user/advanced/#proxies.
620
622 Please email tools@linux.kernel.org with support requests, or browse
623 the list archive at https://lore.kernel.org/tools.
624
626 mricon@kernel.org
627 License: GPLv2+
629
631 The Linux Foundation and contributors
6320.10.0 2022-09-16 B4(5)