X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=Documentation%2Flei-q.pod;h=1cbffba4b36bb0eea2d9c0c077419674155ac89f;hb=3d280ae91480d846f31a05890d59d0d1d42df129;hp=787c51bf7bdddedb0fade1080acf383b4412dc50;hpb=752f1a1c6c3220911bd11e879b24caf660e24058;p=public-inbox.git diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod index 787c51bf..1cbffba4 100644 --- a/Documentation/lei-q.pod +++ b/Documentation/lei-q.pod @@ -10,7 +10,7 @@ lei q [OPTIONS] (--stdin|-) =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. @@ -26,32 +26,53 @@ TODO: mention curl options? Read search terms from stdin. -=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER +=item --no-save -Destination for results (e.g., C, +Do not save the search for L. + +=item --output=MFOLDER + +=item -o MFOLDER + +=item --mfolder=MFOLDER + +Warning: this clobbers and overwrites the output destination unless +L is specified. + +Destination for results (e.g., C, C, or -C). The prefix may be a supported protocol: -C, C, C, or C. URLs requiring -authentication must use L and/or L to +C). The prefix may be a supported protocol: +C or C. URLs requiring +authentication use L to fill in the username and password. -The prefix can instead specify the format of the output: C, -C, C, C, C, C, C, or -C. When a format isn't specified, it's chosen based on -the destination. C is used for the default destination -(stdout), and C is used for an existing directory or -non-existing path. +A prefix can specify the format of the output: C, +C, C, C, C. For a description of +mail formats, see L. -=for comment -TODO: Provide description of formats? +C 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, C, C, C, or C are all supported, +as are the various mbox variants described in L. -Default: - +When a format isn't specified, it's chosen based on the +L destination or prefix. C is used for the +default destination (stdout). -=item -f FORMAT, --format=FORMAT +Using a C prefix with the C<--output> destination is +preferred when not writing to stdout. -Format of results. This option exists as a convenient way to specify -the format for the default stdout destination. Using a C -prefix with the C<--output> destination is preferred otherwise. +=item --no-color + +Disable color (for C<-f reply> and C<-f text>). =item --pretty @@ -78,16 +99,20 @@ 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 -a, --augment +=item --augment + +=item -a Augment output destination instead of clobbering it. =item --no-import-before -Do not importing keywords before writing to an existing output +Do not import keywords before writing to an existing output destination. -=item -t, --threads +=item --threads + +=item -t Return all messages in the same thread as the actual match(es). @@ -99,7 +124,9 @@ of the same thread. TODO: Warning: this flag may become persistent and saved in lei/store unless an MUA unflags it! (Behavior undecided) -=item -d STRATEGY, --dedupe=STRATEGY +=item --dedupe=STRATEGY + +=item -d STRATEGY Strategy for deduplicating messages: C, C, C, or C. @@ -123,7 +150,9 @@ Limit operations to those requiring network access. 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. @@ -135,10 +164,14 @@ 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 -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>. @@ -148,16 +181,22 @@ option applies to C<--include>, C<--exclude>, and C<--only>. Disable the default behavior of memoizing remote messages into the local store. -=item --lock +=item --lock=METHOD L locking method(s) to use: C, C, C or C. Default: fcntl,dotlock -=item -NUMBER, -n NUMBER, --limit=NUMBER +=item --limit=NUMBER + +=item -NUMBER + +=item -n NUMBER -Limit the number of matches. +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 @@ -167,47 +206,116 @@ Shift start of search results. Default: 0 -=item -r, --reverse +=item --reverse + +=item -r 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, C, and C. Default: C -=item -v, --verbose +=item --verbose + +=item -v Provide more feedback on stderr. -=item -q, --quiet +=item --quiet + +=item -q Suppress feedback messages. -=item --torsocks=auto|no|yes, --no-torsocks +=item --torsocks=auto|no|yes + +=item --no-torsocks -Whether to wrap L and L commands with torsocks. +Whether to wrap L and L commands with L. Default: C +=item --proxy=PROTO://HOST[:PORT] + =back +=head1 SEARCH TERMS + +C 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 for more info on labels and keywords. + +Most prefixes are probabilistic, meaning they support stemming +and wildcards (C<*>). Ranges (such as C) and boolean prefixes +do not support stemming or wildcards. +The upstream Xapian query parser documentation fully explains +the query syntax: L + +=head1 TIPS + +C<-f reply> is intended to aid in turning a cover letter +into a reply (since using C +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 -The mail archives are hosted at L -and L +The mail archives are hosted at L and +L =head1 COPYRIGHT -Copyright 2021 all contributors L +Copyright all contributors L License: AGPL-3.0+ L =head1 SEE ALSO -L, +L, L, L, L