Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MU(FIND)			 User Manuals			      MU(FIND)

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

       mu find [options] <search expression>

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

       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	<> running in the snow
	 2009-03-05 18:38:24 EET Marius	<> 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-sec-
       tion 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 de-
       tails, see:

       One  special  feature of	mu is that is does not distinguish between up-
       percase and lowercase, nor the accented or unaccented versions of char-
       acters.	All  match. In general,	mu tries to be 'eager' in matching, as
       filtering out unwanted results is usually preferable over non  matching

       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  charac-
       ters  before the	wildcard. mu supports wildcard searches	for all	fields
       except maildirs and paths. 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 im-
       portant 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.

       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 ei-
       ther body or subject or one of the address-fields (to/from/cc).

       As mentioned, matching is case-insensitive and accent-insensitive; thus

	 $ mu find MA<paragraph>nkey BANAAAY

       yields the same results as the example above.

       mu also recognizes prefixes for specific	fields in a messages; for  ex-

	 $ 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
	    body,b	    Message body
	    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 re-
       quire some extra	discussion. 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,trashed	    Marked for deletion
	    a,attach	    Has	attachment
	    z,signed	    Signed message
	    x,encrypted	    Encrypted message
	    l,list	    Mailing-list message

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

	 $ mu find flag:signed flag:attach

       Encrypted messages may be signed	as well, but this is only visible  af-
       ter 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 mes-
       sages 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/run-
       ning/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 in-
       terval. 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. If you omit the left
       part completely,	the beginning date is assumed to be January 1, year  0
       at  00:00.   Likewise,  if you omit the right part, the end data	is as-
       sumed to	be to the last second of the year 9999.

       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 positive	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
       present	moment	and  'today' for the beginning of today. So to get all
       messages	sent or	received today,	you could use:

	 $ mu find

       The size	or z allows you	to match size ranges --	that  is,  match  mes-
       sages  that  have  a  byte-size	within	a certain range. Units (B (for
       bytes), K (for 1000 bytes) and M	(for  1000  *  1000  bytes)  are  sup-
       ported).	 For example, to get all messages between 10Kb and 2Mb (assum-
       ing 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 ""

       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 men-
	      tions 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
		   v	   Mailing-list	Id

	      The message flags	are the	same ones we already saw in  the  mes-
	      sage  flags  above.  Thus, a message which is 'seen', has	an at-
	      tachment 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 re-
	      verted - 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	   Nessage priority
		   subject,s	   Message subject
		   to,t		   To:-recipient(s)
		   list,v	   Mailing-list	id

	      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 high-
	      est).  This  is  usually	a good choice, but for dates it	may be
	      more useful to sort in the opposite direction.

       -n, --maxnum=<number>
	      If > 0, display maximally	that number of entries.	 If not	speci-
	      fied, all	matching entries are displayed.

	      If  >  0,	 use  that number of lines of the message to provide a

	      output results in	the specified format.

	      The default is plain, i.e	normal output with one line  per  mes-

	      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 di-
	      rectory before, but this has a big chance	of accidentally	remov-
	      ing 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  automati-
	      cally  inserts a .noindex	file, to exclude the directory from mu

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

	      the  --exec  command  causes  the	command	to be executed on each
	      matched message; for example, to see the raw text	 of  all  mes-
	      sages 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  occurrence  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 re-
	      lated 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 ta-

	      |		    | 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
	      Zawinksi's description:

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

	 $ 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 (right-
       most) part of a search term.  Note[3]: non-word characters (such	as  a~
       or ao) are ignore in queries; you cannot	search for them.

   Integrating mu find with mail clients

	      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"


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

	      (require 'elmo-search)
		  '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  ex-
	      pression	by adding something like the following to your folders

	      VFolders {
		[]!mu  "Today"

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

		[flag:unread]!mu      "Unread"

	      After restarting Wanderlust, the virtual folders should appear.

	      Wanderlust (old)

	      Another way to integrate 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 "/"
		     (cmdline (concat mu-wl-mu-program " find "
			      "--clearlinks --format=links --linksdir='" sfldr "' "
		     (rv (shell-command	cmdline)))
		    ((=	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"
		(when (mu-wl-search)
		    (concat "."	mu-wl-search-folder)
		    'force-update nil nil t)

	      ;; querying both in summary and folder
	      (define-key wl-summary-mode-map (kbd "Q")	;; => query
	      (define-key wl-folder-mode-map (kbd "Q") ;; => query

       mu find returns 0 upon successful completion; if	the  search  was  per-
       formed,	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	       |

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

       Please  report bugs if you find them:
       If you have specific messages which are not matched  correctly,	please
       attach them (appropriately censored if needed).

       Dirk-Jan	C. Binnema <>

       mu(1) mu-index(1)

19 April 2015			       1			      MU(FIND)


Want to link to this manual page? Use this URL:

home | help