]> Sergey Matveev's repositories - public-inbox.git/blobdiff - Documentation/lei-q.pod
lei convert: remove redundant input_net_cb
[public-inbox.git] / Documentation / lei-q.pod
index c8df6fc7244bfae68673b2506d7917f47f5d2317..574c12eb9d3a36883063fc5a05c6b793cec2698c 100644 (file)
@@ -6,16 +6,18 @@ lei-q - search for messages matching terms
 
 lei q [OPTIONS] TERM [TERM...]
 
 
 lei q [OPTIONS] TERM [TERM...]
 
-lei q [OPTIONS] --stdin
+lei q [OPTIONS] (--stdin|-)
 
 =head1 DESCRIPTION
 
 
 =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.
 
 =head1 OPTIONS
 
 TODO: Give common prefixes, or at least a description/reference.
 
 =head1 OPTIONS
 
+=for comment
 TODO: mention curl options?
 
 =over
 TODO: mention curl options?
 
 =over
@@ -24,19 +26,53 @@ TODO: mention curl options?
 
 Read search terms from stdin.
 
 
 Read search terms from stdin.
 
-=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
+=item --no-save
 
 
-Destination for results (e.g., C<path/to/Maildir> or - for stdout).
+Do not save the search for L<lei-up(1)>.
 
 
-Default: -
+=item --output=MFOLDER
 
 
-=item -f FORMAT, --format=FORMAT
+=item -o MFOLDER
 
 
-Format of results: C<maildir>, C<mboxrd>, C<mboxcl2>, C<mboxcl>,
-C<mboxo>, C<json>, C<jsonl>, or C<concatjson>.  The default format
-used depends on C<--output>.
+=item --mfolder=MFOLDER
 
 
-TODO: Provide description of formats?
+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
 
 
 =item --pretty
 
@@ -63,21 +99,41 @@ 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.
 
 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
 doesn't point to stdout, nothing otherwise.
 
-=item -a, --augment
+=item --augment
+
+=item -a
 
 Augment output destination instead of clobbering it.
 
 
 Augment output destination instead of clobbering it.
 
-=item -t, --threads
+=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).
 
 
 Return all messages in the same thread as the actual match(es).
 
-=item -d STRATEGY, --dedupe=STRATEGY
+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>
 
 
 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
 TODO: Provide description of strategies?
 
 =item --[no-]remote
@@ -94,7 +150,9 @@ Limit operations to those requiring network access.
 
 Don't include results from externals.
 
 
 Don't include results from externals.
 
-=item -I LOCATION, --include=LOCATION
+=item --include=LOCATION
+
+=item -I LOCATION
 
 Include specified external in search.  This option may be given
 multiple times.
 
 Include specified external in search.  This option may be given
 multiple times.
@@ -106,17 +164,39 @@ multiple times.
 
 =item --only=LOCATION
 
 
 =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.
 
 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 -g, --globoff
+=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>.
 
 
 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 option applies to C<--include>, C<--exclude>, and C<--only>.
 
-=item -NUMBER, -n NUMBER, --limit=NUMBER
+=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
 
 
-Limit the number of matches.
+=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
 
 
 Default: 10000
 
@@ -126,39 +206,58 @@ Shift start of search results.
 
 Default: 0
 
 
 Default: 0
 
-=item -r, --reverse
+=item --reverse
+
+=item -r
 
 Reverse the results.  Note that this applies before C<--limit>.
 
 
 Reverse the results.  Note that this applies before C<--limit>.
 
-=item -s KEY, --sort=KEY
+=item --sort=KEY
+
+=item -s KEY
 
 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 and C<docid>.
 
 Default: C<received>
 
 
 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 and C<docid>.
 
 Default: C<received>
 
-=item -v, --verbose
+=item --verbose
+
+=item -v
 
 Provide more feedback on stderr.
 
 
 Provide more feedback on stderr.
 
-=item -q, --quiet
+=item --quiet
+
+=item -q
 
 Suppress feedback messages.
 
 
 Suppress feedback messages.
 
-=item --torsocks=auto|no|yes, --no-torsocks
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
 Default: C<auto>
 
 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 
 Default: C<auto>
 
+=item --proxy=PROTO://HOST[:PORT]
+
 =back
 
 =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>
 
 =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://hjrcffqmbrq6wope.onion/meta/>
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 
@@ -168,5 +267,5 @@ License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
 
 =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>
 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>