Documentation/lei-q.pod

   1 =head1 NAME
   2
   3 lei-q - search for messages matching terms
   4
   5 =head1 SYNOPSIS
   6
   7 lei q [OPTIONS] TERM [TERM...]
   8
   9 lei q [OPTIONS] (--stdin|-)
  10
  11 =head1 DESCRIPTION
  12
  13 Search for messages across the lei/store and externals.
  14
  15 =for comment
  16 TODO: Give common prefixes, or at least a description/reference.
  17
  18 =head1 OPTIONS
  19
  20 =for comment
  21 TODO: mention curl options?
  22
  23 =over
  24
  25 =item --stdin
  26
  27 Read search terms from stdin.
  28
  29 =item --no-save
  30
  31 Do not save the search for L<lei-up(1)>.
  32
  33 =item --output=MFOLDER
  34
  35 =item -o MFOLDER
  36
  37 =item --mfolder=MFOLDER
  38
  39 Warning: this clobbers and overwrites the output destination unless
  40 L</--augment> is specified.
  41
  42 Destination for results (e.g., C</tmp/results-Maildir>,
  43 C<imaps://user@mail.example.com/INBOX.test>, or
  44 C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
  45 C<imap://> or C<imaps://>.  URLs requiring
  46 authentication use L<git-credential(1)> to
  47 fill in the username and password.
  48
  49 A prefix can specify the format of the output: C<maildir>,
  50 C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>.  For a description of
  51 mail formats, see L<lei-mail-formats(5)>.
  52
  53 C<maildir> is the default for an existing directory or non-existing path.
  54
  55 Default: C<-> (stdout)
  56
  57 =item --format=FORMAT
  58
  59 =item -f FORMAT
  60
  61 Format of results to stdout.  This option exists as a convenient
  62 way to specify the format for the default stdout destination.
  63 C<reply>, C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
  64 as are the various mbox variants described in L</--output>.
  65
  66 When a format isn't specified, it's chosen based on the
  67 L</--output> destination or prefix.  C<json> is used for the
  68 default destination (stdout).
  69
  70 Using a C<format:> prefix with the C<--output> destination is
  71 preferred when not writing to stdout.
  72
  73 =item --no-color
  74
  75 Disable color (for C<-f reply> and C<-f text>).
  76
  77 =item --pretty
  78
  79 Pretty print C<json> or C<concatjson> output.  If stdout is opened to
  80 a tty and used as the C<--output> destination, C<--pretty> is enabled
  81 by default.
  82
  83 =item --mua=COMMAND
  84
  85 A command to run on C<--output> Maildir or mbox (e.g., C<mutt -f %f>).
  86 For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can
  87 be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>,
  88 or C<neomutt>.
  89
  90 =item --alert=COMMAND[,COMMAND...]
  91
  92 Run C<COMMAND> after writing to output.  C<:WINCH> indicates to send
  93 C<SIGWINCH> to the C<--mua> process.  C<:bell> indicates to print a
  94 bell code.  Any other value is interpreted as a command to execute as
  95 is.
  96
  97 This option may be given multiple times.
  98
  99 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
 100 doesn't point to stdout, nothing otherwise.
 101
 102 =item --augment
 103
 104 =item -a
 105
 106 Augment output destination instead of clobbering it.
 107
 108 =item --no-import-before
 109
 110 Do not import keywords before writing to an existing output
 111 destination.
 112
 113 =item --threads
 114
 115 =item -t
 116
 117 Return all messages in the same thread as the actual match(es).
 118
 119 Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
 120 on messages which were actual matches.  This is useful to distinguish
 121 messages which were direct hits from messages which were merely part
 122 of the same thread.
 123
 124 TODO: Warning: this flag may become persistent and saved in
 125 lei/store unless an MUA unflags it!  (Behavior undecided)
 126
 127 =item --dedupe=STRATEGY
 128
 129 =item -d STRATEGY
 130
 131 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
 132 C<none>.
 133
 134 Default: C<content>
 135
 136 =for comment
 137 TODO: Provide description of strategies?
 138
 139 =item --[no-]remote
 140
 141 Whether to include results requiring network access.  When local
 142 externals are configured, C<--remote> must be explicitly passed to
 143 enable reporting of results from remote externals.
 144
 145 =item --no-local
 146
 147 Limit operations to those requiring network access.
 148
 149 =item --no-external
 150
 151 Don't include results from externals.
 152
 153 =item --include=LOCATION
 154
 155 =item -I LOCATION
 156
 157 Include specified external in search.  This option may be given
 158 multiple times.
 159
 160 =item --exclude=LOCATION
 161
 162 Exclude specified external from search.  This option may be given
 163 multiple times.
 164
 165 =item --only=LOCATION
 166
 167 =item -O LOCATION
 168
 169 Use only the specified external for search.  This option may be given
 170 multiple times, in which case the search uses only the specified set.
 171
 172 =item --globoff
 173
 174 =item -g
 175
 176 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 177 option applies to C<--include>, C<--exclude>, and C<--only>.
 178
 179 =item --no-import-remote
 180
 181 Disable the default behavior of memoizing remote messages into the
 182 local store.
 183
 184 =item --lock=METHOD
 185
 186 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
 187 C<none>.
 188
 189 Default: fcntl,dotlock
 190
 191 =item --limit=NUMBER
 192
 193 =item -NUMBER
 194
 195 =item -n NUMBER
 196
 197 Fuzzy limit the number of matches per-local external and lei/store.
 198 Messages added by the L<--threads> switch do not count towards this
 199 limit, and there is no limit on remote externals.
 200
 201 Default: 10000
 202
 203 =item --offset=NUMBER
 204
 205 Shift start of search results.
 206
 207 Default: 0
 208
 209 =item --reverse
 210
 211 =item -r
 212
 213 Reverse the results.  Note that this applies before C<--limit>.
 214
 215 =item --sort=KEY
 216
 217 =item -s KEY
 218
 219 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 220 and C<docid>.
 221
 222 Default: C<received>
 223
 224 =item --verbose
 225
 226 =item -v
 227
 228 Provide more feedback on stderr.
 229
 230 =item --quiet
 231
 232 =item -q
 233
 234 Suppress feedback messages.
 235
 236 =item --torsocks=auto|no|yes
 237
 238 =item --no-torsocks
 239
 240 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 241
 242 Default: C<auto>
 243
 244 =item --proxy=PROTO://HOST[:PORT]
 245
 246 =back
 247
 248 =head1 SEARCH TERMS
 249
 250 C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
 251 instances:
 252
 253 =for comment
 254 AUTO-GENERATED-SEARCH-TERMS-BEGIN
 255
 256   s:       match within Subject  e.g. s:"a quick brown fox"
 257   d:       match date-time range, git "approxidate" formats supported
 258            Open-ended ranges such as `d:last.week..' and
 259            `d:..2.days.ago' are supported
 260   b:       match within message body, including text attachments
 261   nq:      match non-quoted text within message body
 262   q:       match quoted text within message body
 263   n:       match filename of attachment(s)
 264   t:       match within the To header
 265   c:       match within the Cc header
 266   f:       match within the From header
 267   a:       match within the To, Cc, and From headers
 268   tc:      match within the To and Cc headers
 269   l:       match contents of the List-Id header
 270   bs:      match within the Subject and body
 271   dfn:     match filename from diff
 272   dfa:     match diff removed (-) lines
 273   dfb:     match diff added (+) lines
 274   dfhh:    match diff hunk header context (usually a function name)
 275   dfctx:   match diff context lines
 276   dfpre:   match pre-image git blob ID
 277   dfpost:  match post-image git blob ID
 278   dfblob:  match either pre or post-image git blob ID
 279   rt:      match received time, like `d:' if sender's clock was correct
 280
 281 =for comment
 282 AUTO-GENERATED-SEARCH-TERMS-END
 283
 284 Additional search prefixes which only affect the local lei/store:
 285
 286   L:       match the given label
 287   kw:      match the given keywords
 288
 289 See L<lei-tag(1)> for more info on labels and keywords.
 290
 291 Most prefixes are probabilistic, meaning they support stemming
 292 and wildcards (C<*>).  Ranges (such as C<d:>) and boolean prefixes
 293 do not support stemming or wildcards.
 294 The upstream Xapian query parser documentation fully explains
 295 the query syntax: L<https://xapian.org/docs/queryparser.html>
 296
 297 =head1 TIPS
 298
 299 C<-f reply> is intended to aid in turning a cover letter
 300 into a reply (since using C<git format-patch --in-reply-to=...>
 301 is tedious).  Results (including "From " lines) should be edited
 302 and trimmed in your favorite C<$EDITOR> before sending.
 303
 304 =head1 CONTACT
 305
 306 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 307
 308 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 309 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 310
 311 =head1 COPYRIGHT
 312
 313 Copyright all contributors L<mailto:meta@public-inbox.org>
 314
 315 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 316
 317 =head1 SEE ALSO
 318
 319 L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
 320 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>