]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/lei-q.pod
lei q: make --save the default
[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 must use L<netrc(5)> and/or 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<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<--format=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 --dedupe=STRATEGY
128
129 =item -d STRATEGY
130
131 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
132 C<none>.
133
134 Default: C<content>
135
136 =for comment
137 TODO: Provide description of strategies?
138
139 =item --[no-]remote
140
141 Whether to include results requiring network access.  When local
142 externals are configured, C<--remote> must be explicitly passed to
143 enable reporting of results from remote externals.
144
145 =item --no-local
146
147 Limit operations to those requiring network access.
148
149 =item --no-external
150
151 Don't include results from externals.
152
153 =item --include=LOCATION
154
155 =item -I LOCATION
156
157 Include specified external in search.  This option may be given
158 multiple times.
159
160 =item --exclude=LOCATION
161
162 Exclude specified external from search.  This option may be given
163 multiple times.
164
165 =item --only=LOCATION
166
167 Use only the specified external for search.  This option may be given
168 multiple times, in which case the search uses only the specified set.
169
170 =item --globoff
171
172 =item -g
173
174 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
175 option applies to C<--include>, C<--exclude>, and C<--only>.
176
177 =item --no-import-remote
178
179 Disable the default behavior of memoizing remote messages into the
180 local store.
181
182 =item --lock=METHOD
183
184 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
185 C<none>.
186
187 Default: fcntl,dotlock
188
189 =item --limit=NUMBER
190
191 =item -NUMBER
192
193 =item -n NUMBER
194
195 Limit the number of matches.
196
197 Default: 10000
198
199 =item --offset=NUMBER
200
201 Shift start of search results.
202
203 Default: 0
204
205 =item --reverse
206
207 =item -r
208
209 Reverse the results.  Note that this applies before C<--limit>.
210
211 =item --sort=KEY
212
213 =item -s KEY
214
215 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
216 and C<docid>.
217
218 Default: C<received>
219
220 =item --verbose
221
222 =item -v
223
224 Provide more feedback on stderr.
225
226 =item --quiet
227
228 =item -q
229
230 Suppress feedback messages.
231
232 =item --torsocks=auto|no|yes
233
234 =item --no-torsocks
235
236 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
237
238 Default: C<auto>
239
240 =item --proxy=PROTO://HOST[:PORT]
241
242 =back
243
244 =head1 CONTACT
245
246 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
247
248 The mail archives are hosted at L<https://public-inbox.org/meta/> and
249 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
250
251 =head1 COPYRIGHT
252
253 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
254
255 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
256
257 =head1 SEE ALSO
258
259 L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
260 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>