3 lei-q - search for messages matching terms
7 lei q [OPTIONS] TERM [TERM...]
9 lei q [OPTIONS] (--stdin|-)
13 Search for messages across the lei/store and externals.
16 TODO: Give common prefixes, or at least a description/reference.
21 TODO: mention curl options?
27 Read search terms from stdin.
31 Do not save the search for L<lei-up(1)>.
33 =item --output=MFOLDER
37 =item --mfolder=MFOLDER
39 Warning: this clobbers and overwrites the output destination unless
40 L</--augment> is specified.
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.
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)>.
53 C<maildir> is the default for an existing directory or non-existing path.
55 Default: C<-> (stdout)
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>.
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).
70 Using a C<format:> prefix with the C<--output> destination is
71 preferred when not writing to stdout.
75 Disable color (for C<-f reply> and C<-f text>).
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
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>,
90 =item --alert=COMMAND[,COMMAND...]
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
97 This option may be given multiple times.
99 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
100 doesn't point to stdout, nothing otherwise.
106 Augment output destination instead of clobbering it.
108 =item --no-import-before
110 Do not import keywords before writing to an existing output
117 Return all messages in the same thread as the actual match(es).
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
124 TODO: Warning: this flag may become persistent and saved in
125 lei/store unless an MUA unflags it! (Behavior undecided)
127 =item --dedupe=STRATEGY
131 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
137 TODO: Provide description of strategies?
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.
147 Limit operations to those requiring network access.
151 Don't include results from externals.
153 =item --include=LOCATION
157 Include specified external in search. This option may be given
160 =item --exclude=LOCATION
162 Exclude specified external from search. This option may be given
165 =item --only=LOCATION
169 Use only the specified external for search. This option may be given
170 multiple times, in which case the search uses only the specified set.
176 Do not match locations using C<*?> wildcards and C<[]> ranges. This
177 option applies to C<--include>, C<--exclude>, and C<--only>.
179 =item --no-import-remote
181 Disable the default behavior of memoizing remote messages into the
186 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
189 Default: fcntl,dotlock
197 Fuzzy limit the number of matches per-local external and lei/store.
198 Messages added by the L<--threads> switch do not count towards this
199 limit, and there is no limit on remote externals.
203 =item --offset=NUMBER
205 Shift start of search results.
213 Reverse the results. Note that this applies before C<--limit>.
219 Order the results by KEY. Valid keys are C<received>, C<relevance>,
228 Provide more feedback on stderr.
234 Suppress feedback messages.
236 =item --torsocks=auto|no|yes
240 Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
244 =item --proxy=PROTO://HOST[:PORT]
250 C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
254 AUTO-GENERATED-SEARCH-TERMS-BEGIN
256 s: match within Subject e.g. s:"a quick brown fox"
257 d: match date-time range, git "approxidate" formats supported
258 Open-ended ranges such as `d:last.week..' and
259 `d:..2.days.ago' are supported
260 b: match within message body, including text attachments
261 nq: match non-quoted text within message body
262 q: match quoted text within message body
263 n: match filename of attachment(s)
264 t: match within the To header
265 c: match within the Cc header
266 f: match within the From header
267 a: match within the To, Cc, and From headers
268 tc: match within the To and Cc headers
269 l: match contents of the List-Id header
270 bs: match within the Subject and body
271 dfn: match filename from diff
272 dfa: match diff removed (-) lines
273 dfb: match diff added (+) lines
274 dfhh: match diff hunk header context (usually a function name)
275 dfctx: match diff context lines
276 dfpre: match pre-image git blob ID
277 dfpost: match post-image git blob ID
278 dfblob: match either pre or post-image git blob ID
279 patchid: match `git patch-id --stable' output
280 rt: match received time, like `d:' if sender's clock was correct
283 AUTO-GENERATED-SEARCH-TERMS-END
285 Additional search prefixes which only affect the local lei/store:
287 L: match the given label
288 kw: match the given keywords
290 See L<lei-tag(1)> for more info on labels and keywords.
292 Most prefixes are probabilistic, meaning they support stemming
293 and wildcards (C<*>). Ranges (such as C<d:>) and boolean prefixes
294 do not support stemming or wildcards.
295 The upstream Xapian query parser documentation fully explains
296 the query syntax: L<https://xapian.org/docs/queryparser.html>
300 C<-f reply> is intended to aid in turning a cover letter
301 into a reply (since using C<git format-patch --in-reply-to=...>
302 is tedious). Results (including "From " lines) should be edited
303 and trimmed in your favorite C<$EDITOR> before sending.
307 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
309 The mail archives are hosted at L<https://public-inbox.org/meta/> and
310 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
314 Copyright all contributors L<mailto:meta@public-inbox.org>
316 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
320 L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
321 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>