X-Git-Url: http://www.git.stargrave.org/?p=public-inbox.git;a=blobdiff_plain;f=Documentation%2Flei-q.pod;h=fe281d7b0121945fa3df486d5509c8edcd109bbd;hp=e307e0205f932b0a7051b4379ccf50e8154af7d1;hb=1f1b1f0e22f7b4cbe5c8e843c1932222c0461393;hpb=82691a35fcf3b8945539084a029722b3458d72c8 diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod index e307e020..fe281d7b 100644 --- a/Documentation/lei-q.pod +++ b/Documentation/lei-q.pod @@ -6,29 +6,73 @@ lei-q - search for messages matching terms lei q [OPTIONS] TERM [TERM...] +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. =head1 OPTIONS +=for comment +TODO: mention curl options? + =over -=item -o PATH, --output=PATH, --mfolder=PATH +=item --stdin + +Read search terms from stdin. + +=item --no-save + +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 or C. URLs requiring +authentication use L to +fill in the username and password. + +A prefix can specify the format of the output: C, +C, C, C, C. For a description of +mail formats, see L. + +C is the default for an existing directory or non-existing path. + +Default: C<-> (stdout) + +=item --format=FORMAT -Destination for results (e.g., C or - for stdout). +=item -f FORMAT -Default: - +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. -=item -f FORMAT, --format=FORMAT +When a format isn't specified, it's chosen based on the +L destination or prefix. C is used for the +default destination (stdout). -Format of results: C, C, C, C, -C, C, C, or C. The default format -used depends on C<--output>. +Using a C prefix with the C<--output> destination is +preferred when not writing to stdout. -TODO: Provide description of formats? +=item --no-color + +Disable color (for C<-f reply> and C<-f text>). =item --pretty @@ -36,28 +80,60 @@ Pretty print C or C output. If stdout is opened to a tty and used as the C<--output> destination, C<--pretty> is enabled by default. -=item --mua-cmd=COMMAND, --mua=COMMAND +=item --mua=COMMAND A command to run on C<--output> Maildir or mbox (e.g., C). For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can be abbreviated to the name of the program: C, C, C, or C. +=item --alert=COMMAND[,COMMAND...] + +Run C after writing to output. C<:WINCH> indicates to send +C 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 -t, --thread +=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). -=item -d STRATEGY, --dedupe=STRATEGY +Using this twice (C<-tt>) sets the C (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, C, C, or C. Default: C +=for comment TODO: Provide description of strategies? =item --[no-]remote @@ -74,9 +150,53 @@ Limit operations to those requiring network access. Don't include results from externals. -=item -NUMBER, -n NUMBER, --limit=NUMBER +=item --include=LOCATION + +=item -I LOCATION -Limit the number of matches. +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 locking method(s) to use: C, C, C or +C. + +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 @@ -86,42 +206,115 @@ 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 --torsocks=auto|no|yes, --no-torsocks +=item --quiet + +=item -q + +Suppress feedback messages. + +=item --torsocks=auto|no|yes + +=item --no-torsocks Whether to wrap L and L commands with torsocks. 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 + 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