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 --offline-mode
62 Do not perform any network queries (default: False)
63 --no-stdin
65 Disable TTY detection for stdin (default: False)
66
68 b4 mbox
69 This command allows retrieving entire threads from a remote public-in‐
70 box instance. The resulting mbox file can then be opened with most MUA
71 clients for actions like replying to conversations or reviewing patch
72 submissions.
73 usage: b4 mbox [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR]
75 [-c] [-n WANTNAME] [-M] [-f] [msgid]
76 positional arguments:
78 msgid Message ID to process, or pipe a raw mes‐
79 sage
80 options:
82 -h, --help
84 show this help message and exit
85 -p USEPROJECT, --use-project USEPROJECT
87 Use a specific project instead of default (linux-mm,
88 linux-hardening, etc)
89 -m LOCALMBOX, --use-local-mbox LOCALMBOX
91 Instead of grabbing a thread from lore, process this mbox
92 file (or - for stdin)
93 --stdin-pipe-sep STDIN_PIPE_SEP
95 When accepting messages on stdin, split using this pipe
96 separator string
97 -C, --no-cache
99 Do not use local cache
100 -o OUTDIR, --outdir OUTDIR
102 Output into this directory (or use - to output mailbox
103 contents to stdout)
104 -c, --check-newer-revisions
106 Check if newer patch revisions exist
107 -n WANTNAME, --mbox-name WANTNAME
109 Filename to name the mbox destination
110 -M, --save-as-maildir
112 Save as maildir (avoids mbox format ambiguities)
113 -f, --filter-dupes
115 When adding messages to existing maildir, filter out du‐
116 plicates
117 -r MBOX, --refetch MBOX
119 Refetch all messages in specified mbox with their origi‐
120 nal headers
121 Example: b4 mbox 20200313231252.64999-1-keescook@chromium.org
123 b4 am
125 This command allows retrieving threads from a public-inbox instance and
126 preparing them for applying to a git repository using the "git am" com‐
127 mand. It will automatically perform the following operations:
128 • pick the latest submitted version of the series (it can check for
130 newer threads using -c as well)
131 • check DKIM signatures and patatt attestation on all patches and code
133 review messages
134 • collate all submitted code-review trailers (Reviewed-by, Acked-by,
136 etc) and put them into the commit message
137 • add your own Signed-off-by trailer (with -s)
139 • reroll series from partial updates (e.g. someone submits a v2 of a
141 single patch instead of rerolling the entire series)
142 • guess where in the tree history the patches belong, if the exact com‐
144 mit-base is not specified (with -g)
145 • prepare the tree for a 3-way merge (with -3)
147 • cherry-pick a subset of patches from a large series (with -P)
149 usage: b4 am [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR] [-c]
151 [-n WANTNAME] [-M] [-v WANTVER] [-t] [-S] [-T] [-s] [-l] [-P
152 CHERRYPICK] [--cc-trailers] [--no-parent] [--allow-unicode-con‐
153 trol-chars] [-Q] [-g] [-b GUESSBRANCH [GUESSBRANCH ...]]
154 [--guess-lookback GUESSDAYS] [-3] [--no-cover] [--no-par‐
155 tial-reroll] [msgid]
156 positional arguments:
158 msgid Message ID to process, or pipe a raw mes‐
159 sage
160 options:
162 -h, --help
164 show this help message and exit
165 -p USEPROJECT, --use-project USEPROJECT
167 Use a specific project instead of default (linux-mm,
168 linux-hardening, etc)
169 -m LOCALMBOX, --use-local-mbox LOCALMBOX
171 Instead of grabbing a thread from lore, process this mbox
172 file (or - for stdin)
173 --stdin-pipe-sep STDIN_PIPE_SEP
175 When accepting messages on stdin, split using this pipe
176 separator string
177 -C, --no-cache
179 Do not use local cache
180 -o OUTDIR, --outdir OUTDIR
182 Output into this directory (or use - to output mailbox
183 contents to stdout)
184 -c, --check-newer-revisions
186 Check if newer patch revisions exist
187 -n WANTNAME, --mbox-name WANTNAME
189 Filename to name the mbox destination
190 -M, --save-as-maildir
192 Save as maildir (avoids mbox format ambiguities)
193 -v WANTVER, --use-version WANTVER
195 Get a specific version of the patch/series
196 -t, --apply-cover-trailers
198 Apply trailers sent to the cover letter to all patches
199 -S, --sloppy-trailers
201 Apply trailers without email address match checking
202 -T, --no-add-trailers
204 Do not add or sort any trailers
205 -s, --add-my-sob
207 Add your own signed-off-by to every patch
208 -l, --add-link
210 Add a Link: with message-id lookup URL to every patch
211 -P CHERRYPICK, --cherry-pick CHERRYPICK
213 Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P
214 _" to use just the msgid specified, or "-P globbing" to
215 match on commit subject)
216 --cc-trailers
218 Copy all Cc'd addresses into Cc: trailers
219 --no-parent
221 Break thread at the msgid specified and ignore any parent
222 messages
223 --allow-unicode-control-chars
225 Allow unicode control characters (very rarely legitimate)
226 -Q, --quilt-ready
228 Save patches in a quilt-ready folder
229 -g, --guess-base
231 Try to guess the base of the series (if not specified)
232 -b GUESSBRANCH [GUESSBRANCH ...], --guess-branch GUESSBRANCH
234 [GUESSBRANCH ...]
235 When guessing base, restrict to this branch (use with -g)
236 --guess-lookback GUESSDAYS
238 When guessing base, go back this many days from the patch
239 date (default: 2 weeks)
240 -3, --prep-3way
242 Prepare for a 3-way merge (tries to ensure that all index
243 blobs exist by making a fake commit range)
244 --no-cover
246 Do not save the cover letter (on by default when using -o
247 -)
248 --no-partial-reroll
250 Do not reroll partial series when detected
251 Example: b4 am 20200313231252.64999-1-keescook@chromium.org
253 b4 shazam
255 This is very similar to b4 am, but will also apply patches directly to
256 the current git tree using git am. Alternatively, when used with -H, it
257 can fetch the patch series into FETCH_HEAD as if it were a pull re‐
258 quest, so it can be reviewed and merged. In this case, the cover letter
259 is used as a template for the merge commit.
260 If you want to automatically invoke git-merge, you can use -M instead
262 of -H.
263 usage: b4 shazam [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-v WANTVER]
265 [-t] [-S] [-T] [-s] [-l] [-P CHERRYPICK] [--cc-trailers]
266 [--no-parent] [--allow-unicode-control-chars] [-H | -M]
267 [--guess-lookback GUESSDAYS] [msgid]
268 positional arguments:
270 msgid Message ID to process, or pipe a raw mes‐
271 sage
272 options:
274 -h, --help
276 show this help message and exit
277 -p USEPROJECT, --use-project USEPROJECT
279 Use a specific project instead of default (linux-mm,
280 linux-hardening, etc)
281 -m LOCALMBOX, --use-local-mbox LOCALMBOX
283 Instead of grabbing a thread from lore, process this mbox
284 file (or - for stdin)
285 --stdin-pipe-sep STDIN_PIPE_SEP
287 When accepting messages on stdin, split using this pipe
288 separator string
289 -C, --no-cache
291 Do not use local cache
292 -v WANTVER, --use-version WANTVER
294 Get a specific version of the patch/series
295 -t, --apply-cover-trailers
297 Apply trailers sent to the cover letter to all patches
298 -S, --sloppy-trailers
300 Apply trailers without email address match checking
301 -T, --no-add-trailers
303 Do not add or sort any trailers
304 -s, --add-my-sob
306 Add your own signed-off-by to every patch
307 -l, --add-link
309 Add a Link: with message-id lookup URL to every patch
310 -P CHERRYPICK, --cherry-pick CHERRYPICK
312 Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P
313 _" to use just the msgid specified, or "-P globbing" to
314 match on commit subject)
315 --cc-trailers
317 Copy all Cc'd addresses into Cc: trailers
318 --no-parent
320 Break thread at the msgid specified and ignore any parent
321 messages
322 --allow-unicode-control-chars
324 Allow unicode control characters (very rarely legitimate)
325 -H, --make-fetch-head
327 Attempt to treat series as a pull request and fetch it
328 into FETCH_HEAD
329 -M, --merge
331 Attempt to merge series as if it were a pull request (ex‐
332 ecs git-merge)
333 --guess-lookback GUESSDAYS
335 (use with -H or -M) When guessing base, go back this many
336 days from the patch date (default: 3 weeks)
337 Example: b4 shazam -H 20200313231252.64999-1-keescook@chromium.org
339 b4 pr
341 This command is for working with pull requests submitted using git-re‐
342 quest-pull.
343 usage: command.py pr [-h] [-g GITDIR] [-b BRANCH] [-c] [-e] [-o OUTM‐
345 BOX] [msgid]
346 positional arguments:
348 msgid Message ID to process, or pipe a raw mes‐
349 sage
350 optional arguments:
352 -h, --help
354 show this help message and exit
355 -g GITDIR, --gitdir GITDIR
357 Operate on this git tree instead of current dir
358 -b BRANCH, --branch BRANCH
360 Check out FETCH_HEAD into this branch after fetching
361 -c, --check
363 Check if pull request has already been applied
364 -e, --explode
366 Convert a pull request into an mbox full of patches
367 -o OUTMBOX, --output-mbox OUTMBOX
369 Save exploded messages into this mailbox (default: ms‐
370 gid.mbx)
371 -l, --retrieve-links
373 Attempt to retrieve any Link: URLs (use with -e)
374 -f MAILFROM, --from-addr MAILFROM
376 Use this From: in exploded messages (use with -e)
377 Example: b4 pr 202003292120.2BDCB41@keescook
379 b4 ty
381 usage: b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-t THANK_FOR [THANK_FOR
382 ...]] [-d DISCARD [DISCARD ...]] [-a] [-b BRANCH] [--since
383 SINCE] [-S] [--dry-run]
384 optional arguments:
386 -h, --help
388 show this help message and exit
389 -g GITDIR, --gitdir GITDIR
391 Operate on this git tree instead of current dir
392 -o OUTDIR, --outdir OUTDIR
394 Write thanks files into this dir (default=.)
395 -l, --list
397 List pull requests and patch series you have retrieved
398 -t THANK_FOR, --thank-for THANK_FOR
400 Generate thankyous for specific entries from -l (e.g.:
401 1,3-5,7-; or "all")
402 -d DISCARD, --discard DISCARD
404 Discard specific messages from -l (e.g.: 1,3-5,7-; or
405 "all")
406 -a, --auto
408 Use the Auto-Thankanator gun to figure out what got ap‐
409 plied/merged
410 -b BRANCH, --branch BRANCH
412 The branch to check against, instead of current
413 --since SINCE
415 The --since option to use when auto-matching patches (de‐
416 fault=1.week)
417 -S, --send-email
419 Send email instead of writing out .thanks files
420 --dry-run
422 Print out emails instead of sending them
423 --pw-set-state PW_STATE
425 Set this patchwork state instead of default (use with -a,
426 -t or -d)
427 NOTE:
429 To send mails directly using -S, you should have a configured
430 [sendemail] section somewhere in your applicable git configuration
431 files (global or in-tree).
432 Example: b4 ty -aS --dry-run
434 b4 diff
436 usage: b4 diff [-h] [-g GITDIR] [-p USEPROJECT] [-C] [-v WANTVERS
437 [WANTVERS ...]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid]
438 positional arguments:
440 msgid Message ID to process, pipe a raw message,
441 or use -m
442 optional arguments:
444 -h, --help
446 show this help message and exit
447 -g GITDIR, --gitdir GITDIR
449 Operate on this git tree instead of current dir
450 -p USEPROJECT, --use-project USEPROJECT
452 Use a specific project instead of guessing (linux-mm,
453 linux-hardening, etc)
454 -C, --no-cache
456 Do not use local cache
457 -v WANTVERS [WANTVERS ...], --compare-versions WANTVERS [WANTVERS
459 ...]
460 Compare specific versions instead of latest and one before
461 that, e.g. -v 3 5
462 -n, --no-diff
464 Do not generate a diff, just show the command to do it
465 -o OUTDIFF, --output-diff OUTDIFF
467 Save diff into this file instead of outputting to stdout
468 -c, --color
470 Force color output even when writing to file
471 -m AMBOX AMBOX, --compare-am-mboxes AMBOX AMBOX
473 Compare two mbx files prepared with "b4 am"
474 Example: b4 diff 20200526205322.23465-1-mic@digikod.net
476 b4 kr
478 usage: b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [--show-keys]
479 [msgid]
480 positional arguments:
482 msgid Message ID to process, or pipe a raw mes‐
483 sage
484 optional arguments:
486 -h, --help
488 show this help message and exit
489 -p USEPROJECT, --use-project USEPROJECT
491 Use a specific project instead of guessing (linux-mm,
492 linux-hardening, etc)
493 -m LOCALMBOX, --use-local-mbox LOCALMBOX
495 Instead of grabbing a thread from lore, process this mbox
496 file (or - for stdin)
497 --stdin-pipe-sep STDIN_PIPE_SEP
499 When accepting messages on stdin, split using this pipe
500 separator string
501 -C, --no-cache
503 Do not use local cache
504 --show-keys
506 Show all developer keys from the thread
507 Example: b4 kr --show-keys
509 20210521184811.617875-1-konstantin@linuxfoundation.org
510 b4 prep
512 usage: b4 prep [-h] [-c | -p OUTPUT_DIR | --edit-cover | --show-revi‐
513 sion | --force-revision N | --compare-to vN | --manual-reroll
514 COVER_MSGID | --set-prefixes PREFIX [PREFIX ...] | --show-info ]
515 [-n NEW_SERIES_NAME] [-f FORK_POINT] [-F MSGID] [-e ENROLL_BASE]
516 options:
518 -h, --help
520 show this help message and exit
521 -c, --auto-to-cc
523 Automatically populate cover letter trailers with To and
524 Cc addresses
525 -p OUTPUT_DIR, --format-patch OUTPUT_DIR
527 Output prep-tracked commits as patches
528 --edit-cover
530 Edit the cover letter in your defined $EDITOR (or
531 core.editor)
532 --show-revision
534 Show current series revision number
535 --force-revision N
537 Force revision to be this number instead
538 --compare-to vN
540 Display a range-diff to previously sent revision N
541 --manual-reroll COVER_MSGID
543 Mark current revision as sent and reroll (requires cover
544 letter msgid)
545 --set-prefixes PREFIX [PREFIX ...]
547 Extra prefixes to add to [PATCH] (e.g.: RFC mydrv)
548 --show-info
550 Show current series info in a column-parseable format
551 Create new branch:
553 Create a new branch for working on patch series
554 -n NEW_SERIES_NAME, --new NEW_SERIES_NAME
556 Create a new branch for working on a patch series
557 -f FORK_POINT, --fork-point FORK_POINT
559 When creating a new branch, use this fork point instead
560 of HEAD
561 -F MSGID, --from-thread MSGID
563 When creating a new branch, use this thread
564 Enroll existing branch:
566 Enroll existing branch for prep work
567 -e ENROLL_BASE, --enroll ENROLL_BASE
569 Enroll current branch, using the passed tag, branch, or
570 commit as fork base
571 b4 send
573 usage: b4 send [-h] [-d] [-o OUTPUT_DIR] [--reflect]
574 [--no-trailer-to-cc] [--to TO [TO ...]] [--cc CC [CC ...]]
575 [--not-me-too] [--resend [RESEND]] [--no-sign] [--web-auth-new]
576 [--web-auth-verify VERIFY_TOKEN]
577 options:
579 -h, --help
581 show this help message and exit
582 -d, --dry-run
584 Do not send, just dump out raw smtp messages to the std‐
585 out
586 -o OUTPUT_DIR, --output-dir OUTPUT_DIR
588 Do not send, write raw messages to this directory (forces
589 --dry-run)
590 --reflect
592 Send everything to yourself instead of the actual recipi‐
593 ents
594 --no-trailer-to-cc
596 Do not add any addresses found in the cover or patch
597 trailers to To: or Cc:
598 --to TO [TO ...]
600 Addresses to add to the To: list
601 --cc CC [CC ...]
603 Addresses to add to the Cc: list
604 --not-me-too
606 Remove yourself from the To: or Cc: list
607 --resend [RESEND]
609 Resend a previously sent version of the series
610 --no-sign
612 Do not add the cryptographic attestation signature header
613 Web submission:
615 Authenticate with the web submission endpoint
616 --web-auth-new
618 Initiate a new web authentication request
619 --web-auth-verify VERIFY_TOKEN
621 Submit the token received via verification email
622 b4 trailers
624 usage: b4 trailers [-h] [-u] [-S] [-F MSGID] [--since SINCE]
625 options:
627 -h, --help
629 show this help message and exit
630 -u, --update
632 Update branch commits with latest received trailers
633 -S, --sloppy-trailers
635 Apply trailers without email address match checking
636 -F MSGID, --trailers-from MSGID
638 Look for trailers in the thread with this msgid instead
639 of using the series change-id
640 --since SINCE
642 The --since option to use with -F when auto-matching
643 patches (default=1.month)
644 -m LOCALMBOX, --use-local-mbox LOCALMBOX
646 Instead of grabbing a thread from lore, process this mbox
647 file (or - for stdin)
648 --stdin-pipe-sep STDIN_PIPE_SEP
650 When accepting messages on stdin, split using this pipe
651 separator string
652 -C, --no-cache
654 Do not use local cache
655
657 B4 configuration is handled via git-config(1), so you can store it in
658 either the toplevel $HOME/.gitconfig file, or in a per-repository
659 .git/config file if your workflow changes per project.
660 To see configuration options available, see online documentation at
662 https://b4.docs.kernel.org/en/latest/config.html
663
665 Commands making remote HTTP requests may be configured to use a proxy
666 by setting the HTTPS_PROXY environment variable, as described in
667 https://docs.python-requests.org/en/latest/user/advanced/#proxies.
668
670 Please email tools@linux.kernel.org with support requests, or browse
671 the list archive at https://lore.kernel.org/tools.
672
674 mricon@kernel.org
675 License: GPLv2+
677
679 The Linux Foundation and contributors
6800.12.0 2023-01-19 B4(5)