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