diff options
Diffstat (limited to 'Documentation/lei-q.pod')
| -rw-r--r-- | Documentation/lei-q.pod | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod new file mode 100644 index 00000000..79156750 --- /dev/null +++ b/Documentation/lei-q.pod @@ -0,0 +1,354 @@ +=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. + +=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<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) + +=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 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 + +=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) + +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 + +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> |