mirror of https://github.com/djcb/mu.git
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:
parent
27ecbbdd65
commit
4b00ea0635
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
This manpage is part of ~mu~ @VERSION@.
|
This manpage is part of ~mu~ @VERSION@.
|
||||||
|
|
||||||
Copyright © 2022 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later
|
Copyright © @YEAR@ Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later
|
||||||
<https://gnu.org/licenses/gpl.html>. This is free software: you are free to
|
<https://gnu.org/licenses/gpl.html>. This is free software: you are free to
|
||||||
change and redistribute it. There is NO WARRANTY, to the extent permitted by
|
change and redistribute it. There is NO WARRANTY, to the extent permitted by
|
||||||
law.
|
law.
|
||||||
|
|
|
@ -17,8 +17,10 @@
|
||||||
#
|
#
|
||||||
# generate org include files
|
# generate org include files
|
||||||
#
|
#
|
||||||
|
year = run_command('date', '+%Y', check:true, capture:true)
|
||||||
man_data=configuration_data()
|
man_data=configuration_data()
|
||||||
man_data.set('VERSION', meson.project_version())
|
man_data.set('VERSION', meson.project_version())
|
||||||
|
man_data.set('YEAR', year.stdout().strip())
|
||||||
incs=[
|
incs=[
|
||||||
'author.inc',
|
'author.inc',
|
||||||
'bugs.inc',
|
'bugs.inc',
|
||||||
|
@ -46,7 +48,7 @@ man_orgs=[
|
||||||
'mu-add.1.org',
|
'mu-add.1.org',
|
||||||
'mu-bookmarks.5.org',
|
'mu-bookmarks.5.org',
|
||||||
'mu-cfind.1.org',
|
'mu-cfind.1.org',
|
||||||
'mu-easy.5.org',
|
'mu-easy.7.org',
|
||||||
'mu-extract.1.org',
|
'mu-extract.1.org',
|
||||||
'mu-fields.1.org',
|
'mu-fields.1.org',
|
||||||
'mu-find.1.org',
|
'mu-find.1.org',
|
||||||
|
@ -62,14 +64,27 @@ man_orgs=[
|
||||||
'mu-view.1.org'
|
'mu-view.1.org'
|
||||||
]
|
]
|
||||||
|
|
||||||
|
env = environment()
|
||||||
|
env.set('LANG', 'C')
|
||||||
|
yearmonth = run_command('date', '+%B %Y', check:true, capture:true, env: env)
|
||||||
|
ym=yearmonth.stdout().strip()
|
||||||
|
|
||||||
foreach src : man_orgs
|
foreach src : man_orgs
|
||||||
# copy to builddir so org-includes work.
|
|
||||||
configure_file(input: src, output:'@BASENAME@.org', copy:true)
|
|
||||||
|
|
||||||
# meson makes in tricky to use the results of e.g. configure_file
|
# meson makes in tricky to use the results of e.g. configure_file
|
||||||
# in custom_commands..., so this is admittedly a little hacky.
|
# in custom_commands..., so this is admittedly a little hacky.
|
||||||
org = join_paths(meson.current_build_dir(), src)
|
org = join_paths(meson.current_build_dir(), src)
|
||||||
man = '@BASENAME@'
|
man = '@BASENAME@'
|
||||||
|
section = src.substring(-5, -4)
|
||||||
|
|
||||||
|
# we fill in some man-page details:
|
||||||
|
# @SECTION_ID@: the man-page section
|
||||||
|
# @MAN_DATE@: date of the generation (not yet supported by ox-man)
|
||||||
|
conf_data = configuration_data()
|
||||||
|
conf_data.set('SECTION_ID', section)
|
||||||
|
conf_data.set('MAN_DATE', ym)
|
||||||
|
configure_file(input: src, output:'@BASENAME@.org',
|
||||||
|
configuration: conf_data)
|
||||||
|
|
||||||
expr_tmpl = ''.join([
|
expr_tmpl = ''.join([
|
||||||
'(progn',
|
'(progn',
|
||||||
|
@ -77,7 +92,7 @@ foreach src : man_orgs
|
||||||
' (org-export-to-file \'man "@0@"))',
|
' (org-export-to-file \'man "@0@"))',
|
||||||
])
|
])
|
||||||
expr = expr_tmpl.format(org.substring(0,-4))
|
expr = expr_tmpl.format(org.substring(0,-4))
|
||||||
sectiondir = join_paths(mandir, 'man' + src.substring(-5, -4))
|
sectiondir = join_paths(mandir, 'man' + section)
|
||||||
|
|
||||||
custom_target(src + '-to-man',
|
custom_target(src + '-to-man',
|
||||||
build_by_default: true,
|
build_by_default: true,
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU ADD
|
#+TITLE: MU ADD
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU-BOOKMARKS
|
#+TITLE: MU BOOKMARKS
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU CFIND
|
#+TITLE: MU CFIND
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
@ -41,8 +42,7 @@ If you do not specify a search expression, *mu cfind* returns the full list of
|
||||||
contacts. Note, *mu cfind* uses a cache with the e-mail information, which is
|
contacts. Note, *mu cfind* uses a cache with the e-mail information, which is
|
||||||
populated during the indexing process.
|
populated during the indexing process.
|
||||||
|
|
||||||
The regular expressions are Perl-compatible (as per the PCRE-library used by
|
The regular expressions are basic case-insensitive PCRE, see *pcre(3)*.
|
||||||
GRegex).
|
|
||||||
|
|
||||||
* CFIND OPTIONS
|
* CFIND OPTIONS
|
||||||
|
|
||||||
|
@ -113,4 +113,4 @@ otherwise: 1 for a generals error and 2 for 'no matches'.
|
||||||
#+include: "copyright.inc" :minlevel 1
|
#+include: "copyright.inc" :minlevel 1
|
||||||
|
|
||||||
* SEE ALSO
|
* SEE ALSO
|
||||||
*mu(1)*, *mu-index(1)*, *mu-find(1)*
|
*mu(1)*, *mu-index(1)*, *mu-find(1)*, *pcre(3)*
|
||||||
|
|
|
@ -1,313 +0,0 @@
|
||||||
.TH MU-EASY 1 "February 2020" "User Manuals"
|
|
||||||
|
|
||||||
.SH NAME
|
|
||||||
|
|
||||||
mu easy \- a quick introduction to mu
|
|
||||||
|
|
||||||
.SH DESCRIPTION
|
|
||||||
|
|
||||||
\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 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 \fBmu-index\fR(1) or
|
|
||||||
\fBmu-find\fR(1) 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
|
|
||||||
you won't be able to index/search your mail.
|
|
||||||
|
|
||||||
By default, \fBmu\fR uses colorized output when it thinks your terminal is
|
|
||||||
capable of doing so. If you don't like color, you can use the \fB--nocolor\fR
|
|
||||||
command-line option, or set either the \fBMU_NOCOLOR\fR or the \fBNO_COLOR\fR
|
|
||||||
environment variable to non-empty.
|
|
||||||
|
|
||||||
.SH SETTING THINGS UP
|
|
||||||
|
|
||||||
The first time you run the mu commands, you need to initialize it. This is done
|
|
||||||
with the \fBinit\fR command.
|
|
||||||
|
|
||||||
.nf
|
|
||||||
\fB$ mu init\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
This uses the defaults (see \fBmu-init(1)\fR for details on how to change that).
|
|
||||||
|
|
||||||
|
|
||||||
.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(1) man page for more details.
|
|
||||||
|
|
||||||
Normally, \fBmu index\fR 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 \fI.noindex\fR in the directory. When
|
|
||||||
\fBmu\fR sees such a file, it will exclude this directory and its
|
|
||||||
sub-directories from indexing. Also see \fB.noupdate\fR in the \fBmu-index\fR(1)
|
|
||||||
manpage.
|
|
||||||
|
|
||||||
.SH 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 \fBmu-find\fR(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 \fBmu fields\fR command to get information about all possible
|
|
||||||
fields and flags.
|
|
||||||
|
|
||||||
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 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 \fI--fields\fR
|
|
||||||
parameter (try \fBmu fields\fR to see all 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 get
|
|
||||||
a 'summary' of the first lines of the message using the \fI--summary-len\fR
|
|
||||||
option, which will 'summarize' the first \fIn\fR lines of the message:
|
|
||||||
|
|
||||||
.nf
|
|
||||||
\fB$ mu find --summary-len=3 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 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:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find flag:signed prio:high \fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
Get all messages from Jim without an attachment:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find from:jim AND NOT flag:attach\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
Get all messages where Jack is in one of the contact fields:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find contact:jack\fR
|
|
||||||
.fi
|
|
||||||
This uses the special contact: pseudo-field which matches (\fBfrom\fR,
|
|
||||||
\fBto\fR, \fBcc\fR and \fBbcc\fR).
|
|
||||||
|
|
||||||
Get all messages in the Sent Items folder about yoghurt:
|
|
||||||
.nf
|
|
||||||
\fB$mu find maildir:'/Sent Items' yoghurt\fR
|
|
||||||
.fi
|
|
||||||
Note how we need to quote search terms that include spaces.
|
|
||||||
|
|
||||||
|
|
||||||
Get all unread messages where the subject mentions Ångström:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find subject:Ångström flag:unread\fR
|
|
||||||
.fi
|
|
||||||
which is equivalent to:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find subject:angstrom flag:unread\fR
|
|
||||||
.fi
|
|
||||||
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):
|
|
||||||
.nf
|
|
||||||
\fB$ mu find date:20020301..20030831 nightingale flag:unread\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
Get all messages received today:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find date:today..now\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
Get all messages we got in the last two weeks about emacs:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find date:2w..now emacs\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
Another powerful feature (since 0.9.6) are wildcard searches, where you can
|
|
||||||
search for the last \fIn\fR characters in a word. For example, you can search
|
|
||||||
for:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find 'subject:soc*'\fR
|
|
||||||
.fi
|
|
||||||
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:
|
|
||||||
|
|
||||||
.nf
|
|
||||||
\fB$ mu find 'file:pic*'\fR
|
|
||||||
.fi
|
|
||||||
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:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find mime:application/pdf\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
or even:
|
|
||||||
|
|
||||||
Get all messages with image attachments:
|
|
||||||
.nf
|
|
||||||
\fB$ mu find 'mime:image/*'\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
.SH DISPLAYING MESSAGES
|
|
||||||
|
|
||||||
We might also want to display the complete messages instead of the header
|
|
||||||
information. This can be done using \fBmu view\fR 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 \fBl\fRocation) for our first example we
|
|
||||||
can use:
|
|
||||||
|
|
||||||
.nf
|
|
||||||
\fB$ mu find --fields="l" t:julius fruit\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
And we'll get something 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 taste
|
|
||||||
Brought Death into the World, and all our woe,
|
|
||||||
[...]
|
|
||||||
.fi
|
|
||||||
|
|
||||||
.SH FINDING CONTACTS
|
|
||||||
|
|
||||||
While \fBmu find\fR searches for messages, there is also \fBmu cfind\fR to
|
|
||||||
find \fIcontacts\fR, that is, names + addresses. Without any search
|
|
||||||
expression, \fBmu cfind\fR lists all of your contacts.
|
|
||||||
|
|
||||||
.nf
|
|
||||||
\fB$ mu cfind julius\fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
will find all contacts with 'julius' in either name or e-mail address. Note
|
|
||||||
that \fBmu cfind\fR accepts a \fIregular expression\fR.
|
|
||||||
|
|
||||||
\fBmu cfind\fR also supports a \fI--format=\fR-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 \fBmutt\fR
|
|
||||||
address book file, you can use something like:
|
|
||||||
|
|
||||||
.nf
|
|
||||||
\fB$ mu cfind --format=mutt-alias > ~/mutt-aliases \fR
|
|
||||||
.fi
|
|
||||||
|
|
||||||
Then, you can use them in \fBmutt\fR if you add something like \fBsource
|
|
||||||
~/mutt-aliases\fR to your \fImuttrc\fR.
|
|
||||||
|
|
||||||
.SH AUTHOR
|
|
||||||
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
|
||||||
|
|
||||||
.SH "SEE ALSO"
|
|
||||||
.BR mu (1),
|
|
||||||
.BR mu-init (1),
|
|
||||||
.BR mu-index (1),
|
|
||||||
.BR mu-find (1),
|
|
||||||
.BR mu-mfind (1),
|
|
||||||
.BR mu-mkdir (1),
|
|
||||||
.BR mu-view (1),
|
|
||||||
.BR mu-extract (1)
|
|
|
@ -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)*
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU EXTRACT
|
#+TITLE: MU EXTRACT
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
@ -21,10 +22,9 @@ For attachments, the file name used when saving it is the name of the attachment
|
||||||
in the message. If there is no such name, or when saving non-attachment
|
in the message. If there is no such name, or when saving non-attachment
|
||||||
MIME-parts, a name is derived from the message-id of the message.
|
MIME-parts, a name is derived from the message-id of the message.
|
||||||
|
|
||||||
If you specify a pattern (a case-insensitive regular expression) as the second
|
If you specify a regular express pattern as the second argument, all attachments
|
||||||
argument, all attachments with filenames matching that pattern will be
|
with filenames matching that pattern will be extracted. The regular expressions
|
||||||
extracted. The regular expressions are Perl-compatible (as per the
|
are basic PCRE, and are case-sensitive by default; see *pcre(3)* for more details.
|
||||||
PCRE-library).
|
|
||||||
|
|
||||||
Without any options, *mu extract* simply outputs the list of leaf MIME-parts in
|
Without any options, *mu extract* simply outputs the list of leaf MIME-parts in
|
||||||
the message. Only 'leaf' MIME-parts (including RFC822 attachments) are
|
the message. Only 'leaf' MIME-parts (including RFC822 attachments) are
|
||||||
|
|
|
@ -1,4 +1,6 @@
|
||||||
#+title: MU FIELDS
|
#+TITLE: MU FIELDS
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU FIND
|
#+TITLE: MU FIND
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU HELP
|
#+TITLE: MU HELP
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU-INDEX
|
#+TITLE: MU INDEX
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU-INFO
|
#+TITLE: MU INFO
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU-INIT
|
#+TITLE: MU INIT
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
@ -29,9 +30,9 @@ used for filtering in *mu-find(1)*, *mu-cfind(1)* and *mu4e*, e.g. to filter-out
|
||||||
mailing list messages.
|
mailing list messages.
|
||||||
|
|
||||||
=<my-email-address>= can be either a plain e-mail address (such as
|
=<my-email-address>= can be either a plain e-mail address (such as
|
||||||
*foo@example.com*), or a regular-expression (of the 'Basic POSIX' flavor), wrapped
|
*foo@example.com*), or a basic PCRE regular-expression (see *pcre(3)* for details),
|
||||||
in */* (such as =/foo-.*@example\\.com/=). Depending on your shell, the argument may
|
wrapped in */* (such as =/foo-.*@example\\.com/=). Depending on your shell, the
|
||||||
need to b quoted.
|
argument may need to b quoted.
|
||||||
|
|
||||||
#+include: "muhome.inc" :minlevel 2
|
#+include: "muhome.inc" :minlevel 2
|
||||||
|
|
||||||
|
@ -39,4 +40,4 @@ need to b quoted.
|
||||||
|
|
||||||
* SEE ALSO
|
* SEE ALSO
|
||||||
|
|
||||||
*mu-index(1)*, *mu-find(1)*, *mu-cfind(1)*
|
*mu-index(1)*, *mu-find(1)*, *mu-cfind(1)*, *pcre(3)*
|
||||||
|
|
|
@ -1,4 +1,6 @@
|
||||||
#+title: MU MKDIR
|
#+TITLE: MU MKDIR
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU QUERY
|
#+TITLE: MU QUERY
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
@ -82,8 +83,7 @@ Note that a =pure not= - e.g. searching for *not apples* is quite a 'heavy' quer
|
||||||
|
|
||||||
* REGULAR EXPRESSIONS AND WILDCARDS
|
* REGULAR EXPRESSIONS AND WILDCARDS
|
||||||
|
|
||||||
The language supports matching regular expressions that follow ECMAScript; for
|
The language supports matching basic PCRE regular expressions, see *pcre(3*).
|
||||||
details, see http://www.cplusplus.com/reference/regex/ECMAScript/
|
|
||||||
|
|
||||||
Regular expressions are enclosed in *//*. Some examples:
|
Regular expressions are enclosed in *//*. Some examples:
|
||||||
#+begin_example
|
#+begin_example
|
||||||
|
@ -331,4 +331,4 @@ above.
|
||||||
|
|
||||||
* SEE ALSO
|
* SEE ALSO
|
||||||
|
|
||||||
*mu-find(1)*, *mu-fields(1)*
|
*mu-find(1)*, *mu-fields(1), *pcre(3)*
|
||||||
|
|
|
@ -1,4 +1,6 @@
|
||||||
#+title: MU REMOVE
|
#+TITLE: MU REMOVE
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU-SERVER
|
#+TITLE: MU-SERVER
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU VERIFY
|
#+TITLE: MU VERIFY
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU VIEW
|
#+TITLE: MU VIEW
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
#+title: MU
|
#+TITLE: MU
|
||||||
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||||||
|
|
||||||
* NAME
|
* NAME
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue