alx/mu4e
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

mu: update manpages

Browse Source 
Add some notes about the new query parser, and add a mu-query manpage.
This commit is contained in:
djcb
2017-10-25 23:45:38 +03:00
parent 5d3d9e274f
commit c434fdbd86
5 changed files with 352 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
man/Makefile.am
View File

@ -1,4 +1,4 @@
## Copyright (C) 2008-2013 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
## Copyright (C) 2008-2017 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
##
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
@ -26,6 +26,7 @@ dist_man_MANS = \
mu-help.1 \
mu-index.1 \
mu-mkdir.1 \
mu-query.7 \
mu-remove.1 \
mu-server.1 \
mu-script.1 \

88
man/mu-easy.1
View File

@ -6,23 +6,23 @@ 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 mu-index or mu-find
man pages.
\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 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
you won't be able to index/search your mail.
\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 the \fBMU_NOCOLOR\fR environment variable to
non-empty.
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 the \fBMU_NOCOLOR\fR
environment variable to non-empty.
.SH INDEXING YOUR E-MAIL
@ -32,32 +32,35 @@ Before you can search e-mails, you'll first need to index them:
\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.
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
wrongly, 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
details.
\fBmu index\fR guesses the top-level Maildir to do its job; if it
guesses wrongly, 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 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
manpage.
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 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 man page for
details, the syntax of the search parameters and so on. Here, we just give
some examples for common cases.
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 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:
First, let's search for all messages sent to Julius (Caesar) regarding
fruit:
.nf
\fB$ mu find t:julius fruit\fR
@ -69,14 +72,15 @@ This should return something like:
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.
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 (see the \fBmu-find\fR man page for the details):
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

312
man/mu-find.1
View File

@ -10,21 +10,23 @@ mu find \- find e-mail messages in the \fBmu\fR database.
.SH DESCRIPTION
\fBmu find\fR is the \fBmu\fR command for searching e-mail message that
were stored earlier using
\fBmu index(1)\fR.
\fBmu find\fR is the \fBmu\fR command for searching e-mail message
that were stored earlier using \fBmu index(1)\fR.
.SH SEARCHING MAIL
\fBmu find\fR starts a search for messages in the database that match some
search pattern. For example:
\fBmu find\fR starts a search for messages in the database that match
some search pattern. The search patterns are described in detail in
.BR mu-query
.
For example:
.nf
$ mu find subject:snow from:john
$ mu find subject:snow and date:2017..
.fi
would find all messages from John with 'snow' in the subject field, something
like:
would find all messages in 2017 with 'snow' in the subject field, e.g:
.nf
2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow
@ -37,235 +39,11 @@ XML or s-expressions), see the discussion in the \fBOPTIONS\fR-section
below about \fB--format\fR.
The search pattern is taken as a command-line parameter. If the search
parameter consists of multiple parts (as in the example) they are treated as
if there were a logical \fBAND\fR between them.
parameter consists of multiple parts (as in the example) they are
treated as if there were a logical \fBand\fR between them.
\fBmu\fR relies on the Xapian database for its searching capabilities, so it
offers all the search functionality that Xapian offers; for all the details,
see:
\fIhttp://xapian.org/docs/queryparser.html\fR
For details on the possible queries, see
One special feature of \fBmu\fR is that is does not distinguish between
uppercase and lowercase, nor the accented or unaccented versions of
characters. All match. In general, \fBmu\fR tries to be 'eager' in matching,
as filtering out unwanted results is usually preferable over non matching
messages.
A wildcard search is a search where a \fB*\fR matches the last \fIn\fR
character(s) in some string. The string must always start with one or more
characters before the wildcard. \fBmu\fR supports wildcard searches for all
fields except maildirs and paths. To get all mails with a subject containing a
word starting with \fBcom\fR, you can use:
.nf
$ mu find 'subject:com*'
.fi
and get mails about computers, comments, compilation and so on. Note, when
running from the command-line it's important to put the query in quotes,
otherwise the shell would interpret the '*'. It is equally important to
remember that the '*' invokes the wildcard search only when used as the
rightmost character of a search term. Furthermore, it is \fBnot\fR a regular
expression.
The basic way to search a message is to type some words matching it, as you
would do in an internet search engine. For example,
.nf
$ mu find monkey banana
.fi
will find all messages that contain both 'monkey' and 'banana' in either body
or subject or one of the address-fields (to/from/cc).
As mentioned, matching is case-insensitive and accent-insensitive; thus
.nf
$ mu find Mönkey BÄNAÑå
.fi
yields the same results as the example above.
\fBmu\fR also recognizes prefixes for specific fields in a messages; for
example:
.nf
$ mu find subject:penguin
.fi
to find messages with have the word \fBpenguin\fR in the subject field. You
can abbreviate \fBsubject:\fR to just \fBs:\fR. Here is the full table of the
search fields and their abbreviations:
.nf
cc,c Cc (carbon-copy) recipient(s)
bcc,h Bcc (blind-carbon-copy) recipient(s)
from,f Message sender
to,t To: recipient(s)
subject,s Message subject
body,b Message body
maildir,m Maildir
msgid,i Message-ID
prio,p Message priority ('low', 'normal' or 'high')
flag,g Message Flags
date,d Date-Range
size,z Message size
embed,e Search inside embedded text parts (messages, attachments)
file,j Attachment filename
mime,y MIME-type of one or more message parts
tag,x Tags for the message (\fIX-Label\fR and/or \fIX-Keywords\fR)
list,v Mailing list (e.g. the List-Id value)
.fi
There are also the special fields \fBcontact\fR, which matches all
contact-fields (\fBfrom\fR, \fBto\fR, \fBcc\fR and \fBbcc\fR), and
\fBrecip\fR, which matches all recipient-fields (\fBto\fR, \fBcc\fR and
\fBbcc\fR).
The meaning of most of the above fields should be clear, but some require some
extra discussion. First, the message flags field describes certain properties
of the message, as listed in the following table:
.nf
d,draft Draft Message
f,flagged Flagged
n,new New message (in new/ Maildir)
p,passed Passed ('Handled')
r,replied Replied
s,seen Seen
t,trashed Marked for deletion
a,attach Has attachment
z,signed Signed message
x,encrypted Encrypted message
l,list Mailing-list message
.fi
Using this, we can search e.g. for all signed messages that have an
attachment:
.nf
$ mu find flag:signed flag:attach
.fi
Encrypted messages may be signed as well, but this is only visible after
decrypting, and thus, is invisible to \fBmu\fR.
The message-priority has three possible values: low, normal or high. We can
match them using \fBprio:\fR - for example, to get all high-priority messages
with a subject containing some bird:
.nf
$ mu find prio:high subject:nightingale
.fi
The Maildir field describes the directory path starting \fBafter\fR the
Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part. So for
example, if there's a message with the file name
\fI~/Maildir/lists/running/cur/1234.213:2,\fR, you could find it (and all the
other messages in the same maildir) with:
.nf
$ mu find maildir:/lists/running
.fi
Note the starting '/'. If you want to match mails in the 'root' maildir, you
can do with a single '/':
.nf
$ mu find maildir:/
.fi
(and of course you can use the \fBm:\fR shortcut instead of \fBmaildir:\fR)
The \fBdate:\fR (or \fBd:\fR) search parameter is 'special' in the fact that
it takes a range of dates. For now, these dates are in ISO 8601 format
(YYYYMMDDHHMM); you can leave out the right part, and mu will add the rest,
depending on whether this is the beginning or end of the date interval. For
example, for the beginning of the interval "201012" would be interpreted as
"20101201010000", or December 1, 2010 at 00:00, while for the end of the
interval, this would be interpreted as "20101231122359", or December 31, 2010
at 23:59. If you omit the left part completely, the beginning date is
assumed to be January 1, year 0 at 00:00. Likewise, if you omit the
right part, the end data is assumed to be to the last second of the
year 9999.
To get all messages between (inclusive) the 5th of May 2009 and the 2nd of
June 2010, you could use:
.nf
$ mu find date:20090505..20100602
.fi
Non-numeric characters are ignored, so the following is equivalent but more
readable:
.nf
$ mu find date:2009-05-05..2010-06-02
.fi
Precision is up to the minute and 24-hour notation for times is used, so
another example would be:
.nf
$ mu find date:2009-05-05/12:23..2010-06-02/17:18
.fi
\fBmu\fR also understand relative dates, in the form of a positive number
followed by h (hour), d (day), w (week), m (30 days) or y (365 days). Some
examples to explain this:
.nf
5h five hours in the past
2w two weeks in the past
3m three times 30 days in the past
1y 365 days in the past
.fi
Using this notation, you can for example match messages between two and three
weeks old:
.nf
$ mu find date:3w..2w
.fi
There are some special keywords for dates, namely 'now', meaning the
present moment and 'today' for the beginning of today. So to get all messages
sent or received today, you could use:
.nf
$ mu find date:today..now
.fi
The \fBsize\fR or \fBz\fR allows you to match \fIsize ranges\fR -- that is,
match messages that have a byte-size within a certain range. Units (B (for
bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes) are supported). For
example, to get all messages between 10Kb and 2Mb (assuming SI units), you
could use:
.nf
$ mu find size:10K..2M
.fi
It's important to remember that if a search term includes spaces, you should
\fIquote\fr those parts. Thus, when we look at the following examples:
.nf
$ mu find maildir:/Sent Items yoghurt
$ mu find maildir:'/Sent Items' yoghurt
.fi
The first query searches for messages in the \fI/Sent\fR maildir matching
\fIItems\fR and \fIyoghurt\fR, while the second query searches the \fI/Sent
Items\fR maildir searching for messages matching \fIyoghurt\fR.
You can match \fIall\fR messages using "" (or ''):
.nf
$ mu find ""
.fi
.SH OPTIONS
@ -468,68 +246,6 @@ The algorithm used for determining the threads is based on Jamie Zawinksi's
description:
.BR http://www.jwz.org/doc/threading.html
.SS Example queries
Here are some simple examples of \fBmu\fR search queries; you can make many
more complicated queries using various logical operators, parentheses and so
on, but in the author's experience, it's usually faster to find a message with
a simple query just searching for some words.
Find all messages with both 'bee' and 'bird' (in any field)
.nf
$ mu find bee AND bird
.fi
or shorter, because \fBAND\fR is implied:
.nf
$ mu find bee bird
.fi
Find all messages with either Frodo or Sam:
.nf
$ mu find 'Frodo OR Sam'
.fi
Find all messages with the 'wombat' as subject, and 'capibara' anywhere:
.nf
$ mu find subject:wombat capibara
.fi
Find all messages in the 'Archive' folder from Fred:
.nf
$ mu find from:fred maildir:/Archive
.fi
Find all unread messages with attachments:
.nf
$ mu find flag:attach flag:unread
.fi
Find all messages with PDF-attachments:
.nf
$ mu find mime:application/pdf
.fi
Find all messages with attached images:
.nf
$ mu find 'mime:image/*'
.fi
Note[1]: the argument needs to be quoted, or the shell will interpret the '*'
Note[2]: the '*' wild card can only be used as the last (rightmost) part of a
search term.
Note[3]: non-word characters (such as € or ☺) are ignore in queries; you
cannot search for them.
.SS Integrating mu find with mail clients
@ -666,3 +382,5 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.BR mu(1)
.BR mu-index(1)
.BR mu-query(7)

287
man/mu-query.7 Normal file
View File

@ -0,0 +1,287 @@
.TH MU QUERY 7 "25 October 2017" "User Manuals"
.SH NAME
mu query language \- a language for finding messages in a \fBmu\fR database.
.SH DESCRIPTION
The mu query language is a language that allows for searching in a
\fBmu\fR database and is used by \fBmu find\fR and \fBmu4e\fR to find
messages. The language is similar to the default query-parser that
\fBmu\fR's underlying Xapian database uses, but is a indepedent
\fBmu\fR-specific implementation.
In this manpage, we give a structured but informal overview of the
query language and provide examples.
.de EX1
.nf
.RS
..
.de EX2
.RE
.fi
..
.SH TERMS
The basic building blocks are \fBterms\fR; these are just normal
alphanumerical strings like 'banana' or 'hello' or prefixed with a
field-name.
Some example queries:
.EX1
vacation
subject:capybara
maildir:/inbox
.EX2
Terms without an explicit field-prefix, (like 'vacation' above) are
interpreted as something like:
.EX1
to:vacation or subject:vacation or body:vacation or ...
.EX2
The language is case-insensitive for terms and attempts to flatten any
diactrics, so \fIangtrom\fR matches \fIÅngström\fR.
.SH LOGICAL OPERATORS
We can combine terms with logical operators -- binary ones: \fBand\fR,
\fBor\fR, \fBxor\fR and the unary \fBnot\fR, with conventional
precedence and association, and case-insensitive. You can also group
things with \fB(\fR and \fB)\fR, so you can do things like:
.EX1
(subject:beethoven or subject:bach) and not body:elvis
.EX2
If you do not explicitly specify an operator between terms, \fBand\fR
is implied, so the queries
.EX1
subject:chip subject:dale
.EX2
.EX1
subject:chip AND subject:dale
.EX2
are equivalent. For readability, we recommend the second version.
Note that a \fIpure not\fR - e.g. searching for \fBnot apples\fR is
quite a 'heavy' query.
.SH REGULAR EXPRESSIONS AND WILDCARDS
The language supports matching regular expressions that follow
ECMAScript; for details, see
.BR http://www.cplusplus.com/reference/regex/ECMAScript/
Regular expressions must be enclosed in \fB//\fR. Some examples:
.EX1
subject:/h.llo/ # match hallo, hello, ...
subject:/
.EX2
Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the
latter matches messages in the '/foo' maildir, while the latter
matches all messages in all maildirs that match 'foo', such
as '/foo', '/bar/cuux/foo', '/fooishbar' etc.
Wildcards are an older mechanism for matching where a term with a
rightmost \fB*\fR matches any term that starts with the part before
the \fB*\fR; they are supported for backward compatibility and
\fBmu\fR translates them to regular expressions internally; e.g.
\fBfoo*\fR is equivalent to \fB/foo.*/\fR.
Wildcards and regular expressions can be quite heavy to execute.
.SH FIELDS
We already saw a number of search fields, such as \fBsubject:\fR and
\fBbody:\fR. Here is the full table, a shortcut character (so
\fBsubject:october\fR can be written as \fBs:october\fR) and a
description.
.nf
cc,c Cc (carbon-copy) recipient(s)
bcc,h Bcc (blind-carbon-copy) recipient(s)
from,f Message sender
to,t To: recipient(s)
subject,s Message subject
body,b Message body
maildir,m Maildir
msgid,i Message-ID
prio,p Message priority ('low', 'normal' or 'high')
flag,g Message Flags
date,d Date range
size,z Message size range
embed,e Search inside embedded text parts (messages, attachments)
file,j Attachment filename
mime,y MIME-type of one or more message parts
tag,x Tags for the message (\fIX-Label\fR and/or \fIX-Keywords\fR)
list,v Mailing list (e.g. the List-Id value)
.fi
There are also the special fields \fBcontact\fR, which matches all
contact-fields (\fBfrom\fR, \fBto\fR, \fBcc\fR and \fBbcc\fR), and
\fBrecip\fR, which matches all recipient-fields (\fBto\fR, \fBcc\fR
and \fBbcc\fR).
.SH DATE RANGES
The \fBdate:\fR field takes a date-range, expressed as the lower and
upper bound, separated by \fB..\fR. Either lower or upper (but not
both) can be omitted to create an open range.
Dates are expressed in local time and using ISO-8601 format
(YYYY-MM-DD HH:MM:SS); you can leave out the right part, and \fBmu\fR
adds the rest, depending on whether this is the beginning or end of
the range (e.g., as a lower bound, '2015' would be interpreted as the
start of that year; as an upper bound as the end of the year).
You can use '/' , '.', '-' and 'T' to make dates more human readable.
Some examples:
.EX1
date:20170505..20170602
date:2017-05-05..2017-06-02
date:..2017-10-01T12:00
date:2015-06-01..
date:2016..2016
.EX2
You can also use the special 'dates' \fBnow\fR and \fBtoday\fR:
.EX1
date:20170505..now
date:today..
.EX2
Finally, you can use relative 'ago' times which express some time
before now and consist of a number followed by a unit, with units
\fBs\fR for seconds, \fBM\fR for minutes, \fBh\fR for hours, \fBd\fR
for days, \fBw\fR for week, \fBm\fR for months and \fBy\fR for years.
Some examples:
.EX1
date:3m..
e:2017.01.01..5w
.EX2
.SH SIZE RANGES
The \fBsize\fR or \fBz\fR field allows you to match \fIsize ranges\fR
-- that is, match messages that have a byte-size within a certain
range. Units (b (for bytes), K (for 1000 bytes) and M (for 1000 * 1000
bytes) are supported). Some examples:
.EX1
size:10k..2m
size:10m..
.EX2
.SH FLAG FIELDS
The \fBflag\fR/\fBg\fR field allows you to match message flags. The
following fields are available:
.nf
d,draft Draft Message
f,flagged Flagged
n,new New message (in new/ Maildir)
p,passed Passed ('Handled')
r,replied Replied
s,seen Seen
t,trashed Marked for deletion
a,attach Has attachment
z,signed Signed message
x,encrypted Encrypted message
l,list Mailing-list message
.fi
Some examples:
.EX1
flag:attach
flag:replied
g:x
.EX2
Encrypted messages may be signed as well, but this is only visible
after decrypting and thus, invisible to \fBmu\fR.
.SH PRIORITY FIELD
The message priority field (\fBprio:\fR) has three possible values:
\fBlow\fR, \fBnormal\fR or \fBhigh\fR. For instance, to match
high-priority messages:
.EX1
prio:high
.EX2
.SH MAILDIR
The Maildir field describes the directory path starting \fBafter\fR
the Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part.
So for example, if there's a message with the file name
\fI~/Maildir/lists/running/cur/1234.213:2,\fR, you could find it (and
all the other messages in the same maildir) with:
.EX1
maildir:/lists/running
.EX2
Note the starting '/'. If you want to match mails in the 'root'
maildir, you can do with a single '/':
.EX1
maildir:/
.EX2
.SH MORE EXAMPLES
Here are some simple examples of \fBmu\fR queries; you can make many
more complicated queries using various logical operators, parentheses
and so on, but in the author's experience, it's usually faster to find
a message with a simple query just searching for some words.
Find all messages with both 'bee' and 'bird' (in any field)
.EX1
bee AND bird
.EX2
Find all messages with either Frodo or Sam:
.EX1
Frodo OR Sam
.EX2
Find all messages with the 'wombat' as subject, and 'capibara' anywhere:
.EX1
subject:wombat and capibara
.EX2
Find all messages in the 'Archive' folder from Fred:
.EX1
from:fred and maildir:/Archive
.EX2
Find all unread messages with attachments:
.EX1
flag:attach and flag:unread
.EX2
Find all messages with PDF-attachments:
.EX1
mime:application/pdf
.EX2
Find all messages with attached images:
.EX1
mime:image/*
.EX2
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu-find(1)

11
man/mu.1
View File

@ -235,12 +235,5 @@ Please report bugs if you find them:
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu-index(1)
.BR mu-find(1)
.BR mu-cfind(1)
.BR mu-mkdir(1)
.BR mu-view(1)
.BR mu-extract(1)
.BR mu-easy(1)
.BR mu-bookmarks(5)
mu-index(1) mu-find(1) mu-cfind(1) mu-mkdir(1) mu-view(1)
mu-extract(1) mu-easy(1) mu-bookmarks(5) mu-query(7)