]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/lei-q.pod
ipc: drop unused $args from ->ipc_worker_stop
[public-inbox.git] / Documentation / lei-q.pod
1 =head1 NAME
2
3 lei-q - search for messages matching terms
4
5 =head1 SYNOPSIS
6
7 lei q [OPTIONS] TERM [TERM...]
8
9 lei q [OPTIONS] (--stdin|-)
10
11 =head1 DESCRIPTION
12
13 Search for messages across the lei/store and externals.
14
15 =for comment
16 TODO: Give common prefixes, or at least a description/reference.
17
18 =head1 OPTIONS
19
20 =for comment
21 TODO: mention curl options?
22
23 =over
24
25 =item --stdin
26
27 Read search terms from stdin.
28
29 =item --no-save
30
31 Do not save the search for L<lei-up(1)>.
32
33 =item --output=MFOLDER
34
35 =item -o MFOLDER
36
37 =item --mfolder=MFOLDER
38
39 Warning: this clobbers and overwrites the output destination unless
40 L</--augment> is specified.
41
42 Destination for results (e.g., C</tmp/results-Maildir>,
43 C<imaps://user@mail.example.com/INBOX.test>, or
44 C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
45 C<imap://> or C<imaps://>.  URLs requiring
46 authentication use L<git-credential(1)> to
47 fill in the username and password.
48
49 A prefix can specify the format of the output: C<maildir>,
50 C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>.  For a description of
51 mail formats, see L<lei-mail-formats(5)>.
52
53 C<maildir> is the default for an existing directory or non-existing path.
54
55 Default: C<-> (stdout)
56
57 =item --format=FORMAT
58
59 =item -f FORMAT
60
61 Format of results to stdout.  This option exists as a convenient
62 way to specify the format for the default stdout destination.
63 C<reply>, C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
64 as are the various mbox variants described in L</--output>.
65
66 When a format isn't specified, it's chosen based on the
67 L</--output> destination or prefix.  C<json> is used for the
68 default destination (stdout).
69
70 Using a C<format:> prefix with the C<--output> destination is
71 preferred when not writing to stdout.
72
73 =item --no-color
74
75 Disable color (for C<-f reply> and C<-f text>).
76
77 =item --pretty
78
79 Pretty print C<json> or C<concatjson> output.  If stdout is opened to
80 a tty and used as the C<--output> destination, C<--pretty> is enabled
81 by default.
82
83 =item --mua=COMMAND
84
85 A command to run on C<--output> Maildir or mbox (e.g., C<mutt -f %f>).
86 For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can
87 be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>,
88 or C<neomutt>.
89
90 =item --alert=COMMAND[,COMMAND...]
91
92 Run C<COMMAND> after writing to output.  C<:WINCH> indicates to send
93 C<SIGWINCH> to the C<--mua> process.  C<:bell> indicates to print a
94 bell code.  Any other value is interpreted as a command to execute as
95 is.
96
97 This option may be given multiple times.
98
99 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
100 doesn't point to stdout, nothing otherwise.
101
102 =item --augment
103
104 =item -a
105
106 Augment output destination instead of clobbering it.
107
108 =item --no-import-before
109
110 Do not import keywords before writing to an existing output
111 destination.
112
113 =item --threads
114
115 =item -t
116
117 Return all messages in the same thread as the actual match(es).
118
119 Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
120 on messages which were actual matches.  This is useful to distinguish
121 messages which were direct hits from messages which were merely part
122 of the same thread.
123
124 TODO: Warning: this flag may become persistent and saved in
125 lei/store unless an MUA unflags it!  (Behavior undecided)
126
127 =item --jobs=QUERY_WORKERS[,WRITE_WORKERS]
128 =item --jobs=,WRITE_WORKERS
129
130 =item -j QUERY_WORKERS[,WRITE_WORKERS]
131 =item -j ,WRITE_WORKERS
132
133 Set the number of query and write worker processes for parallelism.
134
135 C<QUERY_WORKERS> defaults to the number of CPUs available, but 4 per
136 remote (HTTP/HTTPS) host.
137
138 C<WRITE_WORKERS> defaults to 75% of the number of CPUs available for
139 Maildir and mbox* destinations, but 4 per IMAP/IMAPS host.
140
141 Omitting C<QUERY_WORKERS> but leaving the comma (C<,>) allows
142 one to only set C<WRITE_WORKERS>
143
144 =item --dedupe=STRATEGY
145
146 =item -d STRATEGY
147
148 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
149 C<none>.
150
151 Default: C<content>
152
153 =for comment
154 TODO: Provide description of strategies?
155
156 =item --[no-]remote
157
158 Whether to include results requiring network access.  When local
159 externals are configured, C<--remote> must be explicitly passed to
160 enable reporting of results from remote externals.
161
162 =item --no-local
163
164 Limit operations to those requiring network access.
165
166 =item --no-external
167
168 Don't include results from externals.
169
170 =item --include=LOCATION
171
172 =item -I LOCATION
173
174 Include specified external in search.  This option may be given
175 multiple times.
176
177 =item --exclude=LOCATION
178
179 Exclude specified external from search.  This option may be given
180 multiple times.
181
182 =item --only=LOCATION
183
184 =item -O LOCATION
185
186 Use only the specified external for search.  This option may be given
187 multiple times, in which case the search uses only the specified set.
188
189 =item --globoff
190
191 =item -g
192
193 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
194 option applies to C<--include>, C<--exclude>, and C<--only>.
195
196 =item --no-import-remote
197
198 Disable the default behavior of memoizing remote messages into the
199 local store.
200
201 =item --lock=METHOD
202
203 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
204 C<none>.
205
206 Default: fcntl,dotlock
207
208 =item --limit=NUMBER
209
210 =item -NUMBER
211
212 =item -n NUMBER
213
214 Fuzzy limit the number of matches per-local external and lei/store.
215 Messages added by the L<--threads> switch do not count towards this
216 limit, and there is no limit on remote externals.
217
218 Default: 10000
219
220 =item --offset=NUMBER
221
222 Shift start of search results.
223
224 Default: 0
225
226 =item --reverse
227
228 =item -r
229
230 Reverse the results.  Note that this applies before C<--limit>.
231
232 =item --sort=KEY
233
234 =item -s KEY
235
236 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
237 and C<docid>.
238
239 Default: C<received>
240
241 =item --verbose
242
243 =item -v
244
245 Provide more feedback on stderr.
246
247 =item --quiet
248
249 =item -q
250
251 Suppress feedback messages.
252
253 =item --torsocks=auto|no|yes
254
255 =item --no-torsocks
256
257 Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
258
259 Default: C<auto>
260
261 =item --proxy=PROTOCOL://HOST[:PORT]
262
263 =back
264
265 =head1 SEARCH TERMS
266
267 C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
268 instances:
269
270 =for comment
271 AUTO-GENERATED-SEARCH-TERMS-BEGIN
272
273   s:        match within Subject  e.g. s:"a quick brown fox"
274   d:        match date-time range, git "approxidate" formats supported
275             Open-ended ranges such as `d:last.week..' and
276             `d:..2.days.ago' are supported
277   b:        match within message body, including text attachments
278   nq:       match non-quoted text within message body
279   q:        match quoted text within message body
280   n:        match filename of attachment(s)
281   t:        match within the To header
282   c:        match within the Cc header
283   f:        match within the From header
284   a:        match within the To, Cc, and From headers
285   tc:       match within the To and Cc headers
286   l:        match contents of the List-Id header
287   bs:       match within the Subject and body
288   dfn:      match filename from diff
289   dfa:      match diff removed (-) lines
290   dfb:      match diff added (+) lines
291   dfhh:     match diff hunk header context (usually a function name)
292   dfctx:    match diff context lines
293   dfpre:    match pre-image git blob ID
294   dfpost:   match post-image git blob ID
295   dfblob:   match either pre or post-image git blob ID
296   patchid:  match `git patch-id --stable' output
297   rt:       match received time, like `d:' if sender's clock was correct
298
299 =for comment
300 AUTO-GENERATED-SEARCH-TERMS-END
301
302 Additional search prefixes which only affect the local lei/store:
303
304   L:       match the given label
305   kw:      match the given keywords
306
307 See L<lei-tag(1)> for more info on labels and keywords.
308
309 Most prefixes are probabilistic, meaning they support stemming
310 and wildcards (C<*>).  Ranges (such as C<d:>) and boolean prefixes
311 do not support stemming or wildcards.
312 The upstream Xapian query parser documentation fully explains
313 the query syntax: L<https://xapian.org/docs/queryparser.html>
314
315 =head1 TIPS
316
317 C<-f reply> is intended to aid in turning a cover letter
318 into a reply (since using C<git format-patch --in-reply-to=...>
319 is tedious).  Results (including "From " lines) should be edited
320 and trimmed in your favorite C<$EDITOR> before sending.
321
322 =head1 CONTACT
323
324 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
325
326 The mail archives are hosted at L<https://public-inbox.org/meta/> and
327 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
328
329 =head1 COPYRIGHT
330
331 Copyright all contributors L<mailto:meta@public-inbox.org>
332
333 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
334
335 =head1 SEE ALSO
336
337 L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
338 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>