summaryrefslogtreecommitdiff
path: root/man/b4.5.rst
blob: ee2cdd33345d4b2c0d711d5dfbfaa95ef4f0f7e2 (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
B4
==
-------------------------------------------
Work with patches in a public-inbox archive
-------------------------------------------

:Author:    mricon@kernel.org
:Date:      2020-03-23
:Copyright: The Linux Foundation and contributors
:License:   GPLv2+
:Version:   0.3.5
:Manual section: 5

SYNOPSIS
--------
b4 {mbox,am,attest,attverify} [options]

DESCRIPTION
-----------
This is a helper utility to work with patches 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 attest*: Submit cryptographic attestation for patches

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
  -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
  -C, --no-cache        Do not use local cache

*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
  -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
  -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 mbox patches in a quilt-ready folder

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

b4 attest
~~~~~~~~~
usage:
  b4 attest [-h] [-f SENDER] [-n] [-o OUTPUT] patchfile [patchfile ...]

positional arguments:
  patchfile             Patches to attest

optional arguments:
  -h, --help            show this help message and exit
  -f SENDER, --from SENDER
                        Use a custom From field
  -n, --no-submit       Do not submit attestation, just save the message ready
                        to send
  -o OUTPUT, --output OUTPUT
                        Save attestation message in this file if not
                        submitting it

*Example*: b4 attest -n -o output/xxxx-attestation.patch output/\*.patch

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 processing thread trailers, use this order. Can use shell-globbing
      # and must end with ,*
      # Common alternative order:
      #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*,*
      #
      # 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 = check
      #
      # "gpg" (whatever gpg is configured to do) or "tofu" to force TOFU mode
      # If you don't already have a carefully maintained web of trust setup, it is
      # strongly recommended to set this to "tofu"
      attestation-trust-model = gpg
      #
      # How strict should we be when comparing the email address in From to the
      # email addresses in the key's UIDs?
      # strict: must match one of the uids on the key to pass
      # loose: any valid and trusted key will be accepted
      attestation-uid-match = loose
      #
      # When showing attestation check results, do you like "fancy" (color, unicode)
      # or simple checkmarks?
      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


SUPPORT
-------
Please email tools@linux.kernel.org with support requests.