mu: update manpages
Add some notes about the new query parser, and add a mu-query manpage.
This commit is contained in:
@ -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
|
## 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
|
## it under the terms of the GNU General Public License as published by
|
||||||
@ -26,6 +26,7 @@ dist_man_MANS = \
|
|||||||
mu-help.1 \
|
mu-help.1 \
|
||||||
mu-index.1 \
|
mu-index.1 \
|
||||||
mu-mkdir.1 \
|
mu-mkdir.1 \
|
||||||
|
mu-query.7 \
|
||||||
mu-remove.1 \
|
mu-remove.1 \
|
||||||
mu-server.1 \
|
mu-server.1 \
|
||||||
mu-script.1 \
|
mu-script.1 \
|
||||||
|
|||||||
@ -6,23 +6,23 @@ mu easy \- a quick introduction to mu
|
|||||||
|
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
|
||||||
\fBmu\fR is a set of tools for dealing with e-mail messages in Maildirs. There
|
\fBmu\fR is a set of tools for dealing with e-mail messages in
|
||||||
are many options, which are all described in the man pages for the various
|
Maildirs. There are many options, which are all described in the man
|
||||||
sub-commands. This man pages jumps over all of the details and gives examples
|
pages for the various sub-commands. This man pages jumps over all of
|
||||||
of some common use cases. If the use cases described here do not precisely do
|
the details and gives examples of some common use cases. If the use
|
||||||
what you want, please check the more extensive information in the man page
|
cases described here do not precisely do what you want, please check
|
||||||
about the sub-command you are using -- for example, the mu-index or mu-find
|
the more extensive information in the man page about the sub-command
|
||||||
man pages.
|
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
|
\fBNOTE\fR: the \fBindex\fR command (and therefore, the ones that
|
||||||
that, such as \fBfind\fR), require that you store your mail in the
|
depend on that, such as \fBfind\fR), require that you store your mail
|
||||||
Maildir-format. If you don't do so, you can still use the other commands, but
|
in the Maildir-format. If you don't do so, you can still use the other
|
||||||
you won't be able to index/search your mail.
|
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
|
By default, \fBmu\fR uses colorized output when it thinks your
|
||||||
capable of doing so. If you don't like color, you can use the \fB--nocolor\fR
|
terminal is capable of doing so. If you don't like color, you can use
|
||||||
command-line option, or set the \fBMU_NOCOLOR\fR environment variable to
|
the \fB--nocolor\fR command-line option, or set the \fBMU_NOCOLOR\fR
|
||||||
non-empty.
|
environment variable to non-empty.
|
||||||
|
|
||||||
.SH INDEXING YOUR E-MAIL
|
.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
|
\fB$ mu index\fR
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
The process can take a few minutes, depending on the amount of mail you have,
|
The process can take a few minutes, depending on the amount of mail
|
||||||
the speed of your computer, hard drive etc. Usually, indexing should be able to
|
you have, the speed of your computer, hard drive etc. Usually,
|
||||||
reach a speed of a few hundred messages per second.
|
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
|
\fBmu index\fR guesses the top-level Maildir to do its job; if it
|
||||||
wrongly, you can use the \fI--maildir\fR option to specify the top-level
|
guesses wrongly, you can use the \fI--maildir\fR option to specify the
|
||||||
directory that should be processed. See the \fBmu-index\fR man page for more
|
top-level directory that should be processed. See the \fBmu-index\fR
|
||||||
details.
|
man page for more details.
|
||||||
|
|
||||||
Normally, \fBmu index\fR visits all the directories under the top-level
|
Normally, \fBmu index\fR visits all the directories under the
|
||||||
Maildir; however, you can exclude certain directories (say, the 'trash'
|
top-level Maildir; however, you can exclude certain directories (say,
|
||||||
or 'spam' folders) by creating a file called \fI.noindex\fR in the directory.
|
the 'trash' or 'spam' folders) by creating a file called
|
||||||
When \fBmu\fR sees such a file, it will exclude this directory and its
|
\fI.noindex\fR in the directory. When \fBmu\fR sees such a file, it
|
||||||
sub-directories from indexing. Also see \fB.noupdate\fR in the \fBmu-index\fR
|
will exclude this directory and its sub-directories from indexing.
|
||||||
manpage.
|
Also see \fB.noupdate\fR in the \fBmu-index\fR manpage.
|
||||||
|
|
||||||
.SH SEARCHING YOUR E-MAIL
|
.SH SEARCHING YOUR E-MAIL
|
||||||
|
|
||||||
After you have indexed your mail, you can start searching it. By default, the
|
After you have indexed your mail, you can start searching it. By
|
||||||
search results are printed on standard output. Alternatively, the output can
|
default, the search results are printed on standard output.
|
||||||
take the form of Maildir with symbolic links to the found messages. This
|
Alternatively, the output can take the form of Maildir with symbolic
|
||||||
enables integration with e-mail clients; see the \fBmu-find\fR man page for
|
links to the found messages. This enables integration with e-mail
|
||||||
details, the syntax of the search parameters and so on. Here, we just give
|
clients; see the \fBmu-find\fR man page for details, the syntax of the
|
||||||
some examples for common cases.
|
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
|
.nf
|
||||||
\fB$ mu find t:julius fruit\fR
|
\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
|
2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
This means there is a message to 'julius' with 'fruit' somewhere in the
|
This means there is a message to 'julius' with 'fruit' somewhere in
|
||||||
message. In this case, it's a message from John Milton. Note that the date
|
the message. In this case, it's a message from John Milton. Note that
|
||||||
format depends on your the language/locale you are using.
|
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
|
How do we know that the message was sent to Julius Caesar? Well, it's
|
||||||
visible from the results above, because the default fields that are shown are
|
not visible from the results above, because the default fields that
|
||||||
date/sender/subject. However, we can change this using the \fI--fields\fR
|
are shown are date/sender/subject. However, we can change this using
|
||||||
parameter (see the \fBmu-find\fR man page for the details):
|
the \fI--fields\fR parameter (see the \fBmu-find\fR man page for the
|
||||||
|
details):
|
||||||
|
|
||||||
.nf
|
.nf
|
||||||
\fB$ mu find --fields="t s" t:julius fruit\fR
|
\fB$ mu find --fields="t s" t:julius fruit\fR
|
||||||
|
|||||||
312
man/mu-find.1
312
man/mu-find.1
@ -10,21 +10,23 @@ mu find \- find e-mail messages in the \fBmu\fR database.
|
|||||||
|
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
|
|
||||||
\fBmu find\fR is the \fBmu\fR command for searching e-mail message that
|
\fBmu find\fR is the \fBmu\fR command for searching e-mail message
|
||||||
were stored earlier using
|
that were stored earlier using \fBmu index(1)\fR.
|
||||||
\fBmu index(1)\fR.
|
|
||||||
|
|
||||||
.SH SEARCHING MAIL
|
.SH SEARCHING MAIL
|
||||||
|
|
||||||
\fBmu find\fR starts a search for messages in the database that match some
|
\fBmu find\fR starts a search for messages in the database that match
|
||||||
search pattern. For example:
|
some search pattern. The search patterns are described in detail in
|
||||||
|
.BR mu-query
|
||||||
|
.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
.nf
|
.nf
|
||||||
$ mu find subject:snow from:john
|
$ mu find subject:snow and date:2017..
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
would find all messages from John with 'snow' in the subject field, something
|
would find all messages in 2017 with 'snow' in the subject field, e.g:
|
||||||
like:
|
|
||||||
|
|
||||||
.nf
|
.nf
|
||||||
2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow
|
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.
|
below about \fB--format\fR.
|
||||||
|
|
||||||
The search pattern is taken as a command-line parameter. If the search
|
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
|
parameter consists of multiple parts (as in the example) they are
|
||||||
if there were a logical \fBAND\fR between them.
|
treated as if there were a logical \fBand\fR between them.
|
||||||
|
|
||||||
\fBmu\fR relies on the Xapian database for its searching capabilities, so it
|
For details on the possible queries, see
|
||||||
offers all the search functionality that Xapian offers; for all the details,
|
|
||||||
see:
|
|
||||||
\fIhttp://xapian.org/docs/queryparser.html\fR
|
|
||||||
|
|
||||||
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
|
.SH OPTIONS
|
||||||
@ -468,68 +246,6 @@ The algorithm used for determining the threads is based on Jamie Zawinksi's
|
|||||||
description:
|
description:
|
||||||
.BR http://www.jwz.org/doc/threading.html
|
.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
|
.SS Integrating mu find with mail clients
|
||||||
|
|
||||||
@ -666,3 +382,5 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
|||||||
|
|
||||||
.BR mu(1)
|
.BR mu(1)
|
||||||
.BR mu-index(1)
|
.BR mu-index(1)
|
||||||
|
.BR mu-query(7)
|
||||||
|
|
||||||
|
|||||||
287
man/mu-query.7
Normal file
287
man/mu-query.7
Normal 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
11
man/mu.1
@ -235,12 +235,5 @@ Please report bugs if you find them:
|
|||||||
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
||||||
|
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
|
mu-index(1) mu-find(1) mu-cfind(1) mu-mkdir(1) mu-view(1)
|
||||||
.BR mu-index(1)
|
mu-extract(1) mu-easy(1) mu-bookmarks(5) mu-query(7)
|
||||||
.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)
|
|
||||||
|
|||||||
Reference in New Issue
Block a user