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