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 --jobs=QUERY_WORKERS[,WRITE_WORKERS]
 128 =item --jobs=,WRITE_WORKERS
 129
 130 =item -j QUERY_WORKERS[,WRITE_WORKERS]
 131 =item -j ,WRITE_WORKERS
 132
 133 Set the number of query and write worker processes for parallelism.
 134
 135 C<QUERY_WORKERS> defaults to the number of CPUs available, but 4 per
 136 remote (HTTP/HTTPS) host.
 137
 138 C<WRITE_WORKERS> defaults to 75% of the number of CPUs available for
 139 Maildir and mbox* destinations, but 4 per IMAP/IMAPS host.
 140
 141 Omitting C<QUERY_WORKERS> but leaving the comma (C<,>) allows
 142 one to only set C<WRITE_WORKERS>
 143
 144 =item --dedupe=STRATEGY
 145
 146 =item -d STRATEGY
 147
 148 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
 149 C<none>.
 150
 151 Default: C<content>
 152
 153 =for comment
 154 TODO: Provide description of strategies?
 155
 156 =item --[no-]remote
 157
 158 Whether to include results requiring network access.  When local
 159 externals are configured, C<--remote> must be explicitly passed to
 160 enable reporting of results from remote externals.
 161
 162 =item --no-local
 163
 164 Limit operations to those requiring network access.
 165
 166 =item --no-external
 167
 168 Don't include results from externals.
 169
 170 =item --include=LOCATION
 171
 172 =item -I LOCATION
 173
 174 Include specified external in search.  This option may be given
 175 multiple times.
 176
 177 =item --exclude=LOCATION
 178
 179 Exclude specified external from search.  This option may be given
 180 multiple times.
 181
 182 =item --only=LOCATION
 183
 184 =item -O LOCATION
 185
 186 Use only the specified external for search.  This option may be given
 187 multiple times, in which case the search uses only the specified set.
 188
 189 =item --globoff
 190
 191 =item -g
 192
 193 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 194 option applies to C<--include>, C<--exclude>, and C<--only>.
 195
 196 =item --no-import-remote
 197
 198 Disable the default behavior of memoizing remote messages into the
 199 local store.
 200
 201 =item --lock=METHOD
 202
 203 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
 204 C<none>.
 205
 206 Default: fcntl,dotlock
 207
 208 =item --limit=NUMBER
 209
 210 =item -NUMBER
 211
 212 =item -n NUMBER
 213
 214 Fuzzy limit the number of matches per-local external and lei/store.
 215 Messages added by the L<--threads> switch do not count towards this
 216 limit, and there is no limit on remote externals.
 217
 218 Default: 10000
 219
 220 =item --offset=NUMBER
 221
 222 Shift start of search results.
 223
 224 Default: 0
 225
 226 =item --reverse
 227
 228 =item -r
 229
 230 Reverse the results.  Note that this applies before C<--limit>.
 231
 232 =item --sort=KEY
 233
 234 =item -s KEY
 235
 236 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 237 and C<docid>.
 238
 239 Default: C<received>
 240
 241 =item --verbose
 242
 243 =item -v
 244
 245 Provide more feedback on stderr.
 246
 247 =item --quiet
 248
 249 =item -q
 250
 251 Suppress feedback messages.
 252
 253 =item --torsocks=auto|no|yes
 254
 255 =item --no-torsocks
 256
 257 Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
 258
 259 Default: C<auto>
 260
 261 =item --proxy=PROTOCOL://HOST[:PORT]
 262
 263 =back
 264
 265 =head1 SEARCH TERMS
 266
 267 C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
 268 instances:
 269
 270 =for comment
 271 AUTO-GENERATED-SEARCH-TERMS-BEGIN
 272
 273   s:        match within Subject  e.g. s:"a quick brown fox"
 274   d:        match date-time range, git "approxidate" formats supported
 275             Open-ended ranges such as `d:last.week..' and
 276             `d:..2.days.ago' are supported
 277   b:        match within message body, including text attachments
 278   nq:       match non-quoted text within message body
 279   q:        match quoted text within message body
 280   n:        match filename of attachment(s)
 281   t:        match within the To header
 282   c:        match within the Cc header
 283   f:        match within the From header
 284   a:        match within the To, Cc, and From headers
 285   tc:       match within the To and Cc headers
 286   l:        match contents of the List-Id header
 287   bs:       match within the Subject and body
 288   dfn:      match filename from diff
 289   dfa:      match diff removed (-) lines
 290   dfb:      match diff added (+) lines
 291   dfhh:     match diff hunk header context (usually a function name)
 292   dfctx:    match diff context lines
 293   dfpre:    match pre-image git blob ID
 294   dfpost:   match post-image git blob ID
 295   dfblob:   match either pre or post-image git blob ID
 296   patchid:  match `git patch-id --stable' output
 297   rt:       match received time, like `d:' if sender's clock was correct
 298
 299 =for comment
 300 AUTO-GENERATED-SEARCH-TERMS-END
 301
 302 Additional search prefixes which only affect the local lei/store:
 303
 304   L:       match the given label
 305   kw:      match the given keywords
 306
 307 See L<lei-tag(1)> for more info on labels and keywords.
 308
 309 Most prefixes are probabilistic, meaning they support stemming
 310 and wildcards (C<*>).  Ranges (such as C<d:>) and boolean prefixes
 311 do not support stemming or wildcards.
 312 The upstream Xapian query parser documentation fully explains
 313 the query syntax: L<https://xapian.org/docs/queryparser.html>
 314
 315 =head1 TIPS
 316
 317 C<-f reply> is intended to aid in turning a cover letter
 318 into a reply (since using C<git format-patch --in-reply-to=...>
 319 is tedious).  Results (including "From " lines) should be edited
 320 and trimmed in your favorite C<$EDITOR> before sending.
 321
 322 =head1 CONTACT
 323
 324 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 325
 326 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 327 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 328
 329 =head1 COPYRIGHT
 330
 331 Copyright all contributors L<mailto:meta@public-inbox.org>
 332
 333 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 334
 335 =head1 SEE ALSO
 336
 337 L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
 338 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>