public-inbox.git  about / heads / tags
an "archives first" approach to mailing lists
blob 4476a806dae7659f46b4d6d0e8f62e5a2bfe3e17 9011 bytes (raw)
$ git show HEAD:Documentation/lei-q.pod	# shows this blob on the CLI

  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
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
=head1 NAME

lei-q - search for messages matching terms

=head1 SYNOPSIS

lei q [OPTIONS] TERM [TERM...]

lei q [OPTIONS] (--stdin|-)

=head1 DESCRIPTION

Search for messages across the lei/store and externals.

=head1 OPTIONS

=for comment
TODO: mention curl options?

=over

=item --stdin

Read search terms from stdin.

=item --no-save

Do not save the search for L<lei-up(1)>.

=item --output=MFOLDER

=item -o MFOLDER

=item --mfolder=MFOLDER

Warning: this clobbers and overwrites the output destination unless
L</--augment> is specified.

Destination for results (e.g., C</tmp/results-Maildir>,
C<imaps://user@mail.example.com/INBOX.test>, or
C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
C<imap://> or C<imaps://>.  URLs requiring
authentication use L<git-credential(1)> to
fill in the username and password.

A prefix can specify the format of the output: C<maildir>,
C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>.  For a description of
mail formats, see L<lei-mail-formats(5)>.

C<v2:/path/to/inbox> may be used to create a new inbox of
L<public-inbox-v2-format(5)>.  The new inbox will not be configured
in the L<public-inbox-config(5)> file.

C<maildir> is the default for an existing directory or non-existing path.

Default: C<-> (stdout)

=item --format=FORMAT

=item -f FORMAT

Format of results to stdout.  This option exists as a convenient
way to specify the format for the default stdout destination.
C<reply>, C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
as are the various mbox variants described in L</--output>.

When a format isn't specified, it's chosen based on the
L</--output> destination or prefix.  C<json> is used for the
default destination (stdout).

Using a C<format:> prefix with the C<--output> destination is
preferred when not writing to stdout.

=item --no-color

Disable color (for C<-f reply> and C<-f text>).

=item --pretty

Pretty-print C<json> or C<concatjson> output.  If stdout is opened to
a tty and used as the C<--output> destination, C<--pretty> is enabled
by default.

=item --mua=COMMAND

A command to run on C<--output> Maildir or mbox (e.g., C<mutt -f %f>).
For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can
be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>,
or C<neomutt>.

=item --alert=COMMAND[,COMMAND...]

Run C<COMMAND> after writing to output.  C<:WINCH> indicates to send
C<SIGWINCH> to the C<--mua> process.  C<:bell> indicates to print a
bell code.  Any other value is interpreted as a command to execute as
is.

This option may be given multiple times.

Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
doesn't point to stdout, nothing otherwise.

=item --augment

=item -a

Augment output destination instead of clobbering it.

=item --no-import-before

Do not import messages before writing to an existing output destination.
Be certain you do not need existing data in your output before using
this, it permanently erases data unless C<--augment> is used.

=item --threads

=item -t

Return all messages in the same thread as the actual match(es).

Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
on messages which were actual matches.  This is useful to distinguish
messages which were direct hits from messages which were merely part
of the same thread.

TODO: Warning: this flag may become persistent and saved in
lei/store unless an MUA unflags it!  (Behavior undecided)

Caveat: C<-tt> only works on locally-indexed messages at the
moment, and not on remote (HTTP(S)) endpoints.

=item --jobs=QUERY_WORKERS[,WRITE_WORKERS]

=item --jobs=,WRITE_WORKERS

=item -j QUERY_WORKERS[,WRITE_WORKERS]

=item -j ,WRITE_WORKERS

Set the number of query and write worker processes for parallelism.

C<QUERY_WORKERS> defaults to the number of CPUs available, but 4 per
remote (HTTP/HTTPS) host.

C<WRITE_WORKERS> defaults to 75% of the number of CPUs available for
Maildir and mbox* destinations, but 4 per IMAP/IMAPS host.

Omitting C<QUERY_WORKERS> but leaving the comma (C<,>) allows
one to only set C<WRITE_WORKERS>

=item --dedupe=STRATEGY

=item -d STRATEGY

Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
C<none>.

Default: C<content>

=for comment
TODO: Provide description of strategies?

=item --[no-]remote

Whether to include results requiring network access.  When local
externals are configured, C<--remote> must be explicitly passed to
enable reporting of results from remote externals.

=item --no-local

Limit operations to those requiring network access.

=item --no-external

Don't include results from externals.

=item --include=LOCATION

=item -I LOCATION

Include specified external in search.  This option may be given
multiple times.

=item --exclude=LOCATION

Exclude specified external from search.  This option may be given
multiple times.

=item --only=LOCATION

=item -O LOCATION

Use only the specified external for search.  This option may be given
multiple times, in which case the search uses only the specified set.

=item --globoff

=item -g

Do not match locations using C<*?> wildcards and C<[]> ranges.  This
option applies to C<--include>, C<--exclude>, and C<--only>.

=item --no-import-remote

Disable the default behavior of memoizing remote messages into the
local store.

=item --lock=METHOD

L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
C<none>.

Default: fcntl,dotlock

=item --limit=NUMBER

=item -NUMBER

=item -n NUMBER

Fuzzy-limit the number of matches per local external and lei/store.
Messages added by the L<--threads> switch do not count towards this
limit, and there is no limit on remote externals.

Default: 10000

=item --offset=NUMBER

Shift start of search results.

Default: 0

=item --reverse

=item -r

Reverse the results.  Note that this applies before C<--limit>.

=item --sort=KEY

=item -s KEY

Order the results by KEY.  Valid keys are C<received>, C<relevance>,
and C<docid>.

Default: C<received>

=item --verbose

=item -v

Provide more feedback on stderr.

=item --quiet

=item -q

Suppress feedback messages.

=item --torsocks=auto|no|yes

=item --no-torsocks

Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.

Default: C<auto>

=item --proxy=PROTOCOL://HOST[:PORT]

=back

=head1 SEARCH TERMS

C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
instances:

=for comment
AUTO-GENERATED-SEARCH-TERMS-BEGIN

  s:        match within Subject  e.g. s:"a quick brown fox"
  d:        match date-time range, git "approxidate" formats supported
            Open-ended ranges such as `d:last.week..' and
            `d:..2.days.ago' are supported
  b:        match within message body, including text attachments
  nq:       match non-quoted text within message body
  q:        match quoted text within message body
  n:        match filename of attachment(s)
  t:        match within the To header
  c:        match within the Cc header
  f:        match within the From header
  a:        match within the To, Cc, and From headers
  tc:       match within the To and Cc headers
  l:        match contents of the List-Id header
  bs:       match within the Subject and body
  dfn:      match filename from diff
  dfa:      match diff removed (-) lines
  dfb:      match diff added (+) lines
  dfhh:     match diff hunk header context (usually a function name)
  dfctx:    match diff context lines
  dfpre:    match pre-image git blob ID
  dfpost:   match post-image git blob ID
  dfblob:   match either pre or post-image git blob ID
  patchid:  match `git patch-id --stable' output
  rt:       match received time, like `d:' if sender's clock was correct

=for comment
AUTO-GENERATED-SEARCH-TERMS-END

Additional search prefixes which only affect the local lei/store:

  L:       match the given label
  kw:      match the given keywords

See L<lei-tag(1)> for more info on labels and keywords.

Most prefixes are probabilistic, meaning they support stemming
and wildcards (C<*>).  Ranges (such as C<d:>) and boolean prefixes
do not support stemming or wildcards.
The upstream Xapian query parser documentation fully explains
the query syntax: L<https://xapian.org/docs/queryparser.html>

=head1 TIPS

C<-f reply> is intended to aid in turning a cover letter
into a reply (since using C<git format-patch --in-reply-to=...>
is tedious).  Results (including "From " lines) should be edited
and trimmed in your favorite C<$EDITOR> before sending.

=head1 CONTACT

Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>

The mail archives are hosted at L<https://public-inbox.org/meta/> and
L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

=head1 COPYRIGHT

Copyright all contributors L<mailto:meta@public-inbox.org>

License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>

=head1 SEE ALSO

L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>

git clone https://public-inbox.org/public-inbox.git
git clone http://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/public-inbox.git