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