diff --git a/man/mu-mfind.1 b/man/mu-mfind.1 new file mode 100644 index 00000000..c1166d04 --- /dev/null +++ b/man/mu-mfind.1 @@ -0,0 +1,390 @@ +.TH MU FIND 1 "19 April 2015" "User Manuals" + +.SH NAME + +mu find \- find e-mail messages in the \fBmu\fR database. + +mu mfind \- find e-mail messages in the \fBmu\fR database with mu4e defaults. + +.SH SYNOPSIS + +.B mu find [options] + +.SH DESCRIPTION + +\fBmu find\fR is the \fBmu\fR command for searching e-mail message +that were stored earlier using \fBmu index\fR(1). + +\fBmu mfind\fR is a version of \fBmu find\fR that defaults to +\f--include-related\fR and \fB--skip-dups\fR, just like \fBmu4e\fR does. + +.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:2017.. +.fi + +would find all messages in 2017 with 'snow' in the subject field, e.g: + +.nf + 2009-03-05 17:57:33 EET Lucia running in the snow + 2009-03-05 18:38:24 EET Marius 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 + + + +.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\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; the complete list: + +.nf + t \fBt\fRo: recipient + c \fBc\fRc: (carbon-copy) recipient + h Bcc: (blind carbon-copy, \fBh\fRidden) 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) + p Message \fBp\fRriority (high, normal, low) + s Message \fBs\fRubject + i Message-\fBi\fRd + m \fBm\fRaildir + v Mailing-list Id +.fi + + +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\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). The +following fields are supported: + +.nf + cc,c Cc (carbon-copy) recipient(s) + bcc,h Bcc (blind-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) + list,v Mailing-list id +.fi + +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=\fR +If > 0, display maximally that number of entries. If not specified, all matching entries are displayed. + +.TP +\fB\-\-summary-len=\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\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 --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\fR only show messages whose message files were +last modified (\fBmtime\fR) after \fI\fR. \fI\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\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\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 refered 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. + +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 "mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\ + "mu find" +macro index "~/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. + + +\fBWanderlust (old)\fR + +Another way to integrate \fBmu\fR and \fBwanderlust\fR is shown below; the +aforementioned method is recommended, but if that does not work for some +reason, the below can be an alternative. + +.nf +(defvar mu-wl-mu-program "/usr/local/bin/mu") +(defvar mu-wl-search-folder "search") + +(defun mu-wl-search () + "search for messages with `mu', and jump to the results" + (let* ((muexpr (read-string "Find messages matching: ")) + (sfldr (concat elmo-maildir-folder-path "/" + mu-wl-search-folder)) + (cmdline (concat mu-wl-mu-program " find " + "--clearlinks --format=links --linksdir='" sfldr "' " + muexpr)) + (rv (shell-command cmdline))) + (cond + ((= rv 0) (message "Query succeeded")) + ((= rv 2) (message "No matches found")) + (t (message "Error running query"))) + (= rv 0))) + +(defun mu-wl-search-and-goto () + "search and jump to the folder with the results" + (interactive) + (when (mu-wl-search) + (wl-summary-goto-folder-subr + (concat "." mu-wl-search-folder) + 'force-update nil nil t) + (wl-summary-sort-by-date))) + +;; querying both in summary and folder +(define-key wl-summary-mode-map (kbd "Q") ;; => query + '(lambda()(interactive)(mu-wl-search-and-goto))) +(define-key wl-folder-mode-map (kbd "Q") ;; => query + '(lambda()(interactive)(mu-wl-search-and-goto))) + +.fi + + +.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 | +| 2 | no matches (for 'mu find') | +| 4 | database is corrupted | +.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 + +.SH "SEE ALSO" + +.BR mu (1), +.BR mu-index (1), +.BR mu-query (7)