LEI-Q(1)

📦

version 2.1.0 · 5 versions

2.1.0 · arch rolling, nixos 26.05, nixpkgs unstable (latest)
1.9.0 · epel 9
2.0.0~20230714git590023f · fedora 43, fedora 44
1.9.0 · ubuntu resolute, ubuntu stonking
1.9.0 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing

, in arch rolling, nixos 26.05, nixpkgs unstable

okay bestie, buckle up: this is lei-q(1) from the public-inbox user manual, and it’s literally the search page for messages matching terms. No cap, it’s giving main-character search energy. 🦋

🌸 NAME 🌸

lei-q — search for messages matching terms. That’s the whole name era. ✨

🎀 SYNOPSIS 🎀

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

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

💅 DESCRIPTION 💅

Search for messages across the lei/store and externals. That’s the vibe — your little search goblin across local store and external sources. 💖

✨ OPTIONS ✨

--stdin — read the search terms from stdin, because typing is optional sometimes. 🫶
--no-save — do not save the search for lei-up(1). No archival pressure, bestie.
--output=MFOLDER, -o MFOLDER, --mfolder=MFOLDER — destination for results. Warning: this clobbers and overwrites the output destination unless --augment is specified. Use it with stuff like "/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). "v2:/path/to/inbox" may be used to create a new inbox of public-inbox-v2-format(5). The new inbox will not be configured in the public-inbox-config(5) file. "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). Your retinas can chill.
--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. Slay.
--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. Respectful queen behavior.
--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 --augment is used. This is a big-deal warning, bestie. 😭
--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). Caveat: -tt only works on locally-indexed messages at the moment, and not on remote (HTTP(S)) endpoints.
--thread-id=MSGID, -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).
--jobs=QUERY_WORKERS[,WRITE_WORKERS], --jobs=,WRITE_WORKERS, -j QUERY_WORKERS[,WRITE_WORKERS], -j ,WRITE_WORKERS — set the number of query and write worker processes for parallelism. "QUERY_WORKERS" defaults to the number of CPUs available, but 4 per remote (HTTP/HTTPS) host. "WRITE_WORKERS" defaults to 75% of the number of CPUs available for Maildir and mbox* destinations, but 4 per IMAP/IMAPS host. Omitting "QUERY_WORKERS" but leaving the comma (",") allows one to only set "WRITE_WORKERS".
--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] — the original page lists this one without extra prose, so I’m not inventing details; it’s literally this option signature and nothing more in the source. 🫶

🔍 SEARCH TERMS 🔍

lei q supports the same search prefixes used by HTTP(S) public-inbox instances. Here’s the whole menu, bestie:

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 💡

okay so -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. That’s the whole tip, and it’s giving “edit before you send, bestie.” 💖