.TH MU 1 "December 2009" "User Manuals" .SH NAME mu \- index and search the contents of e-mail messages stored in Maildirs .SH SYNOPSIS .B mu [options] [parameter(s)] .SH DESCRIPTION .B mu is a tool for indexing and searching e-mail messages stored in Maildirs. It does so by recursively scanning a Maildir directory tree and analyzing the e-mail messages found. The results of this analysis are then stored in a database. Using this database, you can quickly search for specific messages. .SH COMMANDS .B mu offers the following commands. .TP \fBindex\fR for indexing (analyzing) the contents of your Maildirs, and storing the information in a database .TP \fBfind\fR for finding messages in your database, using certain search parameters (see below for details). You can use \fBquery\fR and \fBsearch\fR as synonyms for \fBfind\fR. .TP One can can run these command by either using \fBmu index\fR or \fBmu find\fR \ from the command line, plus any parameters they take. In the following, we \ discusses these commands in detail. .SH THE INDEX COMMAND Using the .B index command, you can index your Maildir directories, and store the information in a Xapian database. .B index understands Maildirs as defined by Dan Bernstein for qmail(7). It also understands recursive Maildirs (Maildirs within Maildirs), and the VFAT-version of Maildir, as used by Tinymail/Modest. E-mail messages which are not stored in something that looks like a Maildir leaf directory are ignored. Currently, symlinks are not followed. Also, if there's a file called .B .noindex in a directory, the contents of that directory and any of its subdirectories will be ignored. This can be useful to exclude certain directories from the indexing process, for example directories with spam-messages. The first run of .B mu index can take some time; on the author's laptop using mu version 0.6, scans more than 1000 messages per second. Note that a full scan has to be done only once, after that it suffices to index the changes, which goes much faster. .SS Indexing options .TP \fB\-m\fR, \fB\-\-maildir\fR=\fI\fR start searching at Maildir \fB\fR. By default, .B mu uses whatever .B MAILDIR is set to; if that is not set, it tries .B ~/Maildir .TP \fB\-r\fR, \fB\-\-reindex\fR re-index all mails, even ones that are already in the database. .B NOTE: It is probably not a good idea to run multiple instances of .B mu index concurrently. No data loss should occur, but one or more of the instances may experience errors due to database locks. Also note that, before indexing is completed, searches for messages may fail, even if they have already been indexed, as some of the esssential database information will only be written in batches during the indexing process. .SH THE FIND COMMAND The .B find command starts a search for a specific message in the database. .SS find options .SS query syntax In its simplest form, you can just can just specify a number of words, and .B mu will search for messages that match all of those words. So, .nf $ mu find monkey banana .fi will find all messages which have both "monkey" AND "banana" in one of those fields. .SH OPTIONS .B mu has a number of general options, which work with all the commands. .B --maildir=, -m .I set the full path to the maildir; note that you can also specify this path as a non-option argument to .B mu-index ; if you use both, the non-option argument wins. .B --quiet|-q makes .B mu-index not put out any progress info during its indexing. This is not the default, as running may take quite some time, and might confuse novice users. .SS General options .B --home=, -h .I sets the .B mu home directory; default is .I ~/.mu \. This directory is where the message database is stored, as well as configuration files and logs. .B --log-stderr, -s write logging information to standard error instead of to .I /mu-find.log, which is the default. .B --debug, -d add a lot of logging for debugging purposes .SH CONFIGURATION Instead of specifying the options on the command line, you can also specify them in the .B mu-conf configuration file, in the mu home directory (by default, .B ~/.mu ). The .B General options go in the section .B [mu] while the .B mu-index specific options go under .B [mu-index]. For example, your configuration file could look something like this: .nf [mu] debug=false [mu-index] maildir=~/MyMaildir .fi Note that command line arguments take precedence over the configuration file. .SH MAILDIR SUPPORT .B mu-index supports an extended version of .BR maildir(5) ; in particular, it supports (a) a tree of Maildirs (strictly, the maildir specification does not allow this, but it is useful and widely supported), and (b) it supports '!' in addition to ':' as separators in mail filenames, which some e-mail programs (such as .BR modest(1) and the Maildir module in .BR python(1) use to support on VFAT filesystems, which don't allow ':' in filenames. .B mu-index ignores messages it cannot read or .BR stat(2) ; but failure to read or stat will be logged. Files starting with '.' are ignored, but directories are not. Thus, if there is a message .B .dotdir/new/mymsg1234 it will be indexed. This allows indexing .B Maildir++ directories, as used by .I CourierIMAP and .I Dovecot .B mu-index processes messages in .B cur/ and .B new/ leaf directories; it will ignore messages in .B tmp/ Thus, .B [....]/tmp/msg02 will be ignored, while .B [....]/new/msg01 won't. On the other hand, .B [....]/tmp/cur/msg03 would not be ignored, while .B [....]/cur/tmp/msg04 would. Note: single messages that are added by providing their full pathname to .B mu-index will not have their path checked. .SH ENVIRONMENT As mentioned, .B mu index uses .B MAILDIR to find the user's Maildir if it has not been specified explicitly. If .B MAILDIR is not set, .B mu index will try .B $HOME/Maildir . .SH BUGS There probably are some; please report bugs when you find them: .BR http://code.google.com/p/mu0/issues/list .SH AUTHOR Dirk-Jan C. Binnema .SH "SEE ALSO" .BR maildir(5)