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 =item -d STRATEGY, --dedupe=STRATEGY
  83
  84 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
  85 C<none>.
  86
  87 Default: C<content>
  88
  89 TODO: Provide description of strategies?
  90
  91 =item --[no-]remote
  92
  93 Whether to include results requiring network access.  When local
  94 externals are configured, C<--remote> must be explicitly passed to
  95 enable reporting of results from remote externals.
  96
  97 =item --no-local
  98
  99 Limit operations to those requiring network access.
 100
 101 =item --no-external
 102
 103 Don't include results from externals.
 104
 105 =item -I LOCATION, --include=LOCATION
 106
 107 Include specified external in search.  This option may be given
 108 multiple times.
 109
 110 =item --exclude=LOCATION
 111
 112 Exclude specified external from search.  This option may be given
 113 multiple times.
 114
 115 =item --only=LOCATION
 116
 117 Use only the specified external for search.  This option may be given
 118 multiple times, in which case the search uses only the specified set.
 119
 120 =item -g, --globoff
 121
 122 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 123 option applies to C<--include>, C<--exclude>, and C<--only>.
 124
 125 =item -NUMBER, -n NUMBER, --limit=NUMBER
 126
 127 Limit the number of matches.
 128
 129 Default: 10000
 130
 131 =item --offset=NUMBER
 132
 133 Shift start of search results.
 134
 135 Default: 0
 136
 137 =item -r, --reverse
 138
 139 Reverse the results.  Note that this applies before C<--limit>.
 140
 141 =item -s KEY, --sort=KEY
 142
 143 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 144 and C<docid>.
 145
 146 Default: C<received>
 147
 148 =item -v, --verbose
 149
 150 Provide more feedback on stderr.
 151
 152 =item -q, --quiet
 153
 154 Suppress feedback messages.
 155
 156 =item --torsocks=auto|no|yes, --no-torsocks
 157
 158 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 159
 160 Default: C<auto>
 161
 162 =back
 163
 164 =head1 CONTACT
 165
 166 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 167
 168 The mail archives are hosted at L<https://public-inbox.org/meta/>
 169 and L<http://hjrcffqmbrq6wope.onion/meta/>
 170
 171 =head1 COPYRIGHT
 172
 173 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 174
 175 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 176
 177 =head1 SEE ALSO
 178
 179 L<lei-add-external(1)>,
 180 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>