FreeBSD Manual Pages
MU FIND(1) General Commands Manual MU FIND(1) NAME mu-find - find e-mail messages in the mu database. SYNOPSIS mu [COMMON-OPTIONS] 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. The search patterns are described in detail in mu- query(7). For example: $ mu find subject:snow and date:2009.. would find all messages in 2009 with `snow' in the subject field, e.g: 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 This uses the default, plain output (implicitly, --format=plain). For other output formats (such as symlinks, XML, s-expressions or JSON), see the discussion of --format in the OPTIONS-section below. 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). FIND OPTIONS Note, some of the important options are described in the mu(1) manual 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 out- put. 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" lists the date, subject and sender of all messages with `snow' in the their subject. The table of replacement characters is super-set of the list mentioned for search parameters, such as: t *t*o: recipient d Sent *d*ate of the message f Message sender (*f*rom:) g Message flags (fla*g*s) l Full path to the message (*l*ocation) s Message *s*ubject i Message-*i*d m *m*aildir For the complete list, try the command: mu info fields. The message flags are described in mu-query(7). As an example, a mes- sage which is `seen', has an attachment and is signed has asz as its corresponding output string, while an encrypted new message has nx. -s, --sortfield field and -z,--reverse Specify the field to sort the search results by and the direction (i.e., `reverse' means that the sort should be reverted - Z-A). Exam- ples include: cc,c Cc (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) For the complete list, try the command: mu info fields. 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 usu- ally a good choice, but for dates it may be more useful to sort in the opposite direction. -n, --maxnum number If number > 0, display maximally that number of entries. If not speci- fied, all matching entries are displayed. --summary-len number If number > 0, use that number of lines of the message to provide a summary. --format plain|links|xml|sexp|json|json2 Output results in the specified format. -- The default is plain, i.e., normal output with one line per mes- sage. -- 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). This requires --linksdir. -- xml formats the search results as XML. -- sexp formats the search results as an s-expression as used in Lisp programming environments. -- json formats the output as JSON; it is a direct translation of the sexp format -- json2 is a slightly more idiomatic JSON, for now the only differ- ence with json is that the latter avoids the ':' prefix in key- names (e.g., "subject" instead of ":subject"). json2 is still ex- perimental. --linksdir dir and -c, --clearlinks When using --format=links, output the results as a maildir with sym- bolic 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, existing symlinks will be cleared from the target directories; this allows for re-use of the same maildir. How- ever, this option will delete any symlink it finds, so be careful. $ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks stores 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 option causes command to be executed on each matched mes- sage; for example, to see the raw text of all messages matching `milk- shake', 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-book- marks(5) for the details of the bookmarks file. -u, --skip-dups Whenever there are multiple messages with the same message-id field, 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. -r, --include-related Include messages being referred to by the matched messages -- i.e.. in- clude messages that are part of the same message thread as some matched messages. This is useful if you want Gmail-style `conversations'. -t, --threads Show messages in a `threaded' format -- that is, with indentation and arrows showing the conversation threads in the list of matching mes- sages. When using this, sorting is chronological (by date), based on the newest message in a thread. 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 in- formation 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 mes- sage-id was copied. The algorithm used for determining the threads is based on Jamie Za- winksi's description: http://www.jwz.org/doc/threading.html -a,--analyze Instead of executing the query, analyze it by show the parse-tree s-ex- pression and a stringified version of the Xapian query. This can help users to determine how mu interprets some query. The output of this command are differ between versions, but should be helpful nevertheless. --muhome Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Ear- lier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu. The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. COMMON OPTIONS -d, --debug Makes mu generate extra debug information, useful for debugging the program itself. Debug information goes to the standard logging loca- tion; see mu(1). -q, --quiet Causes mu not to output informational messages and progress information to standard output, but only to the log file. Error messages will still be sent to standard error. Note that mu index is much faster with --quiet, so it is recommended you use this option when using mu from scripts etc. --log-stderr Causes mu to not output log messages to standard error, in addition to sending them to the standard logging location. --nocolor Do not use ANSI colors. The environment variable NO_COLOR can be used as an alternative to --nocolor. -V, --version Prints mu version and copyright information. -h, --help Lists the various command line options. INTEGRATION It is possible to integrate mu find with some 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 configuration 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 perma- nent 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. ENCODING mu find output is encoded according to the locale wwhen using --for- mat=plain (the default format), and UTF-8 for all other formats (sexp, xml). PERFORMANCE Some notes on performance, comparing the timings between some recent releases; taking the total number for 10 test runs. 1. time (repeat 10 mu find "" -n 50000 > /dev/null) 2. time (repeat 10 mu find "" -n 50000 --include-related --threads > /dev/null) +---------------------------------------------+ | release time 1 (sec) time 2 (sec) | +---------------------------------------------+ | 1.4 8.9s 59.3s | | 1.6 8.3s 27.5s | | 1.8 8.7s 29.3s | | 1.10 9.8s 30.6s | | 1.11 (master) 10.1s 29.5s | +---------------------------------------------+ EXIT CODE This command returns 0 upon successful completion, or a non-zero exit code otherwise. 0. success 2. no matches found. Try a different query 11. database schema mismatch. You need to re-initialize mu, see mu- init(1) 19. failed to acquire lock. Some other program has exclusive access to the mu database 99. caught an exception REPORTING BUGS Please report bugs at https://github.com/djcb/mu/issues. AUTHOR Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> COPYRIGHT This manpage is part of mu 1.12.15. Copyright 2008-2026 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL ver- sion 3 or later https://gnu.org/licenses/gpl.html. This is free soft- ware: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. SEE ALSO mu(1), mu-index(1), mu-query(7), mu-info(1) MU FIND(1)
NAME | SYNOPSIS | DESCRIPTION | SEARCHING MAIL | FIND OPTIONS | COMMON OPTIONS | INTEGRATION | ENCODING | PERFORMANCE | EXIT CODE | REPORTING BUGS | AUTHOR | COPYRIGHT | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mu-find&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>