1MU FIND(1) General Commands Manual MU FIND(1)
2
6 mu find - find e-mail messages in the mu database.
7
10 mu [common-options] find [options] <search expression>
11
14 mu find is the mu command for searching e-mail message that were stored
15 earlier using mu index(1).
16
19 mu find starts a search for messages in the database that match some
20 search pattern. The search patterns are described in detail in mu-
21 query(7).
22 For example:
25 $ mu find subject:snow and date:2009..
27 would find all messages in 2009 with 'snow' in the subject field, e.g:
31 2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow
33 2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow
34 Note, this the default, plain-text output, which is the default, so you
38 don't have to use --format=plain. For other types of output (such as
39 symlinks, XML or s-expressions), see the discussion in the OPTIONS-sec‐
40 tion below about --format.
41 The search pattern is taken as a command-line parameter. If the search
44 parameter consists of multiple parts (as in the example) they are
45 treated as if there were a logical and between them.
46 For details on the possible queries, see mu-query(7).
49
52 Note, some of the important options are described in the *mu*(1) man-
53 page and not here, as they apply to multiple mu-commands.
54 The find-command has various options that influence the way mu displays
57 the results. If you don't specify anything, the defaults are fields="d
58 f s", --sortfield=date and --reverse.
59 -f, --fields=<fields>
62 specifies a string that determines which fields are shown in the out‐
63 put. This string consists of a number of characters (such as 's' for
64 subject or 'f' for from), which will replace with the actual field in
65 the output. Fields that are not known will be output as-is, allowing
66 for some simple formatting.
67 For example:
70 $ mu find subject:snow --fields "d f s"
72 lists the date, subject and sender of all messages with 'snow' in the
76 their subject.
77 The table of replacement characters is superset of the list mentions
80 for search parameters, such as:
81 t *t*o: recipient
82 d Sent *d*ate of the message
83 f Message sender (*f*rom:)
84 g Message flags (fla*g*s)
85 l Full path to the message (*l*ocation)
86 s Message *s*ubject
87 i Message-*i*d
88 m *m*aildir
89 For the complate list, see mu-fields(1).
93 The message flags are described in mu-query(7). As an example, a mes‐
96 sage which is 'seen', has an attachment and is signed would have 'asz'
97 as its corresponding output string, while an encrypted new message
98 would have 'nx'.
99 -s, --sortfield=<field> and -z,--reverse
102 specify the field to sort the search results by and the direction
103 (i.e.,
104 cc,c Cc (carbon-copy) recipient(s)
106 date,d Message sent date
107 from,f Message sender
108 maildir,m Maildir
109 msgid,i Message id
110 prio,p Nessage priority
111 subject,s Message subject
112 to,t To:-recipient(s)
113 For the complete list use can use the mu fields command; see mu-
117 fields(1).
118 Thus, for example, to sort messages by date, you could specify:
121 $ mu find fahrrad --fields "d f s" --sortfield=date --reverse
123 Note, if you specify a sortfield, by default, messages are sorted in
127 reverse (descending) order (e.g., from lowest to highest). This is usu‐
128 ally a good choice, but for dates it may be more useful to sort in the
129 opposite direction.
130 -n, --maxnum=<number>
133 If > 0, display maximally that number of entries. If not specified, all
134 matching entries are displayed.
135 --summary-len=<number>
138 If > 0, use that number of lines of the message to provide a summary.
139 --format=<plain|links|xquery|xml|sexp>
142 output results in the specified format:
143 — The default is plain, i.e normal output with one line per message.
146 — links outputs the results as a maildir with symbolic links to the
148 found messages. This enables easy integration with mail-clients
149 (see below for more information).
150 — xml formats the search results as XML.
152 — sexp formats the search results as an s-expression as used in Lisp
154 programming environments.
155 — xquery shows the Xapian query corresponding to your search terms.
157 This is meant for for debugging purposes.
158 --linksdir=<dir> and -c, --clearlinks
161 when using -format=links, output the results as a maildir with symbolic
162 links to the found messages. This enables easy integration with mail-
163 clients (see below for more information). mu will create the maildir if
164 it does not exist yet.
165 If you specify --clearlinks, existing symlinks will be cleared from the
168 target directories; this allows for re-use of the same maildir. How‐
169 ever, this option will delete any symlink it finds, so be careful.
170 $ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks
172 stores links to found messages in ~/Maildir/search. If the directory
176 does not exist yet, it will be created. Note: when mu creates a Maildir
177 for these links, it automatically inserts a .noindex file, to exclude
178 the directory from mu index.
179 --after=<timestamp>
182 only show messages whose message files were last modified (mtime) after
183 <timestamp>. <timestamp> is a UNIX timet value, the number of seconds
184 since 1970-01-01 (in UTC).
185 From the command line, you can use the date command to get this value.
188 For example, only consider messages modified (or created) in the last 5
189 minutes, you could specify
190 --after=`date +%s --date='5 min ago'`
191 This is assuming the GNU date command.
194 --exec=<command>
197 the --exec coption causes the command to be executed on each matched
198 message; for example, to see the raw text of all messages matching
199 'milkshake', you could use:
200 $ mu find milkshake --exec='less'
201 which is roughly equivalent to:
204 $ mu find milkshake --fields="l" | xargs less
205 -b, --bookmark=<bookmark>
209 use a bookmarked search query. Using this option, a query from your
210 bookmark file will be prepended to other search queries. See mu-book‐
211 marks(5) for the details of the bookmarks file.
212 -u, --skip-dups
216 whenever there are multiple messages with the same message-id field,
217 only show the first one. This is useful if you have copies of the same
218 message, which is a common occurrence when using e.g. Gmail together
219 with offlineimap.
220 -r, --include-related
223 include messages being referred to by the matched messages -- i.e.. in‐
224 clude messages that are part of the same message thread as some matched
225 messages. This is useful if you want Gmail-style 'conversations'.
226 -t, --threads
229 show messages in a 'threaded' format -- that is, with indentation and
230 arrows showing the conversation threads in the list of matching mes‐
231 sages. When using this, sorting is chronological (by date), based on
232 the newest message in a thread.
233 Messages in the threaded list are indented based on the depth in the
236 discussion, and are prefix with a kind of arrow with thread-related in‐
237 formation about the message, as in the following table:
238 | | normal | orphan | duplicate |
239 |-------------+--------+--------+-----------|
240 | first child | `-> | `*> | `=> |
241 | other | |-> | |*> | |=> |
242 Here, an 'orphan' is a message without a parent message (in the list of
246 matches), and a duplicate is a message whose message-id was already
247 seen before; not this may not really be the same message, if the mes‐
248 sage-id was copied.
249 The algorithm used for determining the threads is based on Jamie Za‐
252 winksi's description: http://www.jwz.org/doc/threading.html
253 --muhome
256 use a non-default directory to store and read the database, write the
257 logs, etc. By default, mu uses the XDG Base Directory Specification
258 (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Ear‐
259 lier versions of mu defaulted to ~/.mu, which now requires
260 --muhome=~/.mu.
261 The environment variable MUHOME can be used as an alternative to
264 --muhome. The latter has precedence.
265
268 -d, --debug
269 makes mu generate extra debug information, useful for debugging the
270 program itself. By default, debug information goes to the log file,
271 ~/.cache/mu/mu.log. It can safely be deleted when mu is not running.
272 When running with --debug option, the log file can grow rather quickly.
273 See the note on logging below.
274 -q, --quiet
277 causes mu not to output informational messages and progress information
278 to standard output, but only to the log file. Error messages will still
279 be sent to standard error. Note that mu index is much faster with
280 --quiet, so it is recommended you use this option when using mu from
281 scripts etc.
282 --log-stderr
285 causes mu to not output log messages to standard error, in addition to
286 sending them to the log file.
287 --nocolor
290 do not use ANSI colors. The environment variable NO_COLOR can be used
291 as an alternative to --nocolor.
292 -V, --version
295 prints mu version and copyright information.
296 -h, --help
299 lists the various command line options.
300
303 mutt
304 For mutt you can use the following in your muttrc; pressing the F8 key
305 will start a search, and F9 will take you to the results.
306 # mutt macros for mu
308 macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \
309 "mu find"
310 macro index <F9> "<change-folder-readonly>~/Maildir/search" \
311 "mu find results"
312 Wanderlust
317 Sam B suggested the following on the mu-mailing list. First add the
318 following to your Wanderlust configuration file:
319 (require 'elmo-search)
321 (elmo-search-register-engine
322 'mu 'local-file
323 :prog "/usr/local/bin/mu" ;; or wherever you've installed it
324 :args '("find" pattern "--fields" "l") :charset 'utf-8)
325 (setq elmo-search-default-engine 'mu)
327 ;; for when you type "g" in folder or summary.
328 (setq wl-default-spec "[")
329 Now, you can search using the g key binding; you can also create perma‐
333 nent virtual folders when the messages matching some expression by
334 adding something like the following to your folders file.
335 VFolders {
337 [date:today..now]!mu "Today"
338 [size:1m..100m]!mu "Big"
339 [flag:unread]!mu "Unread"
340 }
341 After restarting Wanderlust, the virtual folders should appear.
345
348 mu find output is encoded according the locale for --format=plain (the
349 default), and UTF-8 for all other formats (sexp, xml).
350
353 This command returns 0 upon successful completion, or a non-zero exit
354 code otherwise. Typical values are 2 (no matches found), 11 (database
355 schema mismatch) and 12 (failed to acquire database lock).
356 no matches found (2)
359 Nothing matching found; try a different query
360 database schema mismatch (11)
363 You need to re-initialize mu, see mu-init(1)
364 failed to acquire lock (19)
367 Some other program has exclusive access to the mu (Xapian) database
368
371 Please report bugs at https://github.com/djcb/mu/issues.
372
375 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
376
379 This manpage is part of mu 1.10.5.
380 Copyright © 2022-2023 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL ver‐
383 sion 3 or later https://gnu.org/licenses/gpl.html. This is free soft‐
384 ware: you are free to change and redistribute it. There is NO WARRANTY,
385 to the extent permitted by law.
386
389 mu(1), mu-index(1), mu-query(7), mu-fields(1)
390 MU FIND(1)