Provided by: maildir-utils_0.4-2_i386 bug

NAME

       mu-find - find messages based on search criteria

SYNOPSIS

       mu-find [ options ] < search patterns >

DESCRIPTION

       mu-find  searches  the  databases  of  message information for messages
       matching specific patterns. The database is created and kept up-to-date
       with mu-index(1)

OPTIONS

       (NB:  see the CONFIGURATION section as well for using the configuration
       file)

   General options
       --home=,-h <dir> set the mu  home  directory;  default  is  ~/.mu  This
       directory  is  where  the  message  database  is  stored,  as  well  as
       configuration files and logs.

       --log-stderr, -s write logging information to standard error instead of
       to <mu-home-directory>/mu-find.log , which is the default.

       --log-append,  -a  append to the log file instead of overwriting it for
       every run, which is the default.

       --debug, -d add a lot of logging for debugging purposes

   Output options
       Output options determine how mu-find will display its results. Each  of
       the  options  can  be selected by their full name ( text, sql, links or
       aggregate ), or by a one-letter shortcut  (t,s,l,a,  respectively);  in
       other  words, ’-o s’ would be a shorthand for ’--output=sql’, while ’-o
       a’  gets  you  some  aggregate  data  (statistics)  about  the  matched
       messages.

       --output=text  gives  a  textual display of the messages found; you can
       use the --format option to influence the way this is done.

       --output=links generates a maildir with symbolic links to the  messages
       founds.  These  can  then  be  easily  read with a maildir capable mail
       client, such as mutt(1).  NB:  The  MUTT-INTEGRATION  section  of  this
       manpage has some convenience macros for mutt integration.

       By  default,  the  maildir that is created is mu-found-<n> , where n is
       the lowest two-digit hexademical number [00..ff] for which  there  does
       not   already  exist  a  directory.  Alternatively,  you  can  use  the
       --linkdir=<dir>  option  to  generate  the  maildir  with  a   specific
       name/path. The maildir should not exist yet.

       --output=sql  instead of searching for any messages, show the SQL query
       corresponding with the search criteria (search criteria  are  discussed
       later in this manpage). This can be useful for testing. For example,
       $ mu-find --output=sql s:foo f:bar
       would give us:

       SELECT   m.recipients, m.cc, m.sender, m.subject, m.msg_id,
                NULL AS dummy2, m.flags, m.mdate, m.msize, m.mpath,
                m.priority, m.tstamp, m.id
       FROM     message m
       WHERE    m.subject LIKE ’%foo%’
       AND      m.sender LIKE ’%bar%’
       ORDER BY m.mdate DESC;

       --output=aggregate  show  some aggregate information (statistics) about
       the matching messages,  such  as  the  top-5  oldest,  newest,  biggest
       messages  in the set, and the most frequent sender, recipients. this is
       only marginally useful, as  most  of  the  results  give  us  just  the
       database IDs of the messages/contact found; however, these IDS’s can be
       used to for further processing.

       Also, included is the number of messages that match,  and  the  average
       size. Example output:

       $ mu-find --output=aggregate test
       query statistics
       ================
       number of messages              : 90
       newest messages (msgids)        : 1392 509 501 498 490
       oldest messages (msgids)        : 346 49 51 52 109
       biggest messages (msgids)       : 842 1120 1053 683 346
       avg message size (bytes)        : 199834
       most popular senders (cids)     : 548 456 56 644 181
       most popular recipients (cids)  : 463 554 2 667 668

   Other options
       --linkdir=,  l  <linkdir>  set the maildir where mu-find should put the
       symlinks to any matched messages. Note, this directory must  not  exist
       yet.

       --format=,  -t  <format>  sets the way textual output is formatted. The
       format is a string  consisting  of  letters  corresponding  to  message
       fields.  Any  character  not  known  is  displayed  as-is. For example,
       --text-format="d,f|s"  would   display   the   date   of   message,   a
       ’,’character,  the  sender (From:) of the message, a pipe-character and
       finally the subject of the message:
            1972-14-12 12:23,Someone|a star is born
            2008-08-13 17:30,foo@bar.cx|get rich quick
            ...
       The fields corresponding to certain letters are the same as the ones in
       search expressions (scroll down for the list).

       Note: database fields are not escaped with respect to format characters
       such as ’,’, so be careful when  using  this  generate  comma-separated
       files  and  the  like.  Also  be  careful  to  use alphabet letters are
       separators, as future versions of mu-find might add more fields.

       If you do not specify any format, the default of d,f,s is  chosen,  or,
       show the ’date’, ’from’ and ’subject’ fields, separated by commas.

       Non-printable characters are displayed as ’.’.

       --sortfields, -S <sortfields>

       and

       --sortdir, -D a[scending]|d[escending]

       set  the  way  the  found messages are sorted. The sortfields parameter
       sets the fields to sort by, one letter per field (s=subject, d=date and
       so on, see the section on search expressions to get the full list).

       sortdir determines whether we sort ascending or descending.

       Example  (note:  search expressions like ’s:hello’ are discussed in the
       next section):

        $ mu-find --sortfields=fz --sortdir=a s:hello

       would sort messages ascending, with a  subject  containing  ’hello’  by
       sender, then by size.

       The  default is to sort descending by date. However,if any sortfield is
       explicitly specified, the default sort order is ascending.

SEARCH EXPRESSIONS

       Search expressions are short descriptions that describe the messages to
       find.  Search  expresssions  consist of a character that specifies some
       property, followed by a ’:’ and some  value  to  match.  The  following
       fields are recognized:

       s: subject
       f: from (sender)
       t: to (recipient)
       c: cc: (carbon-copy recipient)
       m: message id
       p: message priority
       P: path to the message
       d: date
       z: size
       F: flags

       And two special types:
       x: xapian search
       B: bookmarks

       Option  x: for ’xapian search’ searches the contents of messages, while
       the other options search for a certain  property  (’metadata’)  of  the
       message. Xapian searching is discussed after the other options.

       Option  B:  refers to bookmarks. You can define ’bookmarks’ (shortcuts)
       for search expression. Bookmarks are discussed later in this  document.

Words

       Now,  let’s discuss search expressions where a certain message property
       contains a word.  We have following word or textual types:

       s: subject
       f: from (sender)
       t: to (recipient)
       c: Cc: (carbon-copy recipient)
       m: message id
       p: message priority
       P: path to the message

       For example, the search expression: s:rain matches all  messages  which
       have  ’rain’  in their subject (s:) (including training, brain, terrain
       etc.)

       f: matches all messages sent by (From:), as well as  all  messages  by.
       Search  expressions  can be combined - we can say f:bobs:new york’ to
       get all message from Bob about New York (search expressions with spaces
       need quotes).

       Sometimes,  we  might  want  to  match  messages  that dont contain as
       certain word in some property. To get all mails  that  do  not  contain
       ’banana’ in their subject we can use the ^ prefix: s:^banana

       And sometimes we might want to match a word exactly ie, we don’t want a
       property to contain the search string, but we want  it  to  be  exactly
       equal.  For  that  we  can  use the ’=’: s:=hello to match exactly that
       string (e.g., it won’t match ’Hello World’).

       Please note that ’=’ and ’^’ only work for textual fields, and ’^’ only
       for textual fields and flags.

Numbers and intervals

       Certain  properties  of  messages  are  better  expressed as numbers or
       intervals than as words, such as the message size or the message date:

       d: date
       z: size

Message size

       First, let’s look at the message size (the on-disk  file  size  of  the
       message).  We could search for a message of size 500K with: z:500k (’k’
       for kilobyte and  ’M’  megabyte  are  supported).  In  many  cases,  an
       interval
         is probably more useful, so we can write: z:250k-750k to get messages
       between 250k and 750k, and z:1M- or z:-2M  to  get  messages  that  are
       either   bigger  than  1M  and  messages  that  are  smaller  than  2M,
       respectively.

Message date

       Another useful  interval  type  is  the  message  date.  Dates  can  be
       specified in many different ways, and may have different meanings based
       on your locale. The recommended format therefore is YYYYMMDD,  although
       other  formats  may  work  as  well - provided the dates do not contain
       ’-’-characters.

       To get all mails in January 2005, we can write: d:20050101-20050131 and
       we can use the same interval notation as for the message size and write
       d:20080801-  to  get  all  mails  received  since  August   2008,   and
       d:-20033112 to get all mails from 2003 and before.

       Single  dates (such as d:20080202 ) are interpreted as an interval from
       the beginning of that day until the end of the day.

       mu-find also recognizes a number followed by ’d’, ’w’, ’f’, ’m’, ’y’ to
       mean  some number of resp. days, weeks, fortnights, months or years ago
       since the present. Thus, d:3d- matches all messages from the last three
       days,  while  d:2y-1m matches all messages that are between 2 years and
       one month old.

       Note that months are assumed to be 30 days, and years 365 days.

Message priority

       The message priority is one of ’L’ (low), ’N’ (normal) or  ’H’  (high).
       To  match  all messages that are have either normal or high importance,
       the  expression  would  be:  p:NH  and  match  only  messages  of   low
       importance: p:L

       Note,  messages  that  do  not  explicitly specify their importance are
       assumed to be of normal priority.

Flags

       The last type of search expression are message flags.   Message  either
       describe  some  property  of  the email file (file flags), or about the
       contents (content flags).

       You can search message by the following file flags: new (’N’),  replied
       (’R’),  flagged  (’F’),  passed  (’P’),  seen  (’S’),  or  combinations
       thereof. For example, to get all new  messages:  F:N  or  the  get  all
       flagged  message you replied to: F:RF New (’N’) messages don’t have any
       other flags, the other flags can be combined.

       Then, there are content flags: has-attachment (’a’), signed  (’s’)  and
       encrypted  (’x’). For example, you could search for all signed messages
       with an attachment with: F:as

       You can also search for the absence of a flag, by  prefixing  the  flag
       with  ’^’  character.  So  for  example,  to get all encrypted messages
       without attachments, you can use: F:x^a

Xapian

       mu uses the Xapian indexing library to search message contents. For the
       end-user,  the  use  of Xapian is mostly a technical detail, except for
       the   fact   that   Xapian   searches   follow   the   Xapian   syntax:
       http://xapian.org/docs/queryparser.html

       The  syntax  is  very  similar  to  what  WWW search engines offer. For
       example, to get all the messages about either apples  or  bananas,  the
       search expression would be:

       x:apples  OR  bananas (and note that on the command-line you would need
       to quote that as: mu-findx:apples OR bananas’ )

       That would get all messages  with  either  apples  or  bananas  in  the
       content  -- that is, the message body, the subject field and the sender
       and recipient fields. More complex queries are possible,  say,  x:apple
       NEAR pear OR NOT (orange XOR coconut)

       Xapian  searches  can  be combined with other search options, so to get
       all message from Alice  (alice@example.com)  regarding  unicorns,  use:
       f:alice@example.com x:unicorns

       NOTE: only up to 1000 documents are returned, and if you combine Xapian
       search with other search options, the result will be a subset of  that.
       In  other  words,  if you search query contains an ’x:’ option, the max
       number of results is 1000.

BOOKMARKS

       You can also define ’bookmarks’ for often-used search expressions. In a
       file called bookmarks in your Mu home directory, you can specify them:
       [important]
       expr=p:H t:me@example.com f:boss@example.com

       [recentdrink]
       expr=d:1w- x:’wine OR beer OR whisky OR gin OR vodka’

       You  can  then  write  search queries with the B: prefix, e.g.  mu-find

       -B:important d:1m-
       You can combine  bookmarks  with  other  search  expressions;  however,
       bookmarks  cannot contain other bookmark expressions. This might change
       in the future.

CONFIGURATION

       Instead of specifying the options on the command  line,  you  can  also
       specify  them  in  the  mu.conf  configuration  file,  in  the  mu-home
       directory (by default, ~/.mu ). The General options go in  the  section
       [mu]  while  the  mu-find  specific  options  go  under [mu-find].  For
       example, your configuration file could look something like this:

       [mu]
       debug=false

       [mu-info]
       format=f,d

       Note that command line arguments take precedence over the configuration
       file.

MUTT INTEGRATION

       mu-find  can  be  integrated  with  the mutt(1) email client using some
       macros:

       macro index <F8> "<shell-escape>rm -rf ~/.mumatch; mu-find -o l -l ~/.mumatch " "mu-find"
       macro index <F9> "<change-folder-readonly>~/.mumatch
" "display mu-find results"

       Now, <F8> will perform a search, and <F9> will  change  to  the  folder
       with the results.

BUGS

       Please       report       bugs       when      you      find      them:
       http://code.google.com/p/mu0/issues/list

AUTHOR

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

SEE ALSO

       mu-index(1), sqlite3(1), mutt(1)