=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.

=for comment
TODO: Give common prefixes, or at least a description/reference.

=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<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 keywords before writing to an existing output
destination.

=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)

=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

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>
