LEI-Q(1)                   public-inbox user manual                   LEI-Q(1)

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=PROTO://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
         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
       Copyright all contributors <mailto:meta@public-inbox.org>

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

SEE ALSO
       lei-add-external(1), lei-lcat(1), lei-up(1), Xapian::QueryParser Syntax
       <https://xapian.org/docs/queryparser.html>

public-inbox.git                  1993-10-02                          LEI-Q(1)