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       mu mfind - find e-mail messages in the mu database with mu4e defaults.
9
10

SYNOPSIS

12       mu find [options] <search expression>
13
14

DESCRIPTION

16       mu find is the mu command for searching e-mail message that were stored
17       earlier using mu index(1).
18
19       mu mfind is a version of mu find that defaults to -include-related  and
20       --skip-dups, just like mu4e does.
21
22

SEARCHING MAIL

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

OPTIONS

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

RETURN VALUE

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

ENCODING

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

BUGS

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

AUTHOR

352       Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
353
354