322 lines
11 KiB
Org Mode
322 lines
11 KiB
Org Mode
#+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 Nessage 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)}}}
|