man: update man pages
Explicitly mention PCRE where appropriate. Include section headers (through MAN_CLASS_OPTIONS) Fix mu-easy manpage Make date dynamic
This commit is contained in:
Dirk-Jan C. Binnema
303
man/mu-easy.7.org
Normal file
303
man/mu-easy.7.org
Normal file
@ -0,0 +1,303 @@
|
||||
#+TITLE: MU EASY
|
||||
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||
|
||||
* NAME
|
||||
|
||||
mu easy - a quick introduction to mu
|
||||
|
||||
* DESCRIPTION
|
||||
|
||||
*mu* is a set of tools for dealing with e-mail messages in Maildirs. There are
|
||||
many options, which are all described in the man pages for the various
|
||||
sub-commands. This man pages jumps over all of the details and gives examples of
|
||||
some 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(1)* or *mu-find(1)* man
|
||||
pages.
|
||||
|
||||
*NOTE*: the *index* command (and therefore, the ones that depend on that, such as
|
||||
*find*), require that you store your mail in the Maildir-format. If you don't do
|
||||
so, you can still use the other commands, but you won't be able to index/search
|
||||
your mail.
|
||||
|
||||
By default, *mu* uses colorized output when it thinks your terminal is capable of
|
||||
doing so. If you don't like color, you can use the *--nocolor* command-line
|
||||
option, or set either the *MU_NOCOLOR* or the *NO_COLOR* environment variable to
|
||||
non-empty.
|
||||
|
||||
* SETTING THINGS UP
|
||||
|
||||
The first time you run the mu commands, you need to initialize it. This is done
|
||||
with the *init* command.
|
||||
|
||||
#+begin_example
|
||||
$ mu init
|
||||
#+end_example
|
||||
|
||||
This uses the defaults (see *mu-init(1)* for details on how to change that).
|
||||
|
||||
|
||||
* INDEXING YOUR E-MAIL
|
||||
|
||||
Before you can search e-mails, you'll first need to index them:
|
||||
|
||||
#+begin_example
|
||||
$ mu index
|
||||
#+end_example
|
||||
|
||||
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.
|
||||
|
||||
*mu index* guesses the top-level Maildir to do its job; if it guesses wrong, you
|
||||
can use the =--maildir= option to specify the top-level directory that should be
|
||||
processed. See the *mu-index*(1) man page for more details.
|
||||
|
||||
Normally, *mu index* visits all the directories under the top-level Maildir;
|
||||
however, you can exclude certain directories (say, the 'trash' or 'spam'
|
||||
folders) by creating a file called =.noindex= in the directory. When *mu* sees such
|
||||
a file, it will exclude this directory and its sub-directories from indexing.
|
||||
Also see *.noupdate* in the *mu-index*(1) manpage.
|
||||
|
||||
* SEARCHING YOUR E-MAIL
|
||||
|
||||
After you have indexed your mail, you can start searching it. By default, the
|
||||
search results are printed on standard output. Alternatively, the output can
|
||||
take the form of Maildir with symbolic links to the found messages. This enables
|
||||
integration with e-mail clients; see the *mu-find*(1) man page for details, the
|
||||
syntax of the search parameters and so on. Here, we just give some examples for
|
||||
common cases.
|
||||
|
||||
You can use the *mu fields* command to get information about all possible fields
|
||||
and flags.
|
||||
|
||||
First, let's search for all messages sent to Julius (Caesar) regarding fruit:
|
||||
|
||||
#+begin_example
|
||||
$ mu find t:julius fruit
|
||||
#+end_example
|
||||
|
||||
This should return something like:
|
||||
|
||||
#+begin_example
|
||||
2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
|
||||
#+end_example
|
||||
|
||||
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 date format depends
|
||||
on your the language/locale you are using.
|
||||
|
||||
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 =--fields= parameter
|
||||
(try *mu fields* to see all the details):
|
||||
|
||||
#+begin_example
|
||||
$ mu find --fields="t s" t:julius fruit
|
||||
#+end_example
|
||||
|
||||
In other words, display the 'To:'-field (t) and the subject (s). This should
|
||||
return something like:
|
||||
#+begin_example
|
||||
Julius Caesar <jc@example.com> Fere libenter homines id quod volunt credunt
|
||||
#+end_example
|
||||
|
||||
This is the same message found before, only with some different fields
|
||||
displayed.
|
||||
|
||||
By default, *mu* 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:
|
||||
|
||||
#+begin_example
|
||||
$ mu find t:julius OR f:socrates
|
||||
#+end_example
|
||||
|
||||
In other words, display messages that are either sent to Julius Caesar *or* are
|
||||
from Socrates. This could return something like:
|
||||
|
||||
#+begin_example
|
||||
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
|
||||
#+end_example
|
||||
|
||||
What if we want to see some of the body of the message? You can get a 'summary'
|
||||
of the first lines of the message using the =--summary-len= option, which will
|
||||
'summarize' the first =n= lines of the message:
|
||||
|
||||
#+begin_example
|
||||
$ mu find --summary-len=3 napoleon m:/archive
|
||||
#+end_example
|
||||
|
||||
#+begin_example
|
||||
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
|
||||
#+end_example
|
||||
|
||||
The summary consists of the first /n/ lines of the message with all superfluous
|
||||
whitespace removed.
|
||||
|
||||
Also note the *m:/archive* parameter in the query. This means that we only match
|
||||
messages in a maildir called ~'/archive'~.
|
||||
|
||||
* MORE QUERIES
|
||||
|
||||
Let's list a few more queries that may be interesting; please note that
|
||||
searches for message flags, priority and date ranges are only available in mu
|
||||
version 0.9 or later.
|
||||
|
||||
Get all important messages which are signed:
|
||||
#+begin_example
|
||||
*$ mu find flag:signed prio:high *
|
||||
#+end_example
|
||||
|
||||
Get all messages from Jim without an attachment:
|
||||
#+begin_example
|
||||
*$ mu find from:jim AND NOT flag:attach*
|
||||
#+end_example
|
||||
|
||||
Get all messages where Jack is in one of the contact fields:
|
||||
#+begin_example
|
||||
*$ mu find contact:jack*
|
||||
#+end_example
|
||||
This uses the special contact: pseudo-field which matches (*from*,
|
||||
*to*, *cc* and *bcc*).
|
||||
|
||||
Get all messages in the Sent Items folder about yoghurt:
|
||||
#+begin_example
|
||||
*$mu find maildir:'/Sent Items' yoghurt*
|
||||
#+end_example
|
||||
Note how we need to quote search terms that include spaces.
|
||||
|
||||
|
||||
Get all unread messages where the subject mentions Ångström:
|
||||
#+begin_example
|
||||
*$ mu find subject:Ångström flag:unread*
|
||||
#+end_example
|
||||
which is equivalent to:
|
||||
#+begin_example
|
||||
*$ mu find subject:angstrom flag:unread*
|
||||
#+end_example
|
||||
because does mu is case-insensitive and accent-insensitive.
|
||||
|
||||
Get all unread messages between March 2002 and August 2003 about some bird (or
|
||||
a Swedish rock band):
|
||||
#+begin_example
|
||||
*$ mu find date:20020301..20030831 nightingale flag:unread*
|
||||
#+end_example
|
||||
|
||||
Get all messages received today:
|
||||
#+begin_example
|
||||
*$ mu find date:today..now*
|
||||
#+end_example
|
||||
|
||||
Get all messages we got in the last two weeks about emacs:
|
||||
#+begin_example
|
||||
*$ mu find date:2w..now emacs*
|
||||
#+end_example
|
||||
|
||||
Another powerful feature (since 0.9.6) are wildcard searches, where you can
|
||||
search for the last =n= characters in a word. For example, you can search
|
||||
for:
|
||||
#+begin_example
|
||||
*$ mu find 'subject:soc*'*
|
||||
#+end_example
|
||||
and get mails about soccer, Socrates, society, and so on. Note, it's important
|
||||
to quote the search query, otherwise the shell will interpret
|
||||
the '*'.
|
||||
|
||||
You can also search for messages with a certain attachment using their
|
||||
filename, for example:
|
||||
|
||||
#+begin_example
|
||||
*$ mu find 'file:pic*'*
|
||||
#+end_example
|
||||
will get you all messages with an attachment starting with 'pic'.
|
||||
|
||||
If you want to find attachments with a certain MIME-type, you can use the
|
||||
following:
|
||||
|
||||
Get all messages with PDF attachments:
|
||||
#+begin_example
|
||||
*$ mu find mime:application/pdf*
|
||||
#+end_example
|
||||
|
||||
or even:
|
||||
|
||||
Get all messages with image attachments:
|
||||
#+begin_example
|
||||
*$ mu find 'mime:image/*'*
|
||||
#+end_example
|
||||
|
||||
|
||||
Note that (1) the '*' wildcard can only be used as the rightmost thing in a
|
||||
search query, and (2) that you need to quote the search term, because
|
||||
otherwise your shell will interpret the '*' (expanding it to all files in the
|
||||
current directory -- probably not what you want).
|
||||
|
||||
* DISPLAYING MESSAGES
|
||||
|
||||
We might also want to display the complete messages instead of the header
|
||||
information. This can be done using *mu view* command. Note that this
|
||||
command does not use the database; you simply provide it 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 *l*ocation) for our first example we
|
||||
can use:
|
||||
|
||||
#+begin_example
|
||||
$ mu find --fields="l" t:julius fruit
|
||||
#+end_example
|
||||
|
||||
And we'll get something like:
|
||||
#+begin_example
|
||||
/home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
|
||||
#+end_example
|
||||
|
||||
We can now display this message:
|
||||
|
||||
#+begin_example
|
||||
$ mu view /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
|
||||
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 taste
|
||||
Brought Death into the World, and all our woe,
|
||||
[...]
|
||||
#+end_example
|
||||
|
||||
* FINDING CONTACTS
|
||||
|
||||
While *mu find* searches for messages, there is also *mu cfind* to find =contacts=,
|
||||
that is, names + addresses. Without any search expression, *mu cfind* lists all of
|
||||
your contacts.
|
||||
|
||||
#+begin_example
|
||||
$ mu cfind julius
|
||||
#+end_example
|
||||
|
||||
will find all contacts with 'julius' in either name or e-mail address. Note that
|
||||
*mu cfind* accepts a =regular expression= (as per *pcre(3)*)
|
||||
|
||||
*mu cfind* also supports a =--format==-parameter, which sets the output to some
|
||||
specific format, so the results can be imported into another program. For
|
||||
example, to export your contact information to a *mutt* address book file, you can
|
||||
use something like:
|
||||
|
||||
#+begin_example
|
||||
$ mu cfind --format=mutt-alias > ~/mutt-aliases
|
||||
#+end_example
|
||||
|
||||
Then, you can use them in *mutt* if you add something like *source ~/mutt-aliases*
|
||||
to your =muttrc=.
|
||||
|
||||
#+include: "prefooter.inc" :minlevel 1
|
||||
|
||||
* SEE ALSO
|
||||
*mu(1)*, *mu-init(1)*, *mu-index(1)*, *mu-find(1)*, *mu-mfind(1)*, *mu-mkdir(1)*, *mu-view(1)*, *mu-extract(1)*
|
||||
Reference in New Issue
Block a user