mu/man/mu-easy.1

.TH MU-EASY 1 "October 2010" "User Manuals"

.SH NAME 

mu easy \- a quick introduction to mu

.SH DESCRIPTION

As you may know, \fBmu\fR is a set of tools for dealing with e-mail messages
in Maildirs. There are many options, which are all described in the individual
man pages for the various sub-commands. This man pages jumps over all the
details and gives examples of the more common use cases. If the use cases
described here do not precisely do what you want, please check the more
extensive information in the man page about the sub-command you are using --
for example, the mu-index or mu-find man pages.

\fBNOTE\fR: the \fBindex\fR command (and therefore, the ones that depend on
that, such as \fBfind\fR), require that you store your mail in the
Maildir-format. If you don't do so, you can still use the other commands, but
cannot index/search your mail.

.SH INDEXING YOUR E-MAIL
Before you can search e-mails, you'll first need to index them:

.nf
\fB$ mu index\fR 
.fi

The process can take a few minutes, depending on the amount of mail you have,
the speed of your computer, hard drive etc. Usually, indexing should be able to
reach a speed of a few hundred messages per second.

\fBmu index\fR guesses the top-level Maildir to do its job; if it guesses
wrong, you can use the \fI--maildir\fR option to specify the top-level
directory that should be processed. See the \fBmu-index\fR man page for more
detail.

.SH SEARCHING YOUR E-MAIL
After you have indexed your mail, you can search it. Normally, the search
results are to standard output, but the output can also be in the form of
Maildir with symbolic links to the found messages. This enables integration
with e-mail clients; see the \fBmu-find\fR man page for details, the syntax of
the search parameters and so on. Here, we just give some examples for common
cases.

First, let's search for all messages sent to Julius Caesar regarding fruit:

.nf
\fB$ mu find t:julius fruit\fR 
.fi

This should return something like:

.nf
  2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
.fi

This means there is a message to 'julius' with 'fruit' somewhere in the
message. In this case, it's a message from John Milton. Note that the display
of the date depends on your system locale.

How do we know that the message was sent to Julius Caesar? Well, it's not
visible from the results above, because the default fields that are shown are
date-sender-subject. However, we can change this using the \fI--fields\fR
parameter (see the \fBmu-find\fR man page for the details):

.nf
\fB$ mu find --fields="t s" t:julius fruit\fR 
.fi

In other words, display the 'To:'-field (t) and the subject (s). This should
return something like:
.nf
  Julius Caesar <jc@example.com> Fere libenter homines id quod volunt credunt
.fi

This is the same message found before, only with some different fields displayed.

By default, \fBmu\fR uses the logical AND for the search parameters -- that
is, it displays messages that match all the parameters. However, we can use
logical OR as well:

.nf
\fB$ mu find t:julius OR f:socrates\fR 
.fi

In other words, display messages that are either sent to Julius Caesar
\fBor\fR are from Socrates. This could return something like:

.nf
  2008-07-31T21:57:25 EEST Socrates <soc@example.com> cool stuff
  2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
.fi

What if we want to see some of the body of the message?  You can list (parts
of) the message contents by using the --summary-len=\fIn\fR option, which
will 'summarize' the first \fIn\fR lines of the message:

.nf
\fB$ mu find --summary-len=4 napoleon m:/archive\fR 
.fi

.nf
  1970-01-01T02:00:00 EET Napoleon Bonaparte <nb@example.com> rock on dude
  Summary: Le 24 février 1815, la vigie de Notre-Dame de la Garde signala le
  trois-mâts le Pharaon, venant de Smyrne, Trieste et Naples. Comme
  d'habitude, un pilote côtier partit aussitôt du port, rasa le château
.fi

The summary consists of the first n lines of the message with all superfluous
whitespace removed.

Also note the \fBm:/archive\fR parameter in the query. This means that we only
match messages in a maildir called '/archive'.

.SH DISPLAYING MESSAGES

We might also want to display complete messages. This can be done using \fBmu
view\fR command. Note that this command does not use the database; you simply
provide the path to a message.

Therefore, if you want to display some message from a search query, you'll
need its path. To get the path (think \fBl\fRocation) for our first example we
can use:

.nf
\fB$ mu find --fields="l" t:julius fruit\fR 
.fi

And we'll get someting like:
.nf
  /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
.fi
We can now display this message: 

.nf
\fB$ mu view /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,\fR

  From: John Milton <jm@example.com>
  To: Julius Caesar <jc@example.com>
  Subject: Fere libenter homines id quod volunt credunt
  Date: 2008-07-31T21:57:25 EEST

  OF Mans First Disobedience, and the Fruit
  Of that Forbidden Tree, whose mortal tast
  Brought Death into the World, and all our woe,
[...]
.fi

.SH BUGS
Please report bugs if you find them:
.BR http://code.google.com/p/mu0/issues/list

.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

.SH "SEE ALSO"
mu(1) mu-index(1) mu-cleanup(1) mu-find(1) mu-mkdir(1) mu-view(1) mu-extract(1)