Provided by: maildir-utils_0.9.9.5-3_amd64 bug

NAME

       mu_find - find e-mail messages in the mu database.

SYNOPSIS

       mu find [options] <search expression>

DESCRIPTION

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

SEARCHING MAIL

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

          $ mu find subject:snow from:john

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

         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

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

       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.

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

       One special feature of mu is that is does not distinguish between uppercase and lowercase,
       nor  the accented or unaccented versions of characters. All match. In general, mu 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 * matches the last n character(s) in some string.
       The string must always start with one or  more  characters  before  the  wildcards.  Since
       version  0.9.6,  mu  also  supports  wildcard  searches for all fields except maildirs and
       paths. So, to get all mails with a subject containing a word starting with  com,  you  can
       use:

         $ mu find 'subject:com*'

       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  not
       a regular expression.

       In  older  versions of mu, queries were logged in <mu-home>/mu.log; 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,

         $ mu find monkey banana

       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

         $ mu find Mönkey BÄNAÑå

       yields the same results as the example above.

       mu also recognizes prefixes for specific fields in a messages; for example:

         $ mu find subject:penguin

       to find messages with have the word penguin in  the  subject  field.  You  can  abbreviate
       subject: to just s:. Here is the full table of the search fields and their abbreviations:

            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 (X-Label and/or X-Keywords)
            list,v          Mailing list (e.g. the List-Id value)

       There  are also the special fields contact, which matches all contact-fields (from, to, cc
       and bcc), and recip, which matches all recipient-fields (to, cc and bcc).

       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:

            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

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

         $ mu find flag:signed flag:attach

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

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

         $ mu find prio:high subject:nightingale

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

         $ mu find maildir:/lists/running

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

         $ mu find maildir:/

       (and of course you can use the m: shortcut instead of maildir:)

       The  date:  (or  d:)  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:

         $ mu find date:20090505..20100602

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

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

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

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

       mu 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:

            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

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

         $ mu find date:3w..2w

       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:

         $ mu find date:today..now

       The size or z allows you to match size ranges -- 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:

         $ mu find size:10K..2M

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

         $ mu find maildir:/Sent Items yoghurt
         $ mu find maildir:'/Sent Items' yoghurt

       The  first  query  searches  for messages in the /Sent maildir matching Items and yoghurt,
       while the second query searches the /Sent Items maildir searching  for  messages  matching
       yoghurt.

       You can match all messages using "" (or ''):

         $ mu find ""

OPTIONS

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

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

              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:

                   t    to: recipient
                   c    cc: (carbon-copy) recipient
                   h    Bcc: (blind carbon-copy, hidden) recipient
                   d    Sent date of the message
                   f    Message sender (from:)
                   g    Message flags (flags)
                   l    Full path to the message (location)
                   p    Message priority (high, normal, low)
                   s    Message subject
                   i    Message-id
                   m    maildir

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

       -s, --sortfield =<field> and -z,
              --reverse  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:

                   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)

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

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

              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.

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

       --include-unreadable
              normally,  mu  find does not include messages that are unreadable, typically do not
              have corresponding disk file, i.e., messages that live only in the databases.  With
              this  option  even such messages are included. Note, for --format=links, unreadable
              message are ignore even when this option is set.

       --format=plain|links|xquery|xml|sexp
              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).
              See --linksdir and --clearlinks below.

              xml formats the search results as XML.

              sexp formats the search results as an s-expression  as  used  in  Lisp  programming
              environments.

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

       --linksdir =<dir> and -c, --clearlinks
              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, 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.

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

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

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

       -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 mu-bookmarks(1) for the  details  of
              the bookmarks file.

       --skip-dups,-u 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
              offlineimap.

       --include-related,-r 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.

       -t, --threads 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:

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

              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: http://www.jwz.org/doc/threading.html

   Example queries
       Here  are  some  simple  examples of mu 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)

         $ mu find bee AND bird

       or shorter, because AND is implied:

         $ mu find bee bird

       Find all messages with either Frodo or Sam:

         $ mu find 'Frodo OR Sam'

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

         $ mu find subject:wombat capibara

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

         $ mu find from:fred maildir:/Archive

       Find all unread messages with attachments:

         $ mu find flag:attach flag:unread

       Find all messages with PDF-attachments:

         $ mu find mime:application/pdf

       Find all messages with attached images:

         $ mu find 'mime:image/*'

       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.

   Integrating mu find with 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.

              # 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"

       Wanderlust

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

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

              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.

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

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

                [flag:unread]!mu      "Unread"
              }

              After restarting Wanderlust, the virtual folders should appear.

              Wanderlust (old)

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

              (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)))

RETURN VALUE

       mu find 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:

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

ENCODING

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

BUGS

       Please report bugs if you find them: 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).

AUTHOR

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

SEE ALSO

       mu(1) mu-index(1)