lei-q(1)

q - search for messages matching terms

Section 1 lei bookworm source

Description

LEI-Q

NAME

lei-q - search for messages matching terms

SYNOPSIS

lei q [ OPTIONS ] TERM [ TERM... ]

lei q [ OPTIONS ] (--stdin|-)

DESCRIPTION

Search for messages across the lei/store and externals.

OPTIONS

--stdin

Read search terms from stdin.

--no-save

Do not save the search for lei-up(1).

--output=MFOLDER
-o MFOLDER
--mfolder=MFOLDER

Warning: this clobbers and overwrites the output destination unless "--augment" is specified.

Destination for results (e.g., "/tmp/results-Maildir", "imaps://user@mail.example.com/INBOX.test", or "mboxcl2:/tmp/results-mboxcl2"). The prefix may be a supported protocol: "imap://" or "imaps://". URLs requiring authentication use git-credential(1) to fill in the username and password.

A prefix can specify the format of the output: "maildir", "mboxrd", "mboxcl2", "mboxcl", "mboxo". For a description of mail formats, see lei-mail-formats(5).

"maildir" is the default for an existing directory or non-existing path.

Default: "-" (stdout)

--format=FORMAT
-f FORMAT

Format of results to stdout. This option exists as a convenient way to specify the format for the default stdout destination. "reply", "text", "json", "jsonl", or "concatjson" are all supported, as are the various mbox variants described in "--output".

When a format isn’t specified, it’s chosen based on the "--output" destination or prefix. "json" is used for the default destination (stdout).

Using a "format:" prefix with the "--output" destination is preferred when not writing to stdout.

--no-color

Disable color (for "-f reply" and "-f text").

--pretty

Pretty print "json" or "concatjson" output. If stdout is opened to a tty and used as the "--output" destination, "--pretty" is enabled by default.

--mua=COMMAND

A command to run on "--output" Maildir or mbox (e.g., "mutt -f %f"). For a subset of MUAs known to accept a mailbox via "-f", COMMAND can be abbreviated to the name of the program: "mutt", "mailx", "mail", or "neomutt".

--alert=COMMAND[,COMMAND...]

Run "COMMAND" after writing to output. ":WINCH" indicates to send "SIGWINCH" to the "--mua" process. ":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: ":WINCH,:bell" when "--mua" is specified and "--output" doesn’t point to stdout, nothing otherwise.

--augment

-a

Augment output destination instead of clobbering it.

--no-import-before

Do not import keywords before writing to an existing output destination.

--threads

-t

Return all messages in the same thread as the actual match(es).

Using this twice ("-tt") sets the "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)

--dedupe=STRATEGY
-d STRATEGY

Strategy for deduplicating messages: "content", "oid", "mid", or "none".

Default: "content"

--[no-]remote

Whether to include results requiring network access. When local externals are configured, "--remote" must be explicitly passed to enable reporting of results from remote externals.

--no-local

Limit operations to those requiring network access.

--no-external

Don’t include results from externals.

--include=LOCATION
-I LOCATION

Include specified external in search. This option may be given multiple times.

--exclude=LOCATION

Exclude specified external from search. This option may be given multiple times.

--only=LOCATION
-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.

--globoff

-g

Do not match locations using "*?" wildcards and "[]" ranges. This option applies to "--include", "--exclude", and "--only".

--no-import-remote

Disable the default behavior of memoizing remote messages into the local store.

--lock=METHOD

mbox(5) locking method(s) to use: "dotlock", "fcntl", "flock" or "none".

Default: fcntl,dotlock

--limit=NUMBER
-NUMBER
-n NUMBER

Fuzzy limit the number of matches per-local external and lei/store. Messages added by the --threads switch do not count towards this limit, and there is no limit on remote externals.

Default: 10000

--offset=NUMBER

Shift start of search results.

Default: 0

--reverse

-r

Reverse the results. Note that this applies before "--limit".

--sort=KEY
-s KEY

Order the results by KEY. Valid keys are "received", "relevance", and "docid".

Default: "received"

--verbose

-v

Provide more feedback on stderr.

--quiet

-q

Suppress feedback messages.

--torsocks=auto|no|yes
--no-torsocks

Whether to wrap git(1) and curl(1) commands with torsocks(1).

Default: "auto"

--proxy=PROTOCOL://HOST[:PORT]

SEARCH TERMS

"lei q" supports the same search prefixes used by HTTP (S) public-inbox instances:

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

Additional search prefixes which only affect the local lei/store:

L: match the given label
kw: match the given keywords

See lei-tag(1) for more info on labels and keywords.

Most prefixes are probabilistic, meaning they support stemming and wildcards ("*"). Ranges (such as "d:") and boolean prefixes do not support stemming or wildcards. The upstream Xapian query parser documentation fully explains the query syntax: <https://xapian.org/docs/queryparser.html>

TIPS

"-f reply" is intended to aid in turning a cover letter into a reply (since using "git format-patch --in-reply-to=..." is tedious). Results (including "From " lines) should be edited and trimmed in your favorite $EDITOR before sending.

CONTACT

Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>

The mail archives are hosted at <https://public-inbox.org/meta/> and <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

COPYRIGHT

License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>