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 mu-query(7).
42
43

OPTIONS

45       Note, some of the important options are described in the mu(1) man-page
46       and not here, as they apply to multiple mu-commands.
47
48       The find-command has various options that influence the way mu displays
49       the   results.   If  you  don't  specify  anything,  the  defaults  are
50       --fields="d f s", --sortfield=date and --reverse.
51
52
53       -f, --fields=<fields>
54              specifies a string that determines which fields are shown in the
55              output.  This string consists of a number of characters (such as
56              's' for subject or 'f' for from), which will  replace  with  the
57              actual  field  in  the output. Fields that are not known will be
58              output as-is, allowing for some simple formatting.
59
60              For example:
61
62                $ mu find subject:snow --fields "d f s"
63
64              would list the date, subject and sender  of  all  messages  with
65              'snow' in the their subject.
66
67              The table of replacement characters is superset of the list men‐
68              tions for search parameters; the complete list:
69
70                   t       to: recipient
71                   c       cc: (carbon-copy) recipient
72                   h       Bcc: (blind carbon-copy, hidden) recipient
73                   d       Sent date of the message
74                   f       Message sender (from:)
75                   g       Message flags (flags)
76                   l       Full path to the message (location)
77                   p       Message priority (high, normal, low)
78                   s       Message subject
79                   i       Message-id
80                   m       maildir
81                   v       Mailing-list Id
82
83
84              The message flags are described in mu-query(7). As an example, a
85              message  which  is 'seen', has an attachment and is signed would
86              have 'asz' as its corresponding  output  string,  while  an  en‐
87              crypted new message would have 'nx'.
88
89
90       -s, --sortfield =<field> and -z,
91              --reverse specifies the field to sort the search results by, and
92              the direction (i.e., 'reverse' means that the sort should be re‐
93              verted - Z-A). The following fields are supported:
94
95                   cc,c            Cc (carbon-copy) recipient(s)
96                   bcc,h           Bcc (blind-carbon-copy) recipient(s)
97                   date,d          Message sent date
98                   from,f          Message sender
99                   maildir,m       Maildir
100                   msgid,i         Message id
101                   prio,p          Nessage priority
102                   subject,s       Message subject
103                   to,t            To:-recipient(s)
104                   list,v          Mailing-list id
105
106              Thus, for example, to sort messages by date, you could specify:
107
108                $ mu find fahrrad --fields "d f s" --sortfield=date --reverse
109
110              Note,  if  you  specify  a  sortfield,  by default, messages are
111              sorted in reverse (descending) order (e.g., from lowest to high‐
112              est).  This  is  usually  a good choice, but for dates it may be
113              more useful to sort in the opposite direction.
114
115
116       -n, --maxnum=<number>
117              If > 0, display maximally that number of entries.  If not speci‐
118              fied, all matching entries are displayed.
119
120
121       --summary-len=<number>
122              If  >  0,  use  that number of lines of the message to provide a
123              summary.
124
125
126       --format=plain|links|xquery|xml|sexp
127              output results in the specified format.
128
129              The default is plain, i.e normal output with one line  per  mes‐
130              sage.
131
132              links  outputs  the  results as a maildir with symbolic links to
133              the found messages. This enables  easy  integration  with  mail-
134              clients (see below for more information).
135
136              xml formats the search results as XML.
137
138              sexp  formats  the  search results as an s-expression as used in
139              Lisp programming environments.
140
141              xquery shows the  Xapian  query  corresponding  to  your  search
142              terms. This is meant for for debugging purposes.
143
144
145       --linksdir =<dir> and -c, --clearlinks
146              output the results as a maildir with symbolic links to the found
147              messages. This enables easy integration with  mail-clients  (see
148              below  for  more  information). mu will create the maildir if it
149              does not exist yet.
150
151              If you specify  --clearlinks,  all  existing  symlinks  will  be
152              cleared  from  the target directories; this allows for re-use of
153              the same maildir. However, this option will delete  any  symlink
154              it finds, so be careful.
155
156                $ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks
157
158              will  store  links to found messages in ~/Maildir/search. If the
159              directory does not exist yet, it will be created.
160
161              Note: when mu creates a Maildir for these  links,  it  automati‐
162              cally  inserts a .noindex file, to exclude the directory from mu
163              index.
164
165
166       --after=<timestamp> only show messages whose message files were
167              last modified (mtime) after <timestamp>. <timestamp> is  a  UNIX
168              time_t value, the number of seconds since 1970-01-01 (in UTC).
169
170              From  the command line, you can use the date command to get this
171              value. For example, only consider messages modified (or created)
172              in the last 5 minutes, you could specify
173                --after=`date +%s --date='5 min ago'`
174              This is assuming the GNU date command.
175
176
177
178       --exec=<command>
179              the  --exec  command  causes  the command to be executed on each
180              matched message; for example, to see the raw text  of  all  mes‐
181              sages matching 'milkshake', you could use:
182                $ mu find milkshake --exec='less'
183              which is roughly equivalent to:
184                $ mu find milkshake --fields="l" | xargs less
185
186
187
188       -b, --bookmark=<bookmark>
189              use  a  bookmarked search query. Using this option, a query from
190              your bookmark file will be prepended to  other  search  queries.
191              See mu-bookmarks(1) for the details of the bookmarks file.
192
193
194
195       --skip-dups,-u whenever there are multiple messages with the
196              same  name,  only show the first one. This is useful if you have
197              copies of the same message, which is a  common  occurrence  when
198              using e.g. Gmail together with offlineimap.
199
200
201       --include-related,-r also include messages being referred to by
202              the  matched messages -- i.e.. include messages that are part of
203              the same message thread as some matched messages. This is useful
204              if you want Gmail-style 'conversations'. Note, finding these re‐
205              lated messages make searches slower.
206
207
208       -t, --threads show messages in a 'threaded' format --
209              that is, with indentation and arrows  showing  the  conversation
210              threads in the list of matching messages. When using this, sort‐
211              ing is chronological (by date), based on the newest message in a
212              thread.
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 ex‐
266              pression by adding something like the following to your  folders
267              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