=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 must use L<netrc(5)> and/or 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 --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

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

Limit the number of matches.

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

Default: C<auto>

=item --proxy=PROTO://HOST[:PORT]

=back

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