1B4(5)                                                                    B4(5)
2
3
4

NAME

6       B4 - Work with code submissions in a public-inbox archive
7

SYNOPSIS

9       b4 {mbox,am,attest,pr,ty,diff} [options]
10

DESCRIPTION

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
17       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

SUBCOMMANDS

21b4 mbox: Download a thread as an mbox file
22
23b4 am: Create an mbox file that is ready to git-am
24
25b4 pr: Work with pull requests
26
27b4 diff: Show range-diff style diffs between patch versions
28
29b4  ty:  Create  templated replies for processed patches and pull re‐
30         quests
31
32b4 attest: (EXPERIMENTAL) Add cryptographic attestation to patches
33
34b4 kr (EXPERIMENTAL) Operate on patatt-compatible keyrings
35

OPTIONS

37       -h, --help
38              show this help message and exit
39
40       -d, --debug
41              Add more debugging info to the output (default: False)
42
43       -q, --quiet
44              Output critical information only (default: False)
45

SUBCOMMAND OPTIONS

47   b4 mbox
48       usage: b4 mbox [-h] [-o OUTDIR] [-p USEPROJECT] [-c] [-n WANTNAME]  [-m
49              LOCALMBOX] [msgid]
50
51       positional arguments:
52              msgid                  Message ID to process, or pipe a raw mes‐
53              sage
54
55       optional arguments:
56
57              -h, --help
58                     show this help message and exit
59
60              -o OUTDIR, --outdir OUTDIR
61                     Output into this directory (or use -  to  output  mailbox
62                     contents to stdout)
63
64              -p USEPROJECT, --use-project USEPROJECT
65                     Use  a  specific  project  instead of guessing (linux-mm,
66                     linux-hardening, etc)
67
68              -c, --check-newer-revisions
69                     Check if newer patch revisions exist
70
71              -n WANTNAME, --mbox-name WANTNAME
72                     Filename to name the mbox file
73
74              -m LOCALMBOX, --use-local-mbox LOCALMBOX
75                     Instead of grabbing a thread from lore, process this mbox
76                     file (or use - for stdin)
77
78              -C, --no-cache
79                     Do not use local cache
80
81              -f, --filter-dupes
82                     When  adding messages to existing maildir, filter out du‐
83                     plicates
84
85              -M, --save-as-maildir
86                     Save as maildir (avoids mbox format ambiguities)
87
88       Example: b4 mbox 20200313231252.64999-1-keescook@chromium.org
89
90   b4 am
91       usage: b4 am [-h] [-o OUTDIR] [-p USEPROJECT] [-c]  [-n  WANTNAME]  [-m
92              LOCALMBOX] [-v WANTVER] [-t] [-T] [-s] [-l] [-Q] [msgid]
93
94       positional arguments:
95              msgid                  Message ID to process, or pipe a raw mes‐
96              sage
97
98       optional arguments:
99
100              -h, --help
101                     show this help message and exit
102
103              -o OUTDIR, --outdir OUTDIR
104                     Output into this directory (or use -  to  output  mailbox
105                     contents to stdout)
106
107              -p USEPROJECT, --use-project USEPROJECT
108                     Use  a  specific  project  instead of guessing (linux-mm,
109                     linux-hardening, etc)
110
111              -c, --check-newer-revisions
112                     Check if newer patch revisions exist
113
114              -n WANTNAME, --mbox-name WANTNAME
115                     Filename to name the mbox file
116
117              -m LOCALMBOX, --use-local-mbox LOCALMBOX
118                     Instead of grabbing a thread from lore, process this mbox
119                     file (or use - for stdin)
120
121              -M, --save-as-maildir
122                     Save as maildir (avoids mbox format ambiguities)
123
124              -C, --no-cache
125                     Do not use local cache
126
127              -v WANTVER, --use-version WANTVER
128                     Get a specific version of the patch/series
129
130              -t, --apply-cover-trailers
131                     Apply trailers sent to the cover letter to all patches
132
133              -S, --sloppy-trailers
134                     Apply trailers without email address match checking
135
136              -T, --no-add-trailers
137                     Do not add or sort any trailers
138
139              -s, --add-my-sob
140                     Add your own signed-off-by to every patch
141
142              -l, --add-link
143                     Add a lore.kernel.org/r/ link to every patch
144
145              -Q, --quilt-ready
146                     Save patches in a quilt-ready folder
147
148              -P CHERRYPICK, --cherry-pick CHERRYPICK
149                     Cherry-pick  a subset of patches (e.g. "-P 1-2,4,6-", "-P
150                     _" to use just the msgid specified, or "-P *globbing*" to
151                     match on commit subject)
152
153              -g, --guess-base
154                     Try to guess the base of the series (if not specified)
155
156              -3, --prep-3way
157                     Prepare for a 3-way merge (tries to ensure that all index
158                     blobs exist by making a fake commit range)
159
160              --cc-trailers
161                     Copy all Cc'd addresses into Cc: trailers, if not already
162                     present
163
164              --no-cover
165                     Do not save the cover letter (on by default when using -o
166                     -)
167
168              --no-partial-reroll
169                     Do not reroll partial series when detected
170
171       Example: b4 am 20200313231252.64999-1-keescook@chromium.org
172
173   b4 attest
174       usage: b4 attest [-h] patchfile [patchfile ...]
175
176       positional arguments:
177              patchfile             Patches to attest
178
179       Example: b4 attest outgoing/*.patch
180
181   b4 pr
182       usage: command.py pr [-h] [-g GITDIR] [-b BRANCH] [-c] [-e]  [-o  OUTM‐
183              BOX] [msgid]
184
185       positional arguments:
186              msgid                  Message ID to process, or pipe a raw mes‐
187              sage
188
189       optional arguments:
190
191              -h, --help
192                     show this help message and exit
193
194              -g GITDIR, --gitdir GITDIR
195                     Operate on this git tree instead of current dir
196
197              -b BRANCH, --branch BRANCH
198                     Check out FETCH_HEAD into this branch after fetching
199
200              -c, --check
201                     Check if pull request has already been applied
202
203              -e, --explode
204                     Convert a pull request into an mbox full of patches
205
206              -o OUTMBOX, --output-mbox OUTMBOX
207                     Save exploded messages into this  mailbox  (default:  ms‐
208                     gid.mbx)
209
210              -l, --retrieve-links
211                     Attempt to retrieve any Link: URLs (use with -e)
212
213              -f MAILFROM, --from-addr MAILFROM
214                     Use this From: in exploded messages (use with -e)
215
216       Example: b4 pr 202003292120.2BDCB41@keescook
217
218   b4 ty
219       usage: b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-s SEND [SEND ...]] [-d
220              DISCARD [DISCARD ...]] [-a] [-b BRANCH] [--since SINCE]
221
222       optional arguments:
223
224              -h, --help
225                     show this help message and exit
226
227              -g GITDIR, --gitdir GITDIR
228                     Operate on this git tree instead of current dir
229
230              -o OUTDIR, --outdir OUTDIR
231                     Write thanks files into this dir (default=.)
232
233              -l, --list
234                     List pull requests and patch series you have retrieved
235
236              -s SEND, --send SEND
237                     Generate thankyous for specific entries  from  -l  (e.g.:
238                     1,3-5,7-; or "all")
239
240              -d DISCARD, --discard DISCARD
241                     Discard  specific  messages  from  -l (e.g.: 1,3-5,7-; or
242                     "all")
243
244              -a, --auto
245                     Use the Auto-Thankanator  to  figure  out  what  got  ap‐
246                     plied/merged
247
248              -b BRANCH, --branch BRANCH
249                     The branch to check against, instead of current
250
251              --since SINCE
252                     The --since option to use when auto-matching patches (de‐
253                     fault=1.week)
254
255       Example: b4 ty --auto
256
257   b4 diff
258       usage: b4 diff [-h] [-g  GITDIR]  [-p  USEPROJECT]  [-C]  [-v  WANTVERS
259       [WANTVERS ...]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid]
260
261       positional arguments:
262              msgid                 Message ID to process, pipe a raw message,
263              or use -m
264
265       optional arguments:
266
267          -h, --help
268                 show this help message and exit
269
270          -g GITDIR, --gitdir GITDIR
271                 Operate on this git tree instead of current dir
272
273          -p USEPROJECT, --use-project USEPROJECT
274                 Use  a  specific  project  instead  of  guessing   (linux-mm,
275                 linux-hardening, etc)
276
277          -C, --no-cache
278                 Do not use local cache
279
280          -v  WANTVERS  [WANTVERS  ...], --compare-versions WANTVERS [WANTVERS
281          ...]
282                 Compare specific versions instead of latest  and  one  before
283                 that, e.g. -v 3 5
284
285          -n, --no-diff
286                 Do not generate a diff, just show the command to do it
287
288          -o OUTDIFF, --output-diff OUTDIFF
289                 Save diff into this file instead of outputting to stdout
290
291          -c, --color
292                 Force color output even when writing to file
293
294          -m AMBOX AMBOX, --compare-am-mboxes AMBOX AMBOX
295                 Compare two mbx files prepared with "b4 am"
296
297       Example: b4 diff 20200526205322.23465-1-mic@digikod.net
298
299   b4 kr
300       usage:  b4  kr  [-h]  [-p USEPROJECT] [-m LOCALMBOX] [-C] [--show-keys]
301       [msgid]
302
303       positional arguments:
304              msgid                 Message ID to process, or pipe a raw  mes‐
305              sage
306
307       optional arguments:
308
309              -h, --help
310                     show this help message and exit
311
312              -p USEPROJECT, --use-project USEPROJECT
313                     Use  a  specific  project  instead of guessing (linux-mm,
314                     linux-hardening, etc)
315
316              -m LOCALMBOX, --use-local-mbox LOCALMBOX
317                     Instead of grabbing a thread from lore, process this mbox
318                     file (or - for stdin)
319
320              -C, --no-cache
321                     Do not use local cache
322
323              --show-keys
324                     Show all developer keys from the thread
325
326       Example:                b4                kr                --show-keys
327       20210521184811.617875-1-konstantin@linuxfoundation.org
328

CONFIGURATION

330       B4 configuration is handled via git-config(1), so you can store  it  in
331       either  the  toplevel  $HOME/.gitconfig  file,  or  in a per-repository
332       .git/config file if your workflow changes per project.
333
334       Default configuration, with explanations:
335
336          [b4]
337             # Where to look up threads by message id
338             midmask = https://lore.kernel.org/r/%s
339             #
340             # When recording Link: trailers, use this mask
341             linkmask = https://lore.kernel.org/r/%s
342             #
343             # When duplicate messages exist, use the following order to decide
344             # which list-id is likely to have the least mangled version. Default
345             # preference is listed below, in the order of lists most likely to
346             # preserve proper DKIM validation. Use shell-style globbing and
347             # separate multiple entries with commas. Must end with ,*
348             listid-preference = *.feeds.kernel.org,*.linux.dev,*.kernel.org,*
349             #
350             # Set to "yes" to save maildirs instead of mailboxes
351             # This will help avoid mboxo/mboxrd format inconsistencies between
352             # public-inbox, python, and git
353             save-maildirs = no
354             #
355             # When processing thread trailers, sort them in this order.
356             # Can use shell-globbing and must end with ,*
357             # Some sorting orders:
358             #trailer-order=link*,fixes*,cc*,reported*,suggested*,original*,co-*,tested*,reviewed*,acked*,signed-off*,*
359             #trailer-order = fixes*,reported*,suggested*,original*,co-*,signed-off*,tested*,reviewed*,acked*,cc*,link*,*
360             trailer-order = _preserve_
361             #
362             # Attestation-checking configuration parameters
363             # off: do not bother checking attestation
364             # check: print an attaboy when attestation is found
365             # softfail: print a warning when no attestation found
366             # hardfail: exit with an error when no attestation found
367             attestation-policy = softfail
368             #
369             # Perform DKIM attestation?
370             attestation-check-dkim = yes
371             #
372             # When showing attestation check results, do you like "fancy" (color, unicode)
373             # or simple markers?
374             attestation-checkmarks = fancy
375             #
376             # How long before we consider attestation to be too old?
377             attestation-staleness-days = 30
378             #
379             # You can point this at a non-default home dir, if you like, or leave out to
380             # use the OS default.
381             attestation-gnupghome = None
382             #
383             # If this is not set, we'll use what we find in
384             # git-config for gpg.program; and if that's not set,
385             # we'll use "gpg" and hope for the best
386             gpgbin = None
387             #
388             # How long to keep downloaded threads in cache (minutes)?
389             cache-expire = 10
390             # Used when creating summaries for b4 ty, and can be set to a value like
391             # thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
392             # See this page for more info on convenient git.kernel.org shorterners:
393             # https://korg.wiki.kernel.org/userdoc/git-url-shorterners
394             thanks-commit-url-mask = None
395             # See thanks-pr-template.example. If not set, a default template will be used.
396             thanks-pr-template = None
397             # See thanks-am-template.example. If not set, a default template will be used.
398             thanks-am-template = None
399

SUPPORT

401       Please email tools@linux.kernel.org with support  requests,  or  browse
402       the list archive at https://lore.kernel.org/tools.
403

AUTHOR

405       mricon@kernel.org
406
407       License: GPLv2+
408
410       The Linux Foundation and contributors
411
412
413
414
4150.8.0                             2021-09-01                             B4(5)
Impressum