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