mirror of https://github.com/djcb/mu.git
339 lines
10 KiB
Groff
339 lines
10 KiB
Groff
.TH MU FIND 1 "29 April 2022" "User Manuals"
|
|
|
|
.SH NAME
|
|
|
|
mu find \- find e-mail messages in the \fBmu\fR database.
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B mu find [options] <search expression>
|
|
|
|
.SH DESCRIPTION
|
|
|
|
\fBmu find\fR is the \fBmu\fR command for searching e-mail message
|
|
that were stored earlier using \fBmu index\fR(1).
|
|
|
|
.SH SEARCHING MAIL
|
|
|
|
\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 (7).
|
|
.
|
|
|
|
For example:
|
|
|
|
.nf
|
|
$ mu find subject:snow and date:2009..
|
|
.fi
|
|
|
|
would find all messages in 2009 with 'snow' in the subject field, e.g:
|
|
|
|
.nf
|
|
2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow
|
|
2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow
|
|
.fi
|
|
|
|
Note, this the default, plain-text output, which is the default, so you don't
|
|
have to use \fB--format=plain\fR. For other types of output (such as symlinks,
|
|
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.
|
|
|
|
For details on the possible queries, see
|
|
.BR mu-query (7).
|
|
|
|
.SH OPTIONS
|
|
|
|
Note, some of the important options are described in the \fBmu\fR(1) man-page
|
|
and not here, as they apply to multiple mu-commands.
|
|
|
|
The \fBfind\fR-command has various options that influence the way \fBmu\fR
|
|
displays the results. If you don't specify anything, the defaults are
|
|
\fI\-\-fields="d f s"\fR, \fI\-\-sortfield=date\fR and \fI\-\-reverse\fR.
|
|
|
|
.TP
|
|
\fB\-f\fR, \fB\-\-fields\fR=\fI<fields>\fR
|
|
specifies a string that determines which fields are shown in the output. This
|
|
string consists of a number of characters (such as 's' for subject or 'f' for
|
|
from), which will replace with the actual field in the output. Fields that are
|
|
not known will be output as-is, allowing for some simple formatting.
|
|
|
|
For example:
|
|
|
|
.nf
|
|
$ mu find subject:snow --fields "d f s"
|
|
.fi
|
|
|
|
would list the date, subject and sender of all messages with 'snow' in the
|
|
their subject.
|
|
|
|
The table of replacement characters is superset of the list mentions for
|
|
search parameters, such as:
|
|
.nf
|
|
t \fBt\fRo: recipient
|
|
d Sent \fBd\fRate of the message
|
|
f Message sender (\fBf\fRrom:)
|
|
g Message flags (fla\fBg\fRs)
|
|
l Full path to the message (\fBl\fRocation)
|
|
s Message \fBs\fRubject
|
|
i Message-\fBi\fRd
|
|
m \fBm\fRaildir
|
|
.fi
|
|
|
|
For the complete, up-to-date list, see:
|
|
.BR mu-fields(1)
|
|
|
|
The message flags are described in \fBmu-query\fR(7). As an example, a
|
|
message which is 'seen', has an attachment and is signed would
|
|
have 'asz' as its corresponding output string, while an encrypted new
|
|
message would have 'nx'.
|
|
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-sortfield\fR \fR=\fI<field>\fR and \fB\-z\fR,
|
|
\fB\-\-reverse\fR specifies the field to sort the search results by, and the
|
|
direction (i.e., 'reverse' means that the sort should be reverted - Z-A). Examples include:
|
|
|
|
.nf
|
|
cc,c Cc (carbon-copy) recipient(s)
|
|
date,d Message sent date
|
|
from,f Message sender
|
|
maildir,m Maildir
|
|
msgid,i Message id
|
|
prio,p Nessage priority
|
|
subject,s Message subject
|
|
to,t To:-recipient(s)
|
|
.fi
|
|
|
|
For the complete, up-to-date list, see:
|
|
.BR mu-fields(1)
|
|
|
|
Thus, for example, to sort messages by date, you could specify:
|
|
|
|
.nf
|
|
$ mu find fahrrad --fields "d f s" --sortfield=date --reverse
|
|
.fi
|
|
|
|
Note, if you specify a sortfield, by default, messages are sorted in reverse
|
|
(descending) order (e.g., from lowest to highest). This is usually a good
|
|
choice, but for dates it may be more useful to sort in the opposite direction.
|
|
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-maxnum=<number>\fR
|
|
If > 0, display maximally that number of entries. If not specified, all matching entries are displayed.
|
|
|
|
.TP
|
|
\fB\-\-summary-len=<number>\fR
|
|
If > 0, use that number of lines of the message to provide a summary.
|
|
|
|
.TP
|
|
\fB\-\-format\fR=\fIplain|links|xquery|xml|sexp\fR
|
|
output results in the specified format.
|
|
|
|
The default is \fBplain\fR, i.e normal output with one line per message.
|
|
|
|
\fBlinks\fR outputs the results as a maildir with symbolic links to the found
|
|
messages. This enables easy integration with mail-clients (see below for more
|
|
information).
|
|
|
|
\fBxml\fR formats the search results as XML.
|
|
|
|
\fBsexp\fR formats the search results as an s-expression as used in Lisp
|
|
programming environments.
|
|
|
|
\fBxquery\fR shows the Xapian query corresponding to your search terms. This
|
|
is meant for for debugging purposes.
|
|
|
|
.TP
|
|
\fB\-\-linksdir\fR \fR=\fI<dir>\fR and \fB\-c\fR, \fB\-\-clearlinks\fR
|
|
output the results as a maildir with symbolic links to the found
|
|
messages. This enables easy integration with mail-clients (see below
|
|
for more information). \fBmu\fR will create the maildir if it does not
|
|
exist yet.
|
|
|
|
If you specify \fB\-\-clearlinks\fR, all existing symlinks will be
|
|
cleared from the target directories; this allows for re-use of the
|
|
same maildir. However, this option will delete any symlink it finds,
|
|
so be careful.
|
|
|
|
.nf
|
|
$ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks
|
|
.fi
|
|
|
|
will store links to found messages in \fI~/Maildir/search\fR. If the directory
|
|
does not exist yet, it will be created.
|
|
|
|
Note: when \fBmu\fR creates a Maildir for these links, it automatically
|
|
inserts a \fI.noindex\fR file, to exclude the directory from \fBmu
|
|
index\fR.
|
|
|
|
.TP
|
|
\fB\-\-after=\fR\fI<timestamp>\fR only show messages whose message files were
|
|
last modified (\fBmtime\fR) after \fI<timestamp>\fR. \fI<timestamp>\fR is a
|
|
UNIX \fBtime_t\fR value, the number of seconds since 1970-01-01 (in UTC).
|
|
|
|
From the command line, you can use the \fBdate\fR command to get this
|
|
value. For example, only consider messages modified (or created) in the last 5
|
|
minutes, you could specify
|
|
.nf
|
|
--after=`date +%s --date='5 min ago'`
|
|
.fi
|
|
This is assuming the GNU \fBdate\fR command.
|
|
|
|
|
|
.TP
|
|
\fB\-\-exec\fR=\fI<command>\fR
|
|
the \fB\-\-exec\fR command causes the \fIcommand\fR to be executed on each
|
|
matched message; for example, to see the raw text of all messages
|
|
matching 'milkshake', you could use:
|
|
.nf
|
|
$ mu find milkshake --exec='less'
|
|
.fi
|
|
which is roughly equivalent to:
|
|
.nf
|
|
$ mu find milkshake --fields="l" | xargs less
|
|
.fi
|
|
|
|
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-bookmark\fR=\fI<bookmark>\fR
|
|
use a bookmarked search query. Using this option, a query from your bookmark
|
|
file will be prepended to other search queries. See \fBmu-bookmarks\fR(1) for the
|
|
details of the bookmarks file.
|
|
|
|
|
|
.TP
|
|
\fB\-\-skip\-dups\fR,\fB-u\fR whenever there are multiple messages with the
|
|
same name, only show the first one. This is useful if you have copies of the
|
|
same message, which is a common occurrence when using e.g. Gmail together with
|
|
\fBofflineimap\fR.
|
|
|
|
.TP
|
|
\fB\-\-include\-related\fR,\fB-r\fR also include messages being referred to by
|
|
the matched messages -- i.e.. include messages that are part of the same
|
|
message thread as some matched messages. This is useful if you want
|
|
Gmail-style 'conversations'. Note, finding these related messages make
|
|
searches slower.
|
|
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-threads\fR show messages in a 'threaded' format --
|
|
that is, with indentation and arrows showing the conversation threads
|
|
in the list of matching messages. When using this, sorting is
|
|
chronological (by date), based on the newest message in a thread.
|
|
|
|
Messages in the threaded list are indented based on the depth in the
|
|
discussion, and are prefix with a kind of arrow with thread-related
|
|
information about the message, as in the following table:
|
|
|
|
.nf
|
|
| | normal | orphan | duplicate |
|
|
|-------------+--------+--------+-----------|
|
|
| first child | `-> | `*> | `=> |
|
|
| other | |-> | |*> | |=> |
|
|
.fi
|
|
|
|
Here, an 'orphan' is a message without a parent message (in the list of
|
|
matches), and a duplicate is a message whose message-id was already seen
|
|
before; not this may not really be the same message, if the message-id was
|
|
copied.
|
|
|
|
The algorithm used for determining the threads is based on Jamie Zawinksi's
|
|
description:
|
|
.BR http://www.jwz.org/doc/threading.html
|
|
|
|
|
|
.SS Integrating mu find with mail clients
|
|
|
|
.TP
|
|
|
|
\fBmutt\fR
|
|
|
|
For \fBmutt\fR you can use the following in your \fImuttrc\fR; pressing the F8
|
|
key will start a search, and F9 will take you to the results.
|
|
|
|
.nf
|
|
# mutt macros for mu
|
|
macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\
|
|
"mu find"
|
|
macro index <F9> "<change-folder-readonly>~/Maildir/search" \\
|
|
"mu find results"
|
|
.fi
|
|
|
|
|
|
.TP
|
|
|
|
\fBWanderlust\fR
|
|
|
|
\fBSam B\fR suggested the following on the \fBmu\fR-mailing list. First add
|
|
the following to your Wanderlust configuration file:
|
|
|
|
.nf
|
|
(require 'elmo-search)
|
|
(elmo-search-register-engine
|
|
'mu 'local-file
|
|
:prog "/usr/local/bin/mu" ;; or wherever you've installed it
|
|
:args '("find" pattern "--fields" "l") :charset 'utf-8)
|
|
|
|
(setq elmo-search-default-engine 'mu)
|
|
;; for when you type "g" in folder or summary.
|
|
(setq wl-default-spec "[")
|
|
.fi
|
|
|
|
Now, you can search using the \fBg\fR key binding; you can also create
|
|
permanent virtual folders when the messages matching some expression by adding
|
|
something like the following to your \fIfolders\fR file.
|
|
|
|
.nf
|
|
VFolders {
|
|
[date:today..now]!mu "Today"
|
|
|
|
[size:1m..100m]!mu "Big"
|
|
|
|
[flag:unread]!mu "Unread"
|
|
}
|
|
.fi
|
|
|
|
After restarting Wanderlust, the virtual folders should appear.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
\fBmu find\fR returns 0 upon successful completion; if the search was
|
|
performed, there needs to be a least one match. Anything else leads to a
|
|
non-zero return value, for example:
|
|
|
|
.nf
|
|
| code | meaning |
|
|
|------+--------------------------------|
|
|
| 0 | ok |
|
|
| 1 | general error |
|
|
| 4 | no matches (for 'mu find') |
|
|
.fi
|
|
|
|
|
|
.SH ENCODING
|
|
|
|
\fBmu find\fR output is encoded according the locale for \fI--format=plain\fR
|
|
(the default), and UTF-8 for all other formats (\fIsexp\fR,
|
|
\fIxml\fR).
|
|
|
|
|
|
.SH BUGS
|
|
|
|
Please report bugs if you find them:
|
|
.BR https://github.com/djcb/mu/issues
|
|
If you have specific messages which are not matched correctly, please attach
|
|
them (appropriately censored if needed).
|
|
|
|
.SH AUTHOR
|
|
|
|
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR mu (1),
|
|
.BR mu-index (1),
|
|
.BR mu-query (7)
|
|
.BR mu-fields (1)
|