aboutsummaryrefslogtreecommitdiff
path: root/man/b4.5.rst
blob: 217e14510fdc4caa96725842cb6318c4d875853a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
B4
==
----------------------------------------------------
Work with code submissions in a public-inbox archive
----------------------------------------------------

:Author:    mricon@kernel.org
:Date:      2021-09-01
:Copyright: The Linux Foundation and contributors
:License:   GPLv2+
:Version:   0.9.0
:Manual section: 5

SYNOPSIS
--------
b4 {mbox,am,shazam,attest,pr,ty,diff} [options]

DESCRIPTION
-----------
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.

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.

SUBCOMMANDS
-----------
* *b4 mbox*: Download a thread as an mbox file
* *b4 am*: Create an mbox file that is ready to git-am
* *b4 shazam*: Similar to *am*, but lets you apply patches directly
* *b4 pr*: Work with pull requests
* *b4 diff*: Show range-diff style diffs between patch versions
* *b4 ty*: Create templated replies for processed patches and pull requests
* *b4 attest*: (EXPERIMENTAL) Add cryptographic attestation to patches
* *b4 kr* (EXPERIMENTAL) Operate on patatt-compatible keyrings

OPTIONS
-------
-h, --help            show this help message and exit
-d, --debug           Add more debugging info to the output (default: False)
-q, --quiet           Output critical information only (default: False)

SUBCOMMAND OPTIONS
------------------
b4 mbox
~~~~~~~
usage:
  b4 mbox [-h] [-o OUTDIR] [-p USEPROJECT] [-c] [-n WANTNAME] [-m LOCALMBOX] [msgid]

positional arguments:
  msgid                 Message ID to process, or pipe a raw message

optional arguments:
  -h, --help            show this help message and exit
  -o OUTDIR, --outdir OUTDIR
                        Output into this directory (or use - to output mailbox contents to stdout)
  -p USEPROJECT, --use-project USEPROJECT
                        Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
  -c, --check-newer-revisions
                        Check if newer patch revisions exist
  -n WANTNAME, --mbox-name WANTNAME
                        Filename to name the mbox file
  -m LOCALMBOX, --use-local-mbox LOCALMBOX
                        Instead of grabbing a thread from lore, process this mbox file
                        (or use - for stdin)
  -C, --no-cache        Do not use local cache
  -f, --filter-dupes    When adding messages to existing maildir, filter out duplicates
  -M, --save-as-maildir
                        Save as maildir (avoids mbox format ambiguities)

*Example*: b4 mbox 20200313231252.64999-1-keescook@chromium.org

b4 am
~~~~~
usage:
  b4 am [-h] [-o OUTDIR] [-p USEPROJECT] [-c] [-n WANTNAME] [-m LOCALMBOX] [-v WANTVER] [-t] [-T] [-s] [-l] [-Q] [msgid]

positional arguments:
  msgid                 Message ID to process, or pipe a raw message

optional arguments:
  -h, --help            show this help message and exit
  -o OUTDIR, --outdir OUTDIR
                        Output into this directory (or use - to output mailbox contents to stdout)
  -p USEPROJECT, --use-project USEPROJECT
                        Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
  -c, --check-newer-revisions
                        Check if newer patch revisions exist
  -n WANTNAME, --mbox-name WANTNAME
                        Filename to name the mbox file
  -m LOCALMBOX, --use-local-mbox LOCALMBOX
                        Instead of grabbing a thread from lore, process this mbox file
                        (or use - for stdin)
  -M, --save-as-maildir
                        Save as maildir (avoids mbox format ambiguities)
  -C, --no-cache        Do not use local cache
  -v WANTVER, --use-version WANTVER
                        Get a specific version of the patch/series
  -t, --apply-cover-trailers
                        Apply trailers sent to the cover letter to all patches
  -S, --sloppy-trailers
                        Apply trailers without email address match checking
  -T, --no-add-trailers
                        Do not add or sort any trailers
  -s, --add-my-sob      Add your own signed-off-by to every patch
  -l, --add-link        Add a lore.kernel.org/r/ link to every patch
  -Q, --quilt-ready     Save patches in a quilt-ready folder
  -P CHERRYPICK, --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 \*globbing\*" to match on commit subject)
  -g, --guess-base
                        Try to guess the base of the series (if not specified)
  -3, --prep-3way
                        Prepare for a 3-way merge (tries to ensure that all index blobs exist by making a fake commit range)
  --cc-trailers
                        Copy all Cc'd addresses into Cc: trailers, if not already present
  --no-cover
                        Do not save the cover letter (on by default when using -o -)
  --no-partial-reroll
                        Do not reroll partial series when detected


*Example*: b4 am 20200313231252.64999-1-keescook@chromium.org

b4 shazam
---------
TBD.

b4 attest
~~~~~~~~~
usage: b4 attest [-h] patchfile [patchfile ...]

.. note::

   This functionality is now implemented via an auxiliary library called
   "patatt". You may instead install and use patatt directly with the
   same results.

positional arguments:
  patchfile             Patches to attest

*Example*: b4 attest outgoing/\*.patch

b4 pr
~~~~~
usage:
  command.py pr [-h] [-g GITDIR] [-b BRANCH] [-c] [-e] [-o OUTMBOX] [msgid]

positional arguments:
  msgid                 Message ID to process, or pipe a raw message

optional arguments:
  -h, --help            show this help message and exit
  -g GITDIR, --gitdir GITDIR
                        Operate on this git tree instead of current dir
  -b BRANCH, --branch BRANCH
                        Check out FETCH_HEAD into this branch after fetching
  -c, --check           Check if pull request has already been applied
  -e, --explode         Convert a pull request into an mbox full of patches
  -o OUTMBOX, --output-mbox OUTMBOX
                        Save exploded messages into this mailbox (default: msgid.mbx)
  -l, --retrieve-links  Attempt to retrieve any Link: URLs (use with -e)
  -f MAILFROM, --from-addr MAILFROM
                        Use this From: in exploded messages (use with -e)

*Example*: b4 pr 202003292120.2BDCB41@keescook

b4 ty
~~~~~
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]

optional arguments:
  -h, --help            show this help message and exit
  -g GITDIR, --gitdir GITDIR
                        Operate on this git tree instead of current dir
  -o OUTDIR, --outdir OUTDIR
                        Write thanks files into this dir (default=.)
  -l, --list            List pull requests and patch series you have retrieved
  -t THANK_FOR, --thank-for THANK_FOR
                        Generate thankyous for specific entries from -l (e.g.: 1,3-5,7-; or "all")
  -d DISCARD, --discard DISCARD
                        Discard specific messages from -l (e.g.: 1,3-5,7-; or "all")
  -a, --auto            Use the Auto-Thankanator gun to figure out what got applied/merged
  -b BRANCH, --branch BRANCH
                        The branch to check against, instead of current
  --since SINCE         The --since option to use when auto-matching patches (default=1.week)
  -S, --send-email      Send email instead of writing out .thanks files
  --dry-run             Print out emails instead of sending them

.. note::

   To send mails directly using -S, you should have a configured
   [sendemail] section somewhere in your applicable git configuration
   files (global or in-tree).

*Example*: b4 ty -aS --dry-run

b4 diff
~~~~~~~
usage: b4 diff [-h] [-g GITDIR] [-p USEPROJECT] [-C] [-v WANTVERS [WANTVERS ...]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid]

positional arguments:
  msgid                 Message ID to process, pipe a raw message, or use -m

optional arguments:

  -h, --help            show this help message and exit
  -g GITDIR, --gitdir GITDIR
                        Operate on this git tree instead of current dir
  -p USEPROJECT, --use-project USEPROJECT
                        Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
  -C, --no-cache        Do not use local cache

  -v WANTVERS [WANTVERS ...], --compare-versions WANTVERS [WANTVERS ...]
                        Compare specific versions instead of latest and one before that, e.g. -v 3 5

  -n, --no-diff
                        Do not generate a diff, just show the command to do it

  -o OUTDIFF, --output-diff OUTDIFF
                        Save diff into this file instead of outputting to stdout
  -c, --color
                        Force color output even when writing to file

  -m AMBOX AMBOX, --compare-am-mboxes AMBOX AMBOX
                        Compare two mbx files prepared with "b4 am"

*Example*: b4 diff 20200526205322.23465-1-mic@digikod.net

b4 kr
~~~~~
usage: b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [--show-keys] [msgid]

positional arguments:
  msgid                 Message ID to process, or pipe a raw message

optional arguments:
  -h, --help            show this help message and exit
  -p USEPROJECT, --use-project USEPROJECT
                        Use a specific project instead of guessing (linux-mm, linux-hardening, etc)
  -m LOCALMBOX, --use-local-mbox LOCALMBOX
                        Instead of grabbing a thread from lore, process this mbox file (or - for stdin)
  -C, --no-cache        Do not use local cache
  --show-keys           Show all developer keys from the thread

*Example*: b4 kr --show-keys 20210521184811.617875-1-konstantin@linuxfoundation.org

CONFIGURATION
-------------
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.

Default configuration, with explanations::

   [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'll use what we find in
      # git-config for gpg.program; and if that's not set,
      # we'll 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

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