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