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