MU FIND(1) General Commands Manual MU FIND(1)
NAME
mu-find - find e-mail messages in the mu database.
SYNOPSIS
mu [COMMON-OPTIONS] find [OPTIONS] SEARCH_EXPRESSION
DESCRIPTION
mu find is the mu command for searching e-mail message that were stored
earlier using mu index(1).
SEARCHING MAIL
mu find starts a search for messages in the database that match some
search pattern. The search patterns are described in detail in mu-
query(7).
For example:
$ mu find subject:snow and date:2009..
would find all messages in 2009 with `snow' in the subject field, e.g:
2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow
2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow
Note, this the default, plain-text output, which is the default, so you
don't have to use --format=plain. For other types of output (such as
symlinks, XML or s-expressions), see the discussion in the
OPTIONS-section below about --format.
The search pattern is taken as a command-line parameter. If the search
parameter consists of multiple parts (as in the example) they are
treated as if there were a logical and between them.
For details on the possible queries, see mu-query(7).
FIND OPTIONS
Note, some of the important options are described in the mu(1) manual
page and not here, as they apply to multiple mu commands.
The find-command has various options that influence the way mu displays
the results. If you don't specify anything, the defaults are
--fields="d f s", --sortfield=date and --reverse.
-f, --fields fields
Specifies a string that determines which fields are shown in the
output. This string consists of a number of characters (such as 's' for
subject or 'f' for from), which will replace with the actual field in
the output. Fields that are not known will be output as-is, allowing
for some simple formatting.
For example:
$ mu find subject:snow --fields "d f s"
lists the date, subject and sender of all messages with `snow' in the
their subject.
The table of replacement characters is superset of the list mentions
for search parameters, such as:
t *t*o: recipient
d Sent *d*ate of the message
f Message sender (*f*rom:)
g Message flags (fla*g*s)
l Full path to the message (*l*ocation)
s Message *s*ubject
i Message-*i*d
m *m*aildir
For the complete list, try the command: mu info fields.
The message flags are described in mu-query(7). As an example, a
message which is `seen', has an attachment and is signed would have
`asz' as its corresponding output string, while an encrypted new
message would have `nx'.
-s, --sortfield field and -z,--reverse
Specify the field to sort the search results by and the direction
(i.e., `reverse' means that the sort should be reverted - Z-A).
Examples include:
cc,c Cc (carbon-copy) recipient(s)
date,d Message sent date
from,f Message sender
maildir,m Maildir
msgid,i Message id
prio,p Nessage priority
subject,s Message subject
to,t To:-recipient(s)
For the complete list, try the command: mu info fields.
Thus, for example, to sort messages by date, you could specify:
$ mu find fahrrad --fields "d f s" --sortfield=date --reverse
Note, if you specify a sortfield, by default, messages are sorted in
reverse (descending) order (e.g., from lowest to highest). This is
usually a good choice, but for dates it may be more useful to sort in
the opposite direction.
-n, --maxnum number
If number > 0, display maximally that number of entries. If not
specified, all matching entries are displayed.
--summary-len number
If number > 0, use that number of lines of the message to provide a
summary.
--format plain|links|xml|sexp
Output results in the specified format.
— The default is plain, i.e normal output with one line per message.
— links outputs the results as a maildir with symbolic links to the
found messages. This enables easy integration with mail-clients
(see below for more information). This requires --linksdir.
— xml formats the search results as XML.
— sexp formats the search results as an s-expression as used in Lisp
programming environments.
--linksdir dir and -c, --clearlinks
When using --format=links, output the results as a maildir with
symbolic links to the found messages. This enables easy integration
with mail-clients (see below for more information). mu will create the
maildir if it does not exist yet.
If you specify --clearlinks, existing symlinks will be cleared from the
target directories; this allows for re-use of the same maildir.
However, this option will delete any symlink it finds, so be careful.
$ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks
stores links to found messages in ~/Maildir/search. If the directory
does not exist yet, it will be created. Note: when mu creates a Maildir
for these links, it automatically inserts a .noindex file, to exclude
the directory from mu index.
--after timestamp
Only show messages whose message files were last modified (mtime) after
timestamp. timestamp is a UNIX time_t value, the number of seconds
since 1970-01-01 (in UTC).
From the command line, you can use the date command to get this value.
For example, only consider messages modified (or created) in the last 5
minutes, you could specify
--after=`date +%s --date='5 min ago'`
This is assuming the GNU date command.
--exec command
The --exec coption causes command to be executed on each matched
message; for example, to see the raw text of all messages matching
`milkshake', you could use:
$ mu find milkshake --exec='less'
which is roughly equivalent to:
$ mu find milkshake --fields="l" | xargs less
-b, --bookmark bookmark
Use a bookmarked search query. Using this option, a query from your
bookmark file will be prepended to other search queries. See mu-
bookmarks(5) for the details of the bookmarks file.
-u, --skip-dups
Whenever there are multiple messages with the same message-id field,
only show the first one. This is useful if you have copies of the same
message, which is a common occurrence when using e.g. Gmail together
with offlineimap.
-r, --include-related
Include messages being referred to by the matched messages -- i.e..
include messages that are part of the same message thread as some
matched messages. This is useful if you want Gmail-style
`conversations'.
-t, --threads
Show messages in a `threaded' format -- that is, with indentation and
arrows showing the conversation threads in the list of matching
messages. When using this, sorting is chronological (by date), based on
the newest message in a thread.
Messages in the threaded list are indented based on the depth in the
discussion, and are prefix with a kind of arrow with thread-related
information about the message, as in the following table:
| | normal | orphan | duplicate |
|-------------+--------+--------+-----------|
| first child | `-> | `*> | `=> |
| other | |-> | |*> | |=> |
Here, an `orphan' is a message without a parent message (in the list of
matches), and a duplicate is a message whose message-id was already
seen before; not this may not really be the same message, if the
message-id was copied.
The algorithm used for determining the threads is based on Jamie
Zawinksi's description: http://www.jwz.org/doc/threading.html
-a,--analyze
Instead of executing the query, analyze it by show the parse-tree s-
expression and a stringified version of the Xapian query. This can help
users to determine how mu interprets some query.
The output of this command are differ between versions, but should be
helpful nevertheless.
--muhome
Use a non-default directory to store and read the database, write the
logs, etc. By default, mu uses the XDG Base Directory Specification
(e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu).
Earlier versions of mu defaulted to ~/.mu, which now requires
--muhome=~/.mu.
The environment variable MUHOME can be used as an alternative to
--muhome. The latter has precedence.
COMMON OPTIONS
-d, --debug
Makes mu generate extra debug information, useful for debugging the
program itself. Debug information goes to the standard logging
location; see mu(1).
-q, --quiet
Causes mu not to output informational messages and progress information
to standard output, but only to the log file. Error messages will still
be sent to standard error. Note that mu index is much faster with
--quiet, so it is recommended you use this option when using mu from
scripts etc.
--log-stderr
Causes mu to not output log messages to standard error, in addition to
sending them to the standard logging location.
--nocolor
Do not use ANSI colors. The environment variable NO_COLOR can be used
as an alternative to --nocolor.
-V, --version
Prints mu version and copyright information.
-h, --help
Lists the various command line options.
INTEGRATION
It is possible to integrate mu find with some mail clients
mutt
For mutt you can use the following in your muttrc; pressing the F8 key
will start a search, and F9 will take you to the results.
# mutt macros for mu
macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\
"mu find"
macro index <F9> "<change-folder-readonly>~/Maildir/search" \\
"mu find results"
Wanderlust
Sam B suggested the following on the mu-mailing list. First add the
following to your Wanderlust configuration file:
(require 'elmo-search)
(elmo-search-register-engine
'mu 'local-file
:prog "/usr/local/bin/mu" ;; or wherever you've installed it
:args '("find" pattern "--fields" "l") :charset 'utf-8)
(setq elmo-search-default-engine 'mu)
;; for when you type "g" in folder or summary.
(setq wl-default-spec "[")
Now, you can search using the g key binding; you can also create
permanent virtual folders when the messages matching some expression by
adding something like the following to your folders file.
VFolders {
[date:today..now]!mu "Today"
[size:1m..100m]!mu "Big"
[flag:unread]!mu "Unread"
}
After restarting Wanderlust, the virtual folders should appear.
