.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] .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 running in the snow 2009-03-05 18:38:24 EET Marius 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.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\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\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\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\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\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 "mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\ "mu find" macro index "~/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 .SH "SEE ALSO" .BR mu(1) .BR mu-index(1)