mu/man/mu.1

.TH MU 1 "January 2010" "User Manuals"
.SH NAME 
mu \- index and search the contents of e-mail messages stored in Maildirs

.SH SYNOPSIS
.B mu <command> [options] [parameter(s)]  

.SH DESCRIPTION
\fBmu\fR is a set of tools 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.

\fBmu\fR also offers functionality for creating maildirs.

The various tools are available as commands for a single
\fBmu\fR executable.

.SH GENERAL OPTIONS
\fBmu\fR offers a number of general options -- options that apply to all commands:

.TP
\fB\-a\fR, \fB\-\-muhome\fR causes \fBmu\fR to use an alternative directory to
store and read its database and logs. By default, \fB~/.mu\fR is used.

.TP
\fB\-d\fR, \fB\-\-debug\fR makes \fBmu\fR generate extra debug information,
useful for debugging the program itself. Note that by default, debug
information goes to the log file, \fI~/.mu/mu.log\fR.

.TP
\fB\-q\fR, \fB\-\-quiet\fR causes \fBmu\fR not to output informational
messages to standard output, but only to the log file. Error messages will
still be sent to standard error.

.TP
\fB\-e\fR, \fB\-\-log-stderr\fR causes \fBmu\fR not to output all log messages
to standard error, in addition to sending them to the log file.

.TP
\fB\-v\fR, \fB\-\-version\fR outputs the \fBmu\fR-version and copyright
information.

.TP
\fB\-h\fR, \fB\-\-help\fR list the various command line options, while
\fB\-\-help\-index\fR, \fB\-\-help\-find\fR and \fB\-\-help\-all\fR list only
the options for one command, or all of the commands.


.SH COMMANDS
\fBmu\fR 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
\fBmkdir\fR
for creating Maildirs.

.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 (\fIcur\fR and \fInew\fR) are ignored.

Currently, symlinks are not followed.

If there is 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
may take a few minutes if you have a lot of mail (ten thousands of messages).
Fortunately, such a full scan needs to be done only once, after that it
suffices to index the changes, which goes much faster. Also note that a
substantial amount of the time goes to printing the progress information; if
you turn that off (with \fB\-q\fR or \fB\-\-quiet\fR), it goes a lot faster.

Phase two of the indexing-process is the removal of messages from the database
for which there is no longer a corresponding file in the Maildir. If you do
not want this, you can use \fB\-u\fR, \fB\-\-nocleanup\fR.

.SS Indexing options

.TP
\fB\-m\fR, \fB\-\-maildir\fR=\fI<maildir>\fR starts searching
at\fI<maildir>\fR. By default,
\fBmu\fR uses whatever the
.B MAILDIR
environment variable 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.

.T
\fB\-u\fR, \fB\-\-nocleanup\fR disables the database cleanup that
\fBmu\fR does by default after indexing.


.TP

.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 messages in the database that match the search
pattern. The search pattern is taken as a command line parameter. If the
search parameter consists of multiple parts (multiple command line parameters)
they are treated as if there were a logical \fBAND\fR between them.

If you want to make your own constructions (using \fBAND\fR, \fBOR\fR,
\fBNOT\fR etc., you have to put quote them so \fBmu\fR can consider them as a
unit.

\fBmu\fR relies on the Xapian database for its searching capabilities, so it
offers all the search functionality that Xapian offers; please refer to:

\fIhttp://xapian.org/docs/queryparser.html\fR

Here, we will show the mu-specific ways to specify search patterns.


.SS find options

.SS query syntax
In its simplest form, you can just can just specify a number of words, and
\fBmu\fR 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 THE MKDIR COMMAND
With the
.B mkdir
command, you can create new Maildirs with permissions 0755. For example,
.nf
   mu mkdir tom dick harry
.fi
will create three Maildirs \fItom\fR, \fIdick\fR and \fIharry\fR.

If the creation somehow fails, for safety reasons, \fBno\fR attempt is made to
remove any parts that were created.

.SH ENVIRONMENT
As mentioned, \fBmu index\fR uses \fBMAILDIR\fR to find the user's Maildir if
it has not been specified explicitly \fB\-\-maildir\fR=\fI<maildir>\fR. If
MAILDIR is not set, \fBmu index\fR will try \fI~/Maildir\fR.
.
.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 <djcb@djcbsoftware.nl>

.SH "SEE ALSO"
.BR maildir(5)