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 --output=MFOLDER
  30
  31 =item -o MFOLDER
  32
  33 =item --mfolder=MFOLDER
  34
  35 Warning: this clobbers and overwrites the output destination unless
  36 L</--augment> is specified.
  37
  38 Destination for results (e.g., C</tmp/results-Maildir>,
  39 C<imaps://user@mail.example.com/INBOX.test>, or
  40 C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
  41 C<imap://> or C<imaps://>.  URLs requiring
  42 authentication must use L<netrc(5)> and/or L<git-credential(1)> to
  43 fill in the username and password.
  44
  45 The prefix can instead specify the format of the output: C<maildir>,
  46 C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>, C<json>, C<jsonl>, or
  47 C<concatjson>.  When a format isn't specified, it's chosen based on
  48 the destination.  C<json> is used for the default destination
  49 (stdout), and C<maildir> is used for an existing directory or
  50 non-existing path.
  51
  52 =for comment
  53 TODO: Provide description of formats?
  54
  55 Default: C<-> (stdout)
  56
  57 =item --format=FORMAT
  58
  59 =item -f FORMAT
  60
  61 Format of results.  This option exists as a convenient way to specify
  62 the format for the default stdout destination.  Using a C<format:>
  63 prefix with the C<--output> destination is preferred otherwise.
  64
  65 =item --pretty
  66
  67 Pretty print C<json> or C<concatjson> output.  If stdout is opened to
  68 a tty and used as the C<--output> destination, C<--pretty> is enabled
  69 by default.
  70
  71 =item --mua=COMMAND
  72
  73 A command to run on C<--output> Maildir or mbox (e.g., C<mutt -f %f>).
  74 For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can
  75 be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>,
  76 or C<neomutt>.
  77
  78 =item --alert=COMMAND[,COMMAND...]
  79
  80 Run C<COMMAND> after writing to output.  C<:WINCH> indicates to send
  81 C<SIGWINCH> to the C<--mua> process.  C<:bell> indicates to print a
  82 bell code.  Any other value is interpreted as a command to execute as
  83 is.
  84
  85 This option may be given multiple times.
  86
  87 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
  88 doesn't point to stdout, nothing otherwise.
  89
  90 =item --augment
  91
  92 =item -a
  93
  94 Augment output destination instead of clobbering it.
  95
  96 =item --no-import-before
  97
  98 Do not importing keywords before writing to an existing output
  99 destination.
 100
 101 =item --threads
 102
 103 =item -t
 104
 105 Return all messages in the same thread as the actual match(es).
 106
 107 Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
 108 on messages which were actual matches.  This is useful to distinguish
 109 messages which were direct hits from messages which were merely part
 110 of the same thread.
 111
 112 TODO: Warning: this flag may become persistent and saved in
 113 lei/store unless an MUA unflags it!  (Behavior undecided)
 114
 115 =item --dedupe=STRATEGY
 116
 117 =item -d STRATEGY
 118
 119 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
 120 C<none>.
 121
 122 Default: C<content>
 123
 124 =for comment
 125 TODO: Provide description of strategies?
 126
 127 =item --[no-]remote
 128
 129 Whether to include results requiring network access.  When local
 130 externals are configured, C<--remote> must be explicitly passed to
 131 enable reporting of results from remote externals.
 132
 133 =item --no-local
 134
 135 Limit operations to those requiring network access.
 136
 137 =item --no-external
 138
 139 Don't include results from externals.
 140
 141 =item --include=LOCATION
 142
 143 =item -I LOCATION
 144
 145 Include specified external in search.  This option may be given
 146 multiple times.
 147
 148 =item --exclude=LOCATION
 149
 150 Exclude specified external from search.  This option may be given
 151 multiple times.
 152
 153 =item --only=LOCATION
 154
 155 Use only the specified external for search.  This option may be given
 156 multiple times, in which case the search uses only the specified set.
 157
 158 =item --globoff
 159
 160 =item -g
 161
 162 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 163 option applies to C<--include>, C<--exclude>, and C<--only>.
 164
 165 =item --no-import-remote
 166
 167 Disable the default behavior of memoizing remote messages into the
 168 local store.
 169
 170 =item --lock
 171
 172 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
 173 C<none>.
 174
 175 Default: fcntl,dotlock
 176
 177 =item --limit=NUMBER
 178
 179 =item -NUMBER
 180
 181 =item -n NUMBER
 182
 183 Limit the number of matches.
 184
 185 Default: 10000
 186
 187 =item --offset=NUMBER
 188
 189 Shift start of search results.
 190
 191 Default: 0
 192
 193 =item --reverse
 194
 195 =item -r
 196
 197 Reverse the results.  Note that this applies before C<--limit>.
 198
 199 =item --sort=KEY
 200
 201 =item -s KEY
 202
 203 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 204 and C<docid>.
 205
 206 Default: C<received>
 207
 208 =item --verbose
 209
 210 =item -v
 211
 212 Provide more feedback on stderr.
 213
 214 =item --quiet
 215
 216 =item -q
 217
 218 Suppress feedback messages.
 219
 220 =item --torsocks=auto|no|yes
 221
 222 =item --no-torsocks
 223
 224 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 225
 226 Default: C<auto>
 227
 228 =back
 229
 230 =head1 CONTACT
 231
 232 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 233
 234 The mail archives are hosted at L<https://public-inbox.org/meta/>
 235 and L<http://hjrcffqmbrq6wope.onion/meta/>
 236
 237 =head1 COPYRIGHT
 238
 239 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 240
 241 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 242
 243 =head1 SEE ALSO
 244
 245 L<lei-add-external(1)>,
 246 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>