mirror of https://github.com/djcb/mu.git
555 lines
16 KiB
Groff
555 lines
16 KiB
Groff
.TH MU FIND 1 "May 2011" "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, JSON 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.
|
|
|
|
If you want to make your own constructions (using \fBAND\fR, \fBOR\fR,
|
|
\fBNOT\fR etc., you have to put quotes around them so \fBmu\fR can consider
|
|
them as a unit; for example to find mails with oranges OR mandarins in the
|
|
subject-field, you can use:
|
|
|
|
.nf
|
|
$ mu find 'subject:orange OR subject:mandarin'
|
|
.fi
|
|
|
|
|
|
\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\R
|
|
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 import to put the query in quotes,
|
|
otherwise the shell would interpret the '*'.
|
|
|
|
|
|
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
|
|
subject,s Message subject
|
|
to,t To: recipient(s)
|
|
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
|
|
attach,a Attachment filename
|
|
.fi
|
|
|
|
For clarity, this man-page uses the longer versions.
|
|
|
|
The meaning of most of these 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
|
|
u,unread Unread (shorthand for 'new or not 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
|
|
|
|
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
|
|
|
|
An important point here is that the date matches are against local the local
|
|
time zone active the time when the mu database was filled (using \fBmu
|
|
index\fR).
|
|
|
|
\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 will explain this:
|
|
|
|
.nf
|
|
5h five hours in the past
|
|
2w one week 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
|
|
|
|
Finally, 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
|
|
|
|
.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\-\-descending\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
|
|
r \fBr\fReferences (message ids In-reply-to, References as comma-separated list)
|
|
.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\-\-descending\fR
|
|
specifies the field to sort the search results by, and the direction. 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 --descending
|
|
.fi
|
|
|
|
Note, if you specify a sortfield, by default, messages are sorted in
|
|
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\-k\fR, \fB\-\-summary\-len\fR=\fI<len>\fR
|
|
output a summary based on up to \fI\len\fR lines of the message. The default
|
|
is \fB0\fR: no summary at all.
|
|
|
|
.TP
|
|
\fB\-\-format\fR=\fIplain|links|xquery|xml|json|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.
|
|
|
|
\fBjson\fR formats the search results as JSON (\fIJavascript Object
|
|
Notation\fR).
|
|
|
|
\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\-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.
|
|
|
|
.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:unread flag:attach
|
|
.fi
|
|
|
|
|
|
|
|
.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 it the a 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 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)
|