diff options
Diffstat (limited to 'Documentation/lei-q.pod')
| -rw-r--r-- | Documentation/lei-q.pod | 105 |
1 files changed, 95 insertions, 10 deletions
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod index e1e3666d..79156750 100644 --- a/Documentation/lei-q.pod +++ b/Documentation/lei-q.pod @@ -12,9 +12,6 @@ lei q [OPTIONS] (--stdin|-) 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 @@ -50,6 +47,10 @@ 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<v2:/path/to/inbox> may be used to create a new inbox of +L<public-inbox-v2-format(5)>. The new inbox will not be configured +in the L<public-inbox-config(5)> file. + C<maildir> is the default for an existing directory or non-existing path. Default: C<-> (stdout) @@ -76,7 +77,7 @@ 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 +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. @@ -107,8 +108,9 @@ Augment output destination instead of clobbering it. =item --no-import-before -Do not import keywords before writing to an existing output -destination. +Do not import messages before writing to an existing output destination. +Be certain you do not need existing data in your output before using +this, it permanently erases data unless C<--augment> is used. =item --threads @@ -124,6 +126,37 @@ of the same thread. TODO: Warning: this flag may become persistent and saved in lei/store unless an MUA unflags it! (Behavior undecided) +Caveat: C<-tt> only works on locally-indexed messages at the +moment, and not on remote (HTTP(S)) endpoints. + +=item --thread-id=MSGID + +=item -T MSGID + +Only search messages in the same thread as the given Message-ID. + +For HTTP(S) externals, this only works on instances running +public-inbox 2.0+ (UNRELEASED). + +=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 75% of the number of CPUs available for +Maildir and mbox* destinations, but 4 per IMAP/IMAPS host. + +Omitting C<QUERY_WORKERS> but leaving the comma (C<,>) allows +one to only set C<WRITE_WORKERS> + =item --dedupe=STRATEGY =item -d STRATEGY @@ -164,6 +197,8 @@ 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. @@ -192,7 +227,7 @@ Default: fcntl,dotlock =item -n NUMBER -Fuzzy limit the number of matches per-local external and lei/store. +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. @@ -235,14 +270,64 @@ Suppress feedback messages. =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=PROTO://HOST[:PORT] +=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 @@ -259,7 +344,7 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> =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> |