mu-find(1)

1MU(FIND)                         User Manuals                         MU(FIND)
2
3
4

NAME

6       mu find - find e-mail messages in the mu database.
7
8

SYNOPSIS

10       mu find [options] <search expression>
11
12

DESCRIPTION

14       mu find is the mu command for searching e-mail message that were stored
15       earlier using mu index(1).
16
17

SEARCHING MAIL

19       mu find starts a search for messages in the database  that  match  some
20       search  pattern.  The  search  patterns  are described in detail in mu-
21       query(7).
22
23       For example:
24
25          $ mu find subject:snow and date:2017..
26
27       would find all messages in 2017 with 'snow' in the subject field, e.g:
28
29         2009-03-05 17:57:33 EET Lucia  <lucia@example.com> running in the snow
30         2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow
31
32       Note, this the default, plain-text output, which is the default, so you
33       don't  have  to  use --format=plain. For other types of output (such as
34       symlinks, XML or s-expressions), see the discussion in the OPTIONS-sec‐
35       tion below about --format.
36
37       The  search pattern is taken as a command-line parameter. If the search
38       parameter consists of multiple parts  (as  in  the  example)  they  are
39       treated as if there were a logical and between them.
40
41       For details on the possible queries, see
42
43
44
45

OPTIONS

47       Note, some of the important options are described in the mu(1) man-page
48       and not here, as they apply to multiple mu-commands.
49
50       The find-command has various options that influence the way mu displays
51       the   results.   If  you  don't  specify  anything,  the  defaults  are
52       --fields="d f s", --sortfield=date and --reverse.
53
54
55       -f, --fields=<fields>
56              specifies a string that determines which fields are shown in the
57              output.  This string consists of a number of characters (such as
58              's' for subject or 'f' for from), which will  replace  with  the
59              actual  field  in  the output. Fields that are not known will be
60              output as-is, allowing for some simple formatting.
61
62              For example:
63
64                $ mu find subject:snow --fields "d f s"
65
66              would list the date, subject and sender  of  all  messages  with
67              'snow' in the their subject.
68
69              The table of replacement characters is superset of the list men‐
70              tions for search parameters; the complete list:
71
72                   t    to: recipient
73                   c    cc: (carbon-copy) recipient
74                   h    Bcc: (blind carbon-copy, hidden) recipient
75                   d    Sent date of the message
76                   f    Message sender (from:)
77                   g    Message flags (flags)
78                   l    Full path to the message (location)
79                   p    Message priority (high, normal, low)
80                   s    Message subject
81                   i    Message-id
82                   m    maildir
83                   v       Mailing-list Id
84
85
86              The message flags are described in mu-query(7). As an example, a
87              message  which  is 'seen', has an attachment and is signed would
88              have  'asz'  as  its  corresponding  output  string,  while   an
89              encrypted new message would have 'nx'.
90
91
92       -s, --sortfield =<field> and -z,
93              --reverse specifies the field to sort the search results by, and
94              the direction (i.e., 'reverse' means that  the  sort  should  be
95              reverted - Z-A). The following fields are supported:
96
97                   cc,c            Cc (carbon-copy) recipient(s)
98                   bcc,h           Bcc (blind-carbon-copy) recipient(s)
99                   date,d          Message sent date
100                   from,f          Message sender
101                   maildir,m       Maildir
102                   msgid,i         Message id
103                   prio,p          Nessage priority
104                   subject,s       Message subject
105                   to,t            To:-recipient(s)
106                   list,v          Mailing-list id
107
108              Thus, for example, to sort messages by date, you could specify:
109
110                $ mu find fahrrad --fields "d f s" --sortfield=date --reverse
111
112              Note,  if  you  specify  a  sortfield,  by default, messages are
113              sorted in reverse (descending) order (e.g., from lowest to high‐
114              est).  This  is  usually  a good choice, but for dates it may be
115              more useful to sort in the opposite direction.
116
117
118       -n, --maxnum=<number>
119              If > 0, display maximally that number of entries.  If not speci‐
120              fied, all matching entries are displayed.
121
122
123       --summary-len=<number>
124              If  >  0,  use  that number of lines of the message to provide a
125              summary.
126
127
128       --format=plain|links|xquery|xml|sexp
129              output results in the specified format.
130
131              The default is plain, i.e normal output with one line  per  mes‐
132              sage.
133
134              links  outputs  the  results as a maildir with symbolic links to
135              the found messages. This enables  easy  integration  with  mail-
136              clients (see below for more information).
137
138              xml formats the search results as XML.
139
140              sexp  formats  the  search results as an s-expression as used in
141              Lisp programming environments.
142
143              xquery shows the  Xapian  query  corresponding  to  your  search
144              terms. This is meant for for debugging purposes.
145
146
147       --linksdir =<dir> and -c, --clearlinks
148              output the results as a maildir with symbolic links to the found
149              messages. This enables easy integration with  mail-clients  (see
150              below  for  more  information). mu will create the maildir if it
151              does not exist yet.
152
153              If you specify  --clearlinks,  all  existing  symlinks  will  be
154              cleared  from  the target directories; this allows for re-use of
155              the same maildir. However, this option will delete  any  symlink
156              it finds, so be careful.
157
158                $ mu find grolsch --linksdir=~/Maildir/search --clearlinks
159
160              will  store  links to found messages in ~/Maildir/search. If the
161              directory does not exist yet, it will be created.
162
163              Note: when mu creates a Maildir for these  links,  it  automati‐
164              cally  inserts a .noindex file, to exclude the directory from mu
165              index.
166
167
168       --after=<timestamp> only show messages whose message files were
169              last modified (mtime) after <timestamp>. <timestamp> is  a  UNIX
170              time_t value, the number of seconds since 1970-01-01 (in UTC).
171
172              From  the command line, you can use the date command to get this
173              value. For example, only consider messages modified (or created)
174              in the last 5 minutes, you could specify
175                --after=`date +%s --date='5 min ago'`
176              This is assuming the GNU date command.
177
178
179
180       --exec=<command>
181              the  --exec  command  causes  the command to be executed on each
182              matched message; for example, to see the raw text  of  all  mes‐
183              sages matching 'milkshake', you could use:
184                $ mu find milkshake --exec='less'
185              which is roughly equivalent to:
186                $ mu find milkshake --fields="l" | xargs less
187
188
189
190       -b, --bookmark=<bookmark>
191              use  a  bookmarked search query. Using this option, a query from
192              your bookmark file will be prepended to  other  search  queries.
193              See mu-bookmarks(1) for the details of the bookmarks file.
194
195
196
197       --skip-dups,-u whenever there are multiple messages with the
198              same  name,  only show the first one. This is useful if you have
199              copies of the same message, which is a  common  occurrence  when
200              using e.g. Gmail together with offlineimap.
201
202
203       --include-related,-r also include messages being refered to by
204              the  matched messages -- i.e.. include messages that are part of
205              the same message thread as some matched messages. This is useful
206              if  you  want  Gmail-style  'conversations'. Note, finding these
207              related messages make searches slower.
208
209
210       -t, --threads show messages in a 'threaded' format -- that is,
211              with indentation and arrows showing the conversation threads  in
212              the list of matching messages.
213
214              Messages in the threaded list are indented based on the depth in
215              the discussion, and are prefix with a kind of arrow with thread-
216              related  information  about the message, as in the following ta‐
217              ble:
218
219              |             | normal | orphan | duplicate |
220              |-------------+--------+--------+-----------|
221              | first child | `->    | `*>    | `=>       |
222              | other       | |->    | |*>    | |=>       |
223
224              Here, an 'orphan' is a message without a parent message (in  the
225              list  of matches), and a duplicate is a message whose message-id
226              was already seen before; not this may not  really  be  the  same
227              message, if the message-id was copied.
228
229              The algorithm used for determining the threads is based on Jamie
230              Zawinksi's description: http://www.jwz.org/doc/threading.html
231
232
233
234   Integrating mu find with mail clients
235       mutt
236
237              For mutt you can use the following in your muttrc; pressing  the
238              F8 key will start a search, and F9 will take you to the results.
239
240              # mutt macros for mu
241              macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \
242                                       "mu find"
243              macro index <F9> "<change-folder-readonly>~/Maildir/search" \
244                                       "mu find results"
245
246
247
248
249       Wanderlust
250
251              Sam  B suggested the following on the mu-mailing list. First add
252              the following to your Wanderlust configuration file:
253
254              (require 'elmo-search)
255              (elmo-search-register-engine
256                  'mu 'local-file
257                  :prog "/usr/local/bin/mu" ;; or wherever you've installed it
258                  :args '("find" pattern "--fields" "l") :charset 'utf-8)
259
260              (setq elmo-search-default-engine 'mu)
261              ;; for when you type "g" in folder or summary.
262              (setq wl-default-spec "[")
263
264              Now, you can search using the g key binding; you can also create
265              permanent  virtual  folders  when  the  messages  matching  some
266              expression by adding something like the following to your  fold‐
267              ers file.
268
269              VFolders {
270                [date:today..now]!mu  "Today"
271
272                [size:1m..100m]!mu    "Big"
273
274                [flag:unread]!mu      "Unread"
275              }
276
277              After restarting Wanderlust, the virtual folders should appear.
278
279
280              Wanderlust (old)
281
282              Another  way  to integrate mu and wanderlust is shown below; the
283              aforementioned method is recommended, but if that does not  work
284              for some reason, the below can be an alternative.
285
286              (defvar mu-wl-mu-program     "/usr/local/bin/mu")
287              (defvar mu-wl-search-folder  "search")
288
289              (defun mu-wl-search ()
290                "search for messages with `mu', and jump to the results"
291                 (let* ((muexpr (read-string "Find messages matching: "))
292                     (sfldr  (concat elmo-maildir-folder-path "/"
293                            mu-wl-search-folder))
294                     (cmdline (concat mu-wl-mu-program " find "
295                              "--clearlinks --format=links --linksdir='" sfldr "' "
296                             muexpr))
297                     (rv (shell-command cmdline)))
298                  (cond
299                    ((= rv 0)  (message "Query succeeded"))
300                    ((= rv 2)  (message "No matches found"))
301                    (t (message "Error running query")))
302                (= rv 0)))
303
304              (defun mu-wl-search-and-goto ()
305                "search and jump to the folder with the results"
306                (interactive)
307                (when (mu-wl-search)
308                  (wl-summary-goto-folder-subr
309                    (concat "." mu-wl-search-folder)
310                    'force-update nil nil t)
311                  (wl-summary-sort-by-date)))
312
313              ;; querying both in summary and folder
314              (define-key wl-summary-mode-map (kbd "Q") ;; => query
315                '(lambda()(interactive)(mu-wl-search-and-goto)))
316              (define-key wl-folder-mode-map (kbd "Q") ;; => query
317                '(lambda()(interactive)(mu-wl-search-and-goto)))
318
319
320
321

RETURN VALUE

323       mu  find  returns  0 upon successful completion; if the search was per‐
324       formed, there needs to be a least one match. Anything else leads  to  a
325       non-zero return value, for example:
326
327       | code | meaning                        |
328       |------+--------------------------------|
329       |    0 | ok                             |
330       |    1 | general error                  |
331       |    2 | no matches (for 'mu find')     |
332       |    4 | database is corrupted          |
333
334
335

ENCODING

337       mu  find output is encoded according the locale for --format=plain (the
338       default), and UTF-8 for all other formats (sexp, xml).
339
340
341

BUGS

343       Please report bugs if you find them:  https://github.com/djcb/mu/issues
344       If  you  have specific messages which are not matched correctly, please
345       attach them (appropriately censored if needed).
346
347

AUTHOR

349       Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
350
351