mu/man/mu-find.1

.TH MU FIND 1 "December 2012" "User Manuals"

.SH NAME

mu find \- find e-mail messages in the \fBmu\fR database.

.SH SYNOPSIS

.B mu find [options] <search expression>

.SH DESCRIPTION

\fBmu find\fR is the \fBmu\fR command for searching e-mail message that
were stored earlier using
\fBmu index(1)\fR.

.SH SEARCHING MAIL

\fBmu find\fR starts a search for messages in the database that match some
search pattern. For example:

.nf
   $ mu find subject:snow from:john
.fi

would find all messages from John with 'snow' in the subject field, something
like:

.nf
  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
.fi

Note, this the default, plain-text output, which is the default, so you don't
have to use \fB--format=plain\fR. For other types of output (such as symlinks,
XML or s-expressions), see the discussion in the \fBOPTIONS\fR-section
below about \fB--format\fR.

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 \fBAND\fR between them.

\fBmu\fR relies on the Xapian database for its searching capabilities, so it
offers all the search functionality that Xapian offers; for all the details,
see:
     \fIhttp://xapian.org/docs/queryparser.html\fR

One special feature of \fBmu\fR is that is does not distinguish between
uppercase and lowercase, nor the accented or unaccented versions of
characters. All match. In general, \fBmu\fR tries to be 'eager' in matching,
as filtering out unwanted results is usually preferrable over non matching
messages.

A wildcard search is a search where a \fB*\fR matches the last \fIn\fR
character(s) in some string. The string must always start with one or more
characters before the wildcards. Since version 0.9.6, \fBmu\fR also supports
wildcard searches for all fields except maildirs and paths. So, to get all
mails with a subject containing a word starting with \fBcom\fR, you can use:

.nf
  $ mu find 'subject:com*'
.fi

and get mails about computers, comments, compilation and so on. Note, when
running from the command-line it's important to put the query in quotes,
otherwise the shell would interpret the '*'. It is equally important to
remember that the '*' invokes the wildcard search only when used as the
rightmost character of a search term. Furthermore, it is \fBnot\fR a regular
expression.

In older versions of mu, queries were logged in \fI<mu-home>/mu.log\fR;
however, since version 0.9, mu no longer does this.

The basic way to search a message is to type some words matching it, as you
would do in an internet search engine. For example,

.nf
  $ mu find monkey banana
.fi

will find all messages that contain both 'monkey' and 'banana' in either body
or subject or one of the address-fields (to/from/cc).

As mentioned, matching is case-insensitive and accent-insensitive; thus

.nf
  $ mu find Mönkey BÄNAÑå
.fi

yields the same results as the example above.


\fBmu\fR also recognizes prefixes for specific fields in a messages; for
example:

.nf
  $ mu find subject:penguin
.fi

to find messages with have the word \fBpenguin\fR in the subject field. You
can abbreviate \fBsubject:\fR to just \fBs:\fR. Here is the full table of the
search fields and their abbreviations:

.nf
	cc,c            Cc (carbon-copy) recipient(s)
	bcc,h           Bcc (blind-carbon-copy) recipient(s)
	from,f          Message sender
	to,t            To: recipient(s)
	subject,s       Message subject
	maildir,m       Maildir
	msgid,i         Message-ID
	prio,p          Message priority ('low', 'normal' or 'high')
	flag,g          Message Flags
	date,d          Date-Range
	size,z          Message size
	embed,e         Search inside embedded text parts (messages, attachments)
	file,j          Attachment filename
	mime,y          MIME-type of one or more message parts
	tag,x           Tags for the message (\fIX-Label\fR and/or \fIX-Keywords\fR)
	list,v          Mailing list (e.g. the List-Id value)
.fi

There are also the special fields \fBcontact\fR, which matches all
contact-fields (\fBfrom\fR, \fBto\fR, \fBcc\fR and \fBbcc\fR), and
\fBrecip\fR, which matches all recipient-fields (\fBto\fR, \fBcc\fR and
\fBbcc\fR).

The meaning of most of the above fields should be clear, but some require some
extra discusion. First, the message flags field describes certain properties
of the message, as listed in the following table:

.nf
	d,draft         Draft Message
	f,flagged       Flagged
	n,new           New message (in new/ Maildir)
	p,passed        Passed ('Handled')
	r,replied       Replied
	s,seen          Seen
	t,thrashed      Marked for deletion
	a,attach        Has attachment
	z,signed        Signed message
	x,encrypted     Encrypted message
.fi

Using this, we can search e.g. for all signed messages that have an
attachment:

.nf
  $ mu find flag:signed flag:attach
.fi

Encrypted messages may be signed as well, but this is only visible after
decrypting, and thus, is invisible to \fBmu\fR.

The message-priority has three possible values: low, normal or high. We can
match them using \fBprio:\fR - for example, to get all high-priority messages
with a subject containing some bird:

.nf
  $ mu find prio:high subject:nightingale
.fi

The Maildir field describes the directory path starting \fBafter\fR the
Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part. So for
example, if there's a message with the file name
\fI~/Maildir/lists/running/cur/1234.213:2,\fR, you could find it (and all the
other messages in the same maildir) with:

.nf
  $ mu find maildir:/lists/running
.fi

Note the starting '/'. If you want to match mails in the 'root' maildir, you
can do with a single '/':

.nf
  $ mu find maildir:/
.fi

(and of course you can use the \fBm:\fR shortcut instead of \fBmaildir:\fR)

The \fBdate:\fR (or \fBd:\fR) search parameter is 'special' in the fact that
it takes a range of dates. For now, these dates are in ISO 8601 format
(YYYYMMDDHHMM); you can leave out the right part, and mu will add the rest,
depending on whether this is the beginning or end of the date interval. For
example, for the beginning of the interval "201012" would be interpreted as
"20101201010000", or December 1, 2010 at 00:00, while for the end of the
interval, this would be interpreted as "20101231122359", or December 31, 2010
at 23:59.

To get all messages between (inclusive) the 5th of May 2009 and the 2nd of
June 2010, you could use:

.nf
  $ mu find date:20090505..20100602
.fi

Non-numeric characters are ignored, so the following is equivalent but more
readable:

.nf
  $ mu find date:2009-05-05..2010-06-02
.fi

Precision is up to the minute and 24-hour notation for times is used, so
another example would be:

.nf
  $ mu find date:2009-05-05/12:23..2010-06-02/17:18
.fi

\fBmu\fR also understand relative dates, in the form of a posiive number
followed by h (hour), d (day), w (week), m (30 days) or y (365 days). Some
examples to explain this:

.nf
	5h      five hours in the past
	2w      two weeks in the past
	3m      three times 30 days in the past
	1y      365 days in the past
.fi

Using this notation, you can for example match messages between two and three
weeks old:

.nf
  $ mu find date:3w..2w
.fi

There are some special keywords for dates, namely 'now', meaning the
prsent moment and 'today' for the beginning of today. So to get all messages
sent or received today, you could use:

.nf
  $ mu find date:today..now
.fi

The \fBsize\fR or \fBz\fR allows you to match \fIsize ranges\fR -- that is,
match messages that have a byte-size within a certain range. Units (B (for
bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes) are supported). For
example, to get all messages between 10Kb and 2Mb (assuming SI units), you
could use:

.nf
  $ mu find size:10K..2M
.fi


It's important to remember that if a search term includes spaces, you should
\fIquote\fr those parts. Thus, when we look at the following examples:

.nf
  $ mu find maildir:/Sent Items yoghurt
  $ mu find maildir:'/Sent Items' yoghurt
.fi

The first query searches for messages in the \fI/Sent\fR maildir matching
\fIItems\fR and \fIyoghurt\fR, while the second query searches the \fI/Sent
Items\fR maildir searching for messages matching \fIyoghurt\fR.


You can match \fIall\fR messages using "" (or ''):

.nf
  $ mu find ""
.fi


.SH OPTIONS

Note, some of the important options are described in the \fBmu(1)\fR man-page
and not here, as they apply to multiple mu-commands.

The \fBfind\fR-command has various options that influence the way \fBmu\fR
displays the results. If you don't specify anything, the defaults are
\fI\-\-fields="d f s"\fR, \fI\-\-sortfield=date\fR and \fI\-\-reverse\fR.

.TP
\fB\-f\fR, \fB\-\-fields\fR=\fI<fields>\fR
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:

.nf
  $ mu find subject:snow --fields "d f s"
.fi

would list 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; the complete list:

.nf
	t	\fBt\fRo: recipient
	c	\fBc\fRc: (carbon-copy) recipient
	h	Bcc: (blind carbon-copy, \fBh\fRidden) recipient
	d	Sent \fBd\fRate of the message
	f	Message sender (\fBf\fRrom:)
	g	Message flags (fla\fBg\fRs)
	l	Full path to the message (\fBl\fRocation)
	p	Message \fBp\fRriority (high, normal, low)
	s	Message \fBs\fRubject
	i	Message-\fBi\fRd
	m	\fBm\fRaildir
.fi


The message flags are the same ones we already saw in the message flags
above. Thus, 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'.

.TP
\fB\-s\fR, \fB\-\-sortfield\fR \fR=\fI<field>\fR and \fB\-z\fR,
\fB\-\-reverse\fR specifies the field to sort the search results by, and the
direction (i.e., 'reverse' means that the sort should be reverted - Z-A). The
following fields are supported:

.nf
	cc,c            Cc (carbon-copy) recipient(s)
	bcc,h           Bcc (blind-carbon-copy) recipient(s)
	date,d          message sent date
	from,f          message sender
	maildir,m       maildir
	msgid,i         message id
	prio,p          message priority
	subject,s       message subject
	to,t            To:-recipient(s)
.fi

Thus, for example, to sort messages by date, you could specify:

.nf
  $ mu find fahrrad --fields "d f s" --sortfield=date --reverse
.fi

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.

.TP
\fB\-\-summary-len=<number>\fR
If > 0, use that number of lines of the message to provide a summary.

.TP
\fB\-\-include\-unreadable\fR normally, \fBmu find\fR does not include
messages for which the corresponding file is unreadable. With this option even
such messages are included. Note, for \fB\-\-format=\fRlinks, unreadable
message are ignored even when this option is set.

.TP
\fB\-\-format\fR=\fIplain|links|xquery|xml|sexp\fR
output results in the specified format.

The default is \fBplain\fR, i.e normal output with one line per message.

\fBlinks\fR 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). See \fB\-\-linksdir\fR and \fB\-\-clearlinks\fR below.

\fBxml\fR formats the search results as XML.

\fBsexp\fR formats the search results as an s-expression as used in Lisp
programming environments.

\fBxquery\fR shows the Xapian query corresponding to your search terms. This
is meant for for debugging purposes.

.TP
\fB\-\-linksdir\fR \fR=\fI<dir>\fR and \fB\-c\fR, \fB\-\-clearlinks\fR
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). \fBmu\fR will create the maildir if it does not exist yet.

If you specify \fB\-\-clearlinks\fR, all existing symlinks will be cleared
from the target maildir; this allows for re-use of the same directory. An
alternative would be to delete the target directory before, but this has a big
chance of accidentaly removing something that should not be removed.

.nf
  $ mu find grolsch --linksdir=~/Maildir/search --clearlinks
.fi

will store links to found messages in \fI~/Maildir/search\fR. If the directory
does not exist yet, it will be created.

Note: when \fBmu\fR creates a Maildir for these links, it automatically
inserts a \fI.noindex\fR file, to exclude the directory from \fBmu
index\fR.

.TP
\fB\-\-after=\fR\fI<timestamp>\fR only show messages whose message files were
last modified (\fBmtime\fR) after \fI<timestamp>\fR. \fI<timestamp>\fR is a
UNIX \fBtime_t\fR value, the number of seconds since 1970-01-01 (in UTC).

From the command line, you can use the \fBdate\fR command to get this
value. For example, only consider messages modified (or created) in the last 5
minutes, you could specify
.nf
  --after=`date +%s --date='5 min ago'`
.fi
This is assuming the GNU \fBdate\fR command.


.TP
\fB\-\-exec\fR=\fI<command>\fR
the \fB\-\-exec\fR command causes the \fIcommand\fR to be executed on each
matched message; for example, to see the raw text of all messages
matching 'milkshake', you could use:
.nf
  $ mu find milkshake --exec='less'
.fi
which is roughly equivalent to:
.nf
  $ mu find milkshake --fields="l" | xargs less
.fi


.TP
\fB\-b\fR, \fB\-\-bookmark\fR=\fI<bookmark>\fR
use a bookmarked search query. Using this option, a query from your bookmark
file will be prepended to other search queries. See mu-bookmarks(1) for the
details of the bookmarks file.


.TP
\fB\-\-skip\-dups\fR,\fB-u\fR whenever there are multiple messages with the
same name, only show the first one. This is useful if you have copies of the
same message, which is a common occurence when using e.g. Gmail together with
\fBofflineimap\fR.

.TP
\fB\-\-include\-related\fR,\fB-r\fR also include messages being refered 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'. Note, finding these related messages make
searches slower.

.TP
\fB\-t\fR, \fB\-\-threads\fR show messages in a 'threaded' format -- that is,
with indentation and arrows showing the conversation threads in the list of
matching messages.

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:

.nf
|             | normal | orphan | duplicate |
|-------------+--------+--------+-----------|
| first child | `->    | `*>    | `=>       |
| other       | |->    | |*>    | |=>       |
.fi

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 Zawinksy's
description:
.BR http://www.jwz.org/doc/threading.html

.SS Example queries

Here are some simple examples of \fBmu\fR search queries; you can make many
more complicated queries using various logical operators, parentheses and so
on, but in the author's experience, it's usually faster to find a message with
a simple query just searching for some words.

Find all messages with both 'bee' and 'bird' (in any field)

.nf
  $ mu find bee AND bird
.fi

or shorter, because \fBAND\fR is implied:

.nf
  $ mu find bee bird
.fi

Find all messages with either Frodo or Sam:

.nf
  $ mu find 'Frodo OR Sam'
.fi

Find all messages with the 'wombat' as subject, and 'capibara' anywhere:

.nf
  $ mu find subject:wombat capibara
.fi

Find all messages in the 'Archive' folder from Fred:

.nf
  $ mu find from:fred maildir:/Archive
.fi

Find all unread messages with attachments:

.nf
  $ mu find flag:attach flag:unread
.fi


Find all messages with PDF-attachments:

.nf
  $ mu find mime:application/pdf
.fi

Find all messages with attached images:

.nf
  $ mu find 'mime:image/*'
.fi

Note[1]: the argument needs to be quoted, or the shell will interpret the '*'
Note[2]: the '*' wild card can only be used as the last (rightmost) part of a
search term.
Note[3]: non-word characters (such as € or ☺) are ignore in queries; you
cannot search for them.


.SS Integrating mu find with mail clients

.TP

\fBmutt\fR

For \fBmutt\fR you can use the following in your \fImuttrc\fR; pressing the F8
key will start a search, and F9 will take you to the results.

.nf
# 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"
.fi


.TP

\fBWanderlust\fR

\fBSam B\fR suggested the following on the \fBmu\fR-mailing list. First add
the following to your Wanderlust configuraiton file:

.nf
(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 "[")
.fi

Now, you can search using the \fBg\fR key binding; you can also create
permanent virtual folders when the messages matching some expression by adding
something like the following to your \fIfolders\fR file.

.nf
VFolders {
  [date:today..now]!mu  "Today"

  [size:1m..100m]!mu    "Big"

  [flag:unread]!mu      "Unread"
}
.fi

After restarting Wanderlust, the virtual folders should appear.


\fBWanderlust (old)\fR

Another way to intergrate \fBmu\fR and \fBwanderlust\fR is shown below; the
aforementioned method is recommended, but if that does not work for some
reason, the below can be an alternative.

.nf
(defvar mu-wl-mu-program     "/usr/local/bin/mu")
(defvar mu-wl-search-folder  "search")

(defun mu-wl-search ()
  "search for messages with `mu', and jump to the results"
   (let* ((muexpr (read-string "Find messages matching: "))
	  (sfldr  (concat elmo-maildir-folder-path "/"
		    mu-wl-search-folder))
	  (cmdline (concat mu-wl-mu-program " find "
		      "--clearlinks --format=links --linksdir='" sfldr "' "
		     muexpr))
	  (rv (shell-command cmdline)))
    (cond
      ((= rv 0)  (message "Query succeeded"))
      ((= rv 2)  (message "No matches found"))
      (t (message "Error running query")))
  (= rv 0)))

(defun mu-wl-search-and-goto ()
  "search and jump to the folder with the results"
  (interactive)
  (when (mu-wl-search)
    (wl-summary-goto-folder-subr
      (concat "." mu-wl-search-folder)
      'force-update nil nil t)
    (wl-summary-sort-by-date)))

;; querying both in summary and folder
(define-key wl-summary-mode-map (kbd "Q") ;; => query
  '(lambda()(interactive)(mu-wl-search-and-goto)))
(define-key wl-folder-mode-map (kbd "Q") ;; => query
  '(lambda()(interactive)(mu-wl-search-and-goto)))

.fi


.SH RETURN VALUE

\fBmu find\fR returns 0 upon successful completion; if the search was
performed, there needs to be a least one match. Anything else leads to a
non-zero return value, for example:

.nf
| code | meaning                        |
|------+--------------------------------|
|    0 | ok                             |
|    1 | general error                  |
|    2 | no matches (for 'mu find')     |
|    4 | database is corrupted          |
.fi


.SH ENCODING

\fBmu find\fR output is encoded according the locale for \fI--format=plain\fR
(the default), and UTF-8 for all other formats (\fIsexp\fR,
\fIxml\fR).


.SH BUGS

Please report bugs if you find them:
.BR http://code.google.com/p/mu0/issues/list
If you have specific messages which are not matched correctly, please attach
them (appropriately censored of course).

.SH AUTHOR

Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

.SH "SEE ALSO"

.BR mu(1)
.BR mu-index(1)