Provided by:
maildir-utils_0.4-2_i386 
NAME
mu-find - find messages based on search criteria
SYNOPSIS
mu-find [ options ] < search patterns >
DESCRIPTION
mu-find searches the databases of message information for messages
matching specific patterns. The database is created and kept up-to-date
with mu-index(1)
OPTIONS
(NB: see the CONFIGURATION section as well for using the configuration
file)
General options
--home=,-h <dir> set the mu home directory; default is ~/.mu This
directory is where the message database is stored, as well as
configuration files and logs.
--log-stderr, -s write logging information to standard error instead of
to <mu-home-directory>/mu-find.log , which is the default.
--log-append, -a append to the log file instead of overwriting it for
every run, which is the default.
--debug, -d add a lot of logging for debugging purposes
Output options
Output options determine how mu-find will display its results. Each of
the options can be selected by their full name ( text, sql, links or
aggregate ), or by a one-letter shortcut (t,s,l,a, respectively); in
other words, ’-o s’ would be a shorthand for ’--output=sql’, while ’-o
a’ gets you some aggregate data (statistics) about the matched
messages.
--output=text gives a textual display of the messages found; you can
use the --format option to influence the way this is done.
--output=links generates a maildir with symbolic links to the messages
founds. These can then be easily read with a maildir capable mail
client, such as mutt(1). NB: The MUTT-INTEGRATION section of this
manpage has some convenience macros for mutt integration.
By default, the maildir that is created is mu-found-<n> , where n is
the lowest two-digit hexademical number [00..ff] for which there does
not already exist a directory. Alternatively, you can use the
--linkdir=<dir> option to generate the maildir with a specific
name/path. The maildir should not exist yet.
--output=sql instead of searching for any messages, show the SQL query
corresponding with the search criteria (search criteria are discussed
later in this manpage). This can be useful for testing. For example,
$ mu-find --output=sql s:foo f:bar
would give us:
SELECT m.recipients, m.cc, m.sender, m.subject, m.msg_id,
NULL AS dummy2, m.flags, m.mdate, m.msize, m.mpath,
m.priority, m.tstamp, m.id
FROM message m
WHERE m.subject LIKE ’%foo%’
AND m.sender LIKE ’%bar%’
ORDER BY m.mdate DESC;
--output=aggregate show some aggregate information (statistics) about
the matching messages, such as the top-5 oldest, newest, biggest
messages in the set, and the most frequent sender, recipients. this is
only marginally useful, as most of the results give us just the
database IDs of the messages/contact found; however, these IDS’s can be
used to for further processing.
Also, included is the number of messages that match, and the average
size. Example output:
$ mu-find --output=aggregate test
query statistics
================
number of messages : 90
newest messages (msgids) : 1392 509 501 498 490
oldest messages (msgids) : 346 49 51 52 109
biggest messages (msgids) : 842 1120 1053 683 346
avg message size (bytes) : 199834
most popular senders (cids) : 548 456 56 644 181
most popular recipients (cids) : 463 554 2 667 668
Other options
--linkdir=, l <linkdir> set the maildir where mu-find should put the
symlinks to any matched messages. Note, this directory must not exist
yet.
--format=, -t <format> sets the way textual output is formatted. The
format is a string consisting of letters corresponding to message
fields. Any character not known is displayed as-is. For example,
--text-format="d,f|s" would display the date of message, a
’,’character, the sender (From:) of the message, a pipe-character and
finally the subject of the message:
1972-14-12 12:23,Someone|a star is born
2008-08-13 17:30,foo@bar.cx|get rich quick
...
The fields corresponding to certain letters are the same as the ones in
search expressions (scroll down for the list).
Note: database fields are not escaped with respect to format characters
such as ’,’, so be careful when using this generate comma-separated
files and the like. Also be careful to use alphabet letters are
separators, as future versions of mu-find might add more fields.
If you do not specify any format, the default of d,f,s is chosen, or,
show the ’date’, ’from’ and ’subject’ fields, separated by commas.
Non-printable characters are displayed as ’.’.
--sortfields, -S <sortfields>
and
--sortdir, -D a[scending]|d[escending]
set the way the found messages are sorted. The sortfields parameter
sets the fields to sort by, one letter per field (s=subject, d=date and
so on, see the section on search expressions to get the full list).
sortdir determines whether we sort ascending or descending.
Example (note: search expressions like ’s:hello’ are discussed in the
next section):
$ mu-find --sortfields=fz --sortdir=a s:hello
would sort messages ascending, with a subject containing ’hello’ by
sender, then by size.
The default is to sort descending by date. However,if any sortfield is
explicitly specified, the default sort order is ascending.
SEARCH EXPRESSIONS
Search expressions are short descriptions that describe the messages to
find. Search expresssions consist of a character that specifies some
property, followed by a ’:’ and some value to match. The following
fields are recognized:
s: subject
f: from (sender)
t: to (recipient)
c: cc: (carbon-copy recipient)
m: message id
p: message priority
P: path to the message
d: date
z: size
F: flags
And two special types:
x: xapian search
B: bookmarks
Option x: for ’xapian search’ searches the contents of messages, while
the other options search for a certain property (’metadata’) of the
message. Xapian searching is discussed after the other options.
Option B: refers to bookmarks. You can define ’bookmarks’ (shortcuts)
for search expression. Bookmarks are discussed later in this document.
Words
Now, let’s discuss search expressions where a certain message property
contains a word. We have following word or textual types:
s: subject
f: from (sender)
t: to (recipient)
c: Cc: (carbon-copy recipient)
m: message id
p: message priority
P: path to the message
For example, the search expression: s:rain matches all messages which
have ’rain’ in their subject (s:) (including training, brain, terrain
etc.)
f: matches all messages sent by (From:), as well as all messages by.
Search expressions can be combined - we can say f:bob â€â€™s:new yorkâ€â€™ to
get all message from Bob about New York (search expressions with spaces
need quotes).
Sometimes, we might want to match messages that donâ€â€™t contain as
certain word in some property. To get all mails that do not contain
’banana’ in their subject we can use the ^ prefix: s:^banana
And sometimes we might want to match a word exactly ie, we don’t want a
property to contain the search string, but we want it to be exactly
equal. For that we can use the ’=’: s:=hello to match exactly that
string (e.g., it won’t match ’Hello World’).
Please note that ’=’ and ’^’ only work for textual fields, and ’^’ only
for textual fields and flags.
Numbers and intervals
Certain properties of messages are better expressed as numbers or
intervals than as words, such as the message size or the message date:
d: date
z: size
Message size
First, let’s look at the message size (the on-disk file size of the
message). We could search for a message of size 500K with: z:500k (’k’
for kilobyte and ’M’ megabyte are supported). In many cases, an
interval
is probably more useful, so we can write: z:250k-750k to get messages
between 250k and 750k, and z:1M- or z:-2M to get messages that are
either bigger than 1M and messages that are smaller than 2M,
respectively.
Message date
Another useful interval type is the message date. Dates can be
specified in many different ways, and may have different meanings based
on your locale. The recommended format therefore is YYYYMMDD, although
other formats may work as well - provided the dates do not contain
’-’-characters.
To get all mails in January 2005, we can write: d:20050101-20050131 and
we can use the same interval notation as for the message size and write
d:20080801- to get all mails received since August 2008, and
d:-20033112 to get all mails from 2003 and before.
Single dates (such as d:20080202 ) are interpreted as an interval from
the beginning of that day until the end of the day.
mu-find also recognizes a number followed by ’d’, ’w’, ’f’, ’m’, ’y’ to
mean some number of resp. days, weeks, fortnights, months or years ago
since the present. Thus, d:3d- matches all messages from the last three
days, while d:2y-1m matches all messages that are between 2 years and
one month old.
Note that months are assumed to be 30 days, and years 365 days.
Message priority
The message priority is one of ’L’ (low), ’N’ (normal) or ’H’ (high).
To match all messages that are have either normal or high importance,
the expression would be: p:NH and match only messages of low
importance: p:L
Note, messages that do not explicitly specify their importance are
assumed to be of normal priority.
Flags
The last type of search expression are message flags. Message either
describe some property of the email file (file flags), or about the
contents (content flags).
You can search message by the following file flags: new (’N’), replied
(’R’), flagged (’F’), passed (’P’), seen (’S’), or combinations
thereof. For example, to get all new messages: F:N or the get all
flagged message you replied to: F:RF New (’N’) messages don’t have any
other flags, the other flags can be combined.
Then, there are content flags: has-attachment (’a’), signed (’s’) and
encrypted (’x’). For example, you could search for all signed messages
with an attachment with: F:as
You can also search for the absence of a flag, by prefixing the flag
with ’^’ character. So for example, to get all encrypted messages
without attachments, you can use: F:x^a
Xapian
mu uses the Xapian indexing library to search message contents. For the
end-user, the use of Xapian is mostly a technical detail, except for
the fact that Xapian searches follow the Xapian syntax:
http://xapian.org/docs/queryparser.html
The syntax is very similar to what WWW search engines offer. For
example, to get all the messages about either apples or bananas, the
search expression would be:
x:apples OR bananas (and note that on the command-line you would need
to quote that as: mu-find â€â€™x:apples OR bananasâ€â€™ )
That would get all messages with either apples or bananas in the
content -- that is, the message body, the subject field and the sender
and recipient fields. More complex queries are possible, say, x:apple
NEAR pear OR NOT (orange XOR coconut)
Xapian searches can be combined with other search options, so to get
all message from Alice (alice@example.com) regarding unicorns, use:
f:alice@example.com x:unicorns
NOTE: only up to 1000 documents are returned, and if you combine Xapian
search with other search options, the result will be a subset of that.
In other words, if you search query contains an ’x:’ option, the max
number of results is 1000.
BOOKMARKS
You can also define ’bookmarks’ for often-used search expressions. In a
file called bookmarks in your Mu home directory, you can specify them:
[important]
expr=p:H t:me@example.com f:boss@example.com
[recentdrink]
expr=d:1w- x:’wine OR beer OR whisky OR gin OR vodka’
You can then write search queries with the B: prefix, e.g. mu-find
-B:important d:1m-
You can combine bookmarks with other search expressions; however,
bookmarks cannot contain other bookmark expressions. This might change
in the future.
CONFIGURATION
Instead of specifying the options on the command line, you can also
specify them in the mu.conf configuration file, in the mu-home
directory (by default, ~/.mu ). The General options go in the section
[mu] while the mu-find specific options go under [mu-find]. For
example, your configuration file could look something like this:
[mu]
debug=false
[mu-info]
format=f,d
Note that command line arguments take precedence over the configuration
file.
MUTT INTEGRATION
mu-find can be integrated with the mutt(1) email client using some
macros:
macro index <F8> "<shell-escape>rm -rf ~/.mumatch; mu-find -o l -l ~/.mumatch " "mu-find"
macro index <F9> "<change-folder-readonly>~/.mumatch
" "display mu-find results"
Now, <F8> will perform a search, and <F9> will change to the folder
with the results.
BUGS
Please report bugs when you find them:
http://code.google.com/p/mu0/issues/list
AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
SEE ALSO
mu-index(1), sqlite3(1), mutt(1)