#+TITLE: MU FIND
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc

* 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 {{{man-link(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 {{{man-link(mu-query,7)}}}.

For example:

#+begin_example
$ mu find subject:snow and date:2009..
#+end_example

would find all messages in 2009 with `snow' in the subject field, e.g:

#+begin_example
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
#+end_example

This uses the default, *plain* output (implicitly, *--format=plain)*. For other
output formats (such as symlinks, XML, s-expressions or JSON), see the
discussion of *--format* in the *OPTIONS*-section below.

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 {{{man-link(mu-query,7)}}}.

* FIND OPTIONS

Note, some of the important options are described in the {{{man-link(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:

#+begin_example
$ mu find subject:snow --fields "d f s"
#+end_example

lists the date, subject and sender of all messages with `snow' in the their
subject.

The table of replacement characters is super-set of the list mentioned for
search parameters, such as:
#+begin_example
	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
#+end_example

For the complete list, try the command: *mu info fields*.

The message flags are described in {{{man-link(mu-query,7)}}}. As an example, a
message which is `seen', has an attachment and is signed has *asz* as its
corresponding output string, while an encrypted new message has *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:

#+begin_example
	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          Message priority
	subject,s       Message subject
	to,t            To:-recipient(s)
#+end_example

For the complete list, try the command: *mu info fields*.

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

#+begin_example
$ mu find fahrrad --fields "d f s" --sortfield=date --reverse
#+end_example

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|json|json2

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.
- *json* formats the output as JSON; it is a direct translation of the *sexp* format
- *json2* is a slightly more idiomatic JSON, for now the only difference with *json*
  is that the latter avoids the ':' prefix in key-names (e.g., "subject" instead
  of ":subject"). *json2* is still experimental.

** --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.

#+begin_example
$ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks
#+end_example

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
#+begin_example
  --after=`date +%s --date='5 min ago'`
#+end_example
This is assuming the GNU *date* command.

** --exec _command_
The *--exec* option causes _command_ to be executed on each matched message;
for example, to see the raw text of all messages matching `milkshake', you could
use:
#+begin_example
$ mu find milkshake --exec='less'
#+end_example
which is roughly equivalent to:
#+begin_example
$ mu find milkshake --fields="l" | xargs less
#+end_example

** -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
{{{man-link(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:
#+begin_example
|             | normal | orphan | duplicate |
|-------------+--------+--------+-----------|
| first child | `->    | `*>    | `=>       |
| other       | |->    | |*>    | |=>       |
#+end_example

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.

#+include: "muhome.inc" :minlevel 2

#+include: "common-options.inc" :minlevel 1

* 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.

#+begin_example
# 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"
#+end_example


** *Wanderlust*

*Sam B* suggested the following on the *mu*-mailing list. First add the following to
your Wanderlust configuration file:

#+begin_example
(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 "[")
#+end_example

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.

#+begin_example
VFolders {
  [date:today..now]!mu  "Today"
  [size:1m..100m]!mu    "Big"
  [flag:unread]!mu      "Unread"
}
#+end_example

After restarting Wanderlust, the virtual folders should appear.

* ENCODING

*mu find* output is encoded according to the locale wwhen using *--format=plain*
(the default format), and UTF-8 for all other formats (=sexp=, =xml=).

* PERFORMANCE

Some notes on performance, comparing the timings between some recent releases;
taking the total number for 10 test runs.

1. time (repeat 10 mu find "" -n 50000 > /dev/null)
2. time (repeat 10 mu find "" -n 50000 --include-related --threads > /dev/null)

#+ATTR_MAN: :disable-caption t
|       release | time 1 (sec) | time 2 (sec) |
|---------------+--------------+--------------|
|           1.4 | 8.9s         | 59.3s        |
|           1.6 | 8.3s         | 27.5s        |
|           1.8 | 8.7s         | 29.3s        |
|          1.10 | 9.8s         | 30.6s        |
| 1.11 (master) | 10.1s        | 29.5s        |

#+include: "exit-code.inc" :minlevel 1

#+include: "bugs.inc" :minlevel 1

#+include: "author.inc" :minlevel 1

#+include: "copyright.inc" :minlevel 1

* SEE ALSO

{{{man-link(mu,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-query,7)}}},
{{{man-link(mu-info,1)}}}
