=head1 DESCRIPTION
-Search for messages across the lei store and externals.
+Search for messages across the lei/store and externals.
=for comment
TODO: Give common prefixes, or at least a description/reference.
Read search terms from stdin.
+=item --no-save
+
+Do not save the search for L<lei-up(1)>.
+
=item --output=MFOLDER
=item -o MFOLDER
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 must use L<netrc(5)> and/or L<git-credential(1)> to
+authentication use L<git-credential(1)> to
fill in the username and password.
A prefix can specify the format of the output: C<maildir>,
Format of results to stdout. This option exists as a convenient
way to specify the format for the default stdout destination.
-C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
+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
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
TODO: Warning: this flag may become persistent and saved in
lei/store unless an MUA unflags it! (Behavior undecided)
+=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 the number of CPUs available for Maildir,
+IMAP/IMAPS, and mbox* destinations.
+
+Omitting C<QUERY_WORKERS> but leaving the comma (C<,>) allows
+one to only set C<WRITE_WORKERS>
+
=item --dedupe=STRATEGY
=item -d STRATEGY
=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 -n NUMBER
-Limit the number of matches.
+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 --no-torsocks
-Whether to wrap L<git(1)> and L<curl(1)> commands with 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>
=head1 COPYRIGHT
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+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-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>