1
.TH MU FIND 1 "December 2011" "User Manuals"
5
mu find \- find e-mail messages in the \fBmu\fR database.
9
.B mu find [options] <search expression>
13
\fBmu find\fR is the \fBmu\fR command for searching e-mail message that
14
were stored earlier using
19
\fBmu find\fR starts a search for messages in the database that match some
20
search pattern. For example:
23
$ mu find subject:snow from:john
26
would find all messages from John with 'snow' in the subject field, something
30
2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow
31
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 don't
35
have to use \fB--format=plain\fR. For other types of output (such as symlinks,
36
XML or s-expressions), see the discussion in the \fBOPTIONS\fR-section
37
below about \fB--format\fR.
39
The search pattern is taken as a command-line parameter. If the search
40
parameter consists of multiple parts (as in the example) they are treated as
41
if there were a logical \fBAND\fR between them.
43
If you want to make your own constructions (using \fBAND\fR, \fBOR\fR,
44
\fBNOT\fR etc., you have to put quotes around them so \fBmu\fR can consider
45
them as a unit; for example to find mails with oranges OR mandarins in the
46
subject-field, you can use:
49
$ mu find 'subject:orange OR subject:mandarin'
53
\fBmu\fR relies on the Xapian database for its searching capabilities, so it
54
offers all the search functionality that Xapian offers; for all the details,
56
\fIhttp://xapian.org/docs/queryparser.html\fR
58
One special feature of \fBmu\fR is that is does not distinguish between
59
uppercase and lowercase, nor the accented or unaccented versions of
60
characters. All match. In general, \fBmu\fR tries to be 'eager' in matching,
61
as filtering out unwanted results is usually preferrable over non matching
64
A wildcard search is a search where a \fB*\fR matches the last \fIn\R
65
character(s) in some string. The string must always start with one or more
66
characters before the wildcards. Since version 0.9.6, \fBmu\fR also supports
67
wildcard searches for all fields except maildirs and paths. So, to get all
68
mails with a subject containing a word starting with \fBcom\fR, you can use:
71
$ mu find 'subject:com*'
74
and get mails about computers, comments, compilation and so on. Note, when
75
running from the command-line it's import to put the query in quotes,
76
otherwise the shell would interpret the '*'. It is important to remember that
77
the '*' invokes the wildcard search only when used as the rightmost character
78
of a search term. Furthermore, it is \fBnot\fR a regular expression.
80
In older versions of mu, queries were logged in \fI<mu-home>/mu.log\fR;
81
however, since version 0.9, mu no longer does this.
83
The basic way to search a message is to type some words matching it, as you
84
would do in an internet search engine. For example,
87
$ mu find monkey banana
90
will find all messages that contain both 'monkey' and 'banana' in either body
91
or subject or one of the address-fields (to/from/cc).
93
As mentioned, matching is case-insensitive and accent-insensitive;
97
$ mu find Mönkey BÄNAÑå
100
yields the same results as the example above.
102
\fBmu\fR also recognizes prefixes for specific fields in a messages; for
106
$ mu find subject:penguin
109
to find messages with have the word \fBpenguin\fR in the subject field. You
110
can abbreviate \fBsubject:\fR to just \fBs:\fR. Here is the full table of the
111
search fields and their abbreviations:
114
cc,c Cc (carbon-copy) recipient(s)
115
bcc,h Bcc (blind-carbon-copy) recipient(s)
116
from,f Message sender
117
subject,s Message subject
118
to,t To: recipient(s)
121
prio,p Message priority ('low', 'normal' or 'high')
125
embed,e Search inside embedded text parts (messages, attachments)
126
file,j Attachment filename
127
mime,y MIME-type of one or more message parts
128
tag,x Tag for the message (contents of the \fIX-Label\fR field)
131
For clarity, this man-page uses the longer versions.
133
The meaning of most of these fields should be clear, but some require some
136
First, the message flags field describes certain properties of the message, as
137
listed in the following table:
140
d,draft Draft Message
142
n,new New message (in new/ Maildir)
143
p,passed Passed ('Handled')
146
t,thrashed Marked for deletion
147
a,attach Has attachment
148
z,signed Signed message
149
x,encrypted Encrypted message
152
Using this, we can search e.g. for all signed messages that have an
156
$ mu find flag:signed flag:attach
159
The message-priority has three possible values: low, normal or high. We can
160
match them using \fBprio:\fR - for example, to get all high-priority messages
161
with a subject containing some bird:
164
$ mu find prio:high subject:nightingale
167
The Maildir field describes the directory path starting \fBafter\fR the
168
Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part. So for
169
example, if there's a message with the file name
170
\fI~/Maildir/lists/running/cur/1234.213:2,\fR, you could find it (and all the
171
other messages in the same maildir) with:
174
$ mu find maildir:/lists/running
177
Note the starting '/'. If you want to match mails in the 'root' maildir, you
178
can do with a single '/':
184
(and of course you can use the \fBm:\fR shortcut instead of \fBmaildir:\fR)
186
The \fBdate:\fR (or \fBd:\fR) search parameter is 'special' in the fact that
187
it takes a range of dates. For now, these dates are in ISO 8601 format
188
(YYYYMMDDHHMM); you can leave out the right part, and mu will add the rest,
189
depending on whether this is the beginning or end of the date interval. For
190
example, for the beginning of the interval "201012" would be interpreted as
191
"20101201010000", or December 1, 2010 at 00:00, while for the end of the
192
interval, this would be interpreted as "20101231122359", or December 31, 2010
195
To get all messages between (inclusive) the 5th of May 2009 and the 2nd of
196
June 2010, you could use:
199
$ mu find date:20090505..20100602
202
Non-numeric characters are ignored, so the following is equivalent but more
206
$ mu find date:2009-05-05..2010-06-02
209
Precision is up to the minute and 24-hour notation for times is used, so
210
another example would be:
213
$ mu find date:2009-05-05/12:23..2010-06-02/17:18
216
An important point here is that the date matches are against local the local
217
time zone active the time when the mu database was filled (using \fBmu
220
\fBmu\fR also understand relative dates, in the form of a posiive number
221
followed by h (hour), d (day), w (week), m (30 days) or y (365 days). Some
222
examples will explain this:
225
5h five hours in the past
226
2w one week in the past
227
3m three times 30 days in the past
228
1y 365 days in the past
231
Using this notation, you can for example match messages between two and three
235
$ mu find date:3w..2w
238
There are some special keywords for dates, namely 'now', meaning the
239
prsent moment and 'today' for the beginning of today. So to get all messages
240
sent or received today, you could use:
243
$ mu find date:today..now
246
The \fBsize\fR or \fBz\fR allows you to match \fIsize ranges\fR -- that is,
247
match messages that have a byte-size within a certain range. Units (B (for
248
bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes) are supported). For
249
example, to get all messages between 10Kb and 2Mb (assuming SI units), you
253
$ mu find size:10K..2M
256
Finally, you can match \fIall\fR messages using "":
265
Note, some of the important options are described in the \fBmu(1)\fR man-page
266
and not here, as they apply to multiple mu-commands.
268
The \fBfind\fR-command has various options that influence the way \fBmu\fR
269
displays the results. If you don't specify anything, the defaults are
270
\fI\-\-fields="d f s"\fR, \fI\-\-sortfield=date\fR and \fI\-\-reverse\fR.
273
\fB\-f\fR, \fB\-\-fields\fR=\fI<fields>\fR
274
specifies a string that determines which fields are shown in the output. This
275
string consists of a number of characters (such as 's' for subject or 'f' for
276
from), which will replace with the actual field in the output. Fields that are
277
not known will be output as-is, allowing for some simple formatting.
282
$ mu find subject:snow --fields "d f s"
285
would list the date, subject and sender of all messages with 'snow' in the
288
The table of replacement characters is superset of the list mentions for
289
search parameters; the complete list:
292
t \fBt\fRo: recipient
293
c \fBc\fRc: (carbon-copy) recipient
294
h Bcc: (blind carbon-copy, \fBh\fRidden) recipient
295
d Sent \fBd\fRate of the message
296
f Message sender (\fBf\fRrom:)
297
g Message flags (fla\fBg\fRs)
298
l Full path to the message (\fBl\fRocation)
299
p Message \fBp\fRriority (high, normal, low)
300
s Message \fBs\fRubject
306
The message flags are the same ones we already saw in the message flags
307
above. Thus, a message which is 'seen', has an attachment and is signed would
308
have 'asz' as its corresponding output string, while an encrypted new message
312
\fB\-s\fR, \fB\-\-sortfield\fR \fR=\fI<field>\fR and \fB\-z\fR,
313
\fB\-\-reverse\fR specifies the field to sort the search results by, and the
314
direction (i.e., 'reverse' means that the sort should be reverted - Z-A). The
315
following fields are supported:
318
cc,c Cc (carbon-copy) recipient(s)
319
bcc,h Bcc (blind-carbon-copy) recipient(s)
320
date,d message sent date
321
from,f message sender
324
prio,p message priority
325
subject,s message subject
326
to,t To:-recipient(s)
329
Thus, for example, to sort messages by date, you could specify:
332
$ mu find fahrrad --fields "d f s" --sortfield=date --reverse
335
Note, if you specify a sortfield, by default, messages are sorted in reverse
336
(descending) order (e.g., from lowest to highest). This is usually a good
337
choice, but for dates it may be more useful to sort in the opposite direction.
341
output a summary based upon the first lines of the message.
344
\fB\-\-include\-unreadable\fR
345
normally, \fBmu find\fR does not include messages that are unreadable,
346
typically do not have corresponding disk file, i.e., messages that live only
347
in the databases. With this option even such messages are included. Note, for
348
\fB\-\-format=\fRlinks, unreadable message are ignore even when this option is
352
\fB\-\-format\fR=\fIplain|links|xquery|xml|sexp\fR
353
output results in the specified format.
355
The default is \fBplain\fR, i.e normal output with one line per message.
357
\fBlinks\fR outputs the results as a maildir with symbolic links to the found
358
messages. This enables easy integration with mail-clients (see below for more
359
information). See \fB\-\-linksdir\fR and \fB\-\-clearlinks\fR below.
361
\fBxml\fR formats the search results as XML.
363
\fBsexp\fR formats the search results as an s-expression as used in Lisp
364
programming environments.
366
\fBxquery\fR shows the Xapian query corresponding to your search terms. This
367
is meant for for debugging purposes.
370
\fB\-\-linksdir\fR \fR=\fI<dir>\fR and \fB\-c\fR, \fB\-\-clearlinks\fR
371
output the results as a maildir with symbolic links to the found
372
messages. This enables easy integration with mail-clients (see below for more
373
information). \fBmu\fR will create the maildir if it does not exist yet.
375
If you specify \fB\-\-clearlinks\fR, all existing symlinks will be cleared
376
from the target maildir; this allows for re-use of the same directory. An
377
alternative would be to delete the target directory before, but this has a big
378
chance of accidentaly removing something that should not be removed.
381
$ mu find grolsch --linksdir=~/Maildir/search --clearlinks
384
will store links to found messages in \fI~/Maildir/search\fR. If the directory
385
does not exist yet, it will be created.
387
Note: when \fBmu\fR creates a Maildir for these links, it automatically
388
inserts a \fI.noindex\fR file, to exclude the directory from \fBmu
392
\fB\-\-exec\fR=\fI<command>\fR
393
the \fB\-\-exec\fR command causes the \fIcommand\fR to be executed on each
394
matched message; for example, to see the raw text of all messages
395
matching 'milkshake', you could use:
397
$ mu find milkshake --exec='less'
399
which is roughly equivalent to:
401
$ mu find milkshake --fields="l" | xargs less
406
\fB\-b\fR, \fB\-\-bookmark\fR=\fI<bookmark>\fR
407
use a bookmarked search query. Using this option, a query from your bookmark
408
file will be prepended to other search queries. See mu-bookmarks(1) for the
409
details of the bookmarks file.
412
\fB\-t\fR, \fB\-\-threads\fR
413
show messages in 'threaded' format -- that is, with indentation and arrows
414
showing the conversation threads in the list of matching messages.
416
Messages in the threaded list are indented based on the depth in the
417
discussion, and are prefix with a kind of arrow with thread-related
418
information about the message, as in the following table:
421
| | normal | orphan | duplicate |
422
|-------------+--------+--------+-----------|
423
| first child | `-> | `*> | `=> |
424
| other | |-> | |*> | |=> |
427
Here, the an 'orphan' is a message without a parent message (in the list of
428
matches), and a duplicate is a message whose message-id was already seen
431
The algorithm used for determining the threads is based on Jamie Zawinksy's
433
.BR http://www.jwz.org/doc/threading.html
437
Here are some simple examples of \fBmu\fR search queries; you can make many
438
more complicated queries using various logical operators, parentheses and so
439
on, but in the author's experience, it's usually faster to find a message with
440
a simple query just searching for some words.
442
Find all messages with both 'bee' and 'bird' (in any field)
445
$ mu find 'bee AND bird'
448
or shorter, because \fBAND\fR is implied:
454
Find all messages with either Frodo or Sam:
457
$ mu find 'Frodo OR Sam'
460
Find all messages with the 'wombat' as subject, and 'capibara' anywhere:
463
$ mu find subject:wombat capibara
466
Find all messages in the 'Archive' folder from Fred:
469
$ mu find from:fred maildir:/Archive
472
Find all unread messages with attachments:
475
$ mu find flag:attach flag:unread
479
Find all messages with PDF-attachments:
482
$ mu find mime:application/pdf
485
Find all messages with attached images:
488
$ mu find 'mime:image/*'
491
Note[1]: the argument needs to be quoted, or the shell will interpret the '*'
492
Note[2]: the '*' wild card can only be used as the last (rightmost) part of a
496
.SS Integrating mu find with mail clients
502
For \fBmutt\fR you can use the following in your \fImuttrc\fR; pressing the F8
503
key will start a search, and F9 will take you to the results.
507
macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\
509
macro index <F9> "<change-folder-readonly>~/Maildir/search" \\
518
\fBSam B\fR suggested the following on the \fBmu\fR-mailing list. First add
519
the following to your Wanderlust configuraiton file:
522
(require 'elmo-search)
523
(elmo-search-register-engine
525
:prog "/usr/local/bin/mu" ;; or wherever you've installed it
526
:args '("find" pattern "--fields" "l") :charset 'utf-8)
528
(setq elmo-search-default-engine 'mu)
529
;; for when you type "g" in folder or summary.
530
(setq wl-default-spec "[")
533
Now, you can search using the \fBg\fR key binding; you can also create
534
permanent virtual folders when the messages matching some expression by adding
535
something like the following to your \fIfolders\fR file.
539
[date:today..now]!mu "Today"
541
[size:1m..100m]!mu "Big"
543
[flag:unread]!mu "Unread"
547
After restarting Wanderlust, the virtual folders should appear.
550
\fBWanderlust (old)\fR
552
Another way to intergrate \fBmu\fR and \fBwanderlust\fR is shown below; the
553
aforementioned method is recommended, but if that does not work for some
554
reason, the below can be an alternative.
557
(defvar mu-wl-mu-program "/usr/local/bin/mu")
558
(defvar mu-wl-search-folder "search")
560
(defun mu-wl-search ()
561
"search for messages with `mu', and jump to the results"
562
(let* ((muexpr (read-string "Find messages matching: "))
563
(sfldr (concat elmo-maildir-folder-path "/"
564
mu-wl-search-folder))
565
(cmdline (concat mu-wl-mu-program " find "
566
"--clearlinks --format=links --linksdir='" sfldr "' "
568
(rv (shell-command cmdline)))
570
((= rv 0) (message "Query succeeded"))
571
((= rv 2) (message "No matches found"))
572
(t (message "Error running query")))
575
(defun mu-wl-search-and-goto ()
576
"search and jump to the folder with the results"
579
(wl-summary-goto-folder-subr
580
(concat "." mu-wl-search-folder)
581
'force-update nil nil t)
582
(wl-summary-sort-by-date)))
584
;; querying both in summary and folder
585
(define-key wl-summary-mode-map (kbd "Q") ;; => query
586
'(lambda()(interactive)(mu-wl-search-and-goto)))
587
(define-key wl-folder-mode-map (kbd "Q") ;; => query
588
'(lambda()(interactive)(mu-wl-search-and-goto)))
595
\fBmu find\fR returns 0 upon successful completion; if it the a search was
596
performed, there needs to be a least one match. Anything else leads to a
597
non-zero return value, for example:
601
|------+--------------------------------|
603
| 1 | general error |
604
| 2 | no matches (for 'mu find') |
605
| 4 | database is corrupted |
611
\fBmu find\fR output is encoded according the locale for \fI--format=plain\fR
612
(the default), and UTF-8 for all other formats (\fIsexp\fR,
618
Please report bugs if you find them:
619
.BR http://code.google.com/p/mu0/issues/list
620
If you have specific messages which are not matched correctly, please attach
621
them (appropriately censored of course).
625
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
added
removed
.pc/fix-manpages/man/mu-find.1
