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.	 The  search  patterns	are described in detail	in mu-

       For example:

	  $ mu find subject:snow and date:2017..

       would find all messages in 2017 with 'snow' in the subject field, e.g:

	 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.

       For details on the possible queries, see	mu-query(7).

       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 described in mu-query(7). As an example, a
	      message  which  is 'seen', has an	attachment and is signed would
	      have 'asz' as its	corresponding  output  string,	while  an  en-
	      crypted 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).

	      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	directories; this allows for re-use of
	      the same maildir.	However, this option will delete  any  symlink
	      it finds,	so be careful.

		$ mu find grolsch --format=links --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	referred 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.	When using this, sort-
	      ing is chronological (by date), based on the newest message in a

	      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:

   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), mu-query(7)

22 June	2021			       1			      MU(FIND)


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

home | help