emacs
/
mu
mirror of https://github.com/djcb/mu.git
1
0
Fork 0
Code Issues Releases Wiki Activity

man: generate manpages from .org files 

Generate the manpages from org-documents which makes it a bit easier to
keep them update to date since I find org-syntax easier than troff, and
we can use include files.
This commit is contained in:
Dirk-Jan C. Binnema 2022-12-18 00:21:52 +02:00
parent ba09b8fc2c
commit a259ae4162
45 changed files with 1667 additions and 1972 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
man/author.inc Normal file
View File

@ -0,0 +1,7 @@
* AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
# Local Variables:
# mode: org
# End:

7
man/bugs.inc Normal file
View File

@ -0,0 +1,7 @@
* REPORTING BUGS
Please report bugs at <https://github.com/djcb/mu/issues>.
# Local Variables:
# mode: org
# End:

31
man/common-options.inc Normal file
View File

@ -0,0 +1,31 @@
* COMMON OPTIONS
** -d, --debug
makes mu generate extra debug information, useful for debugging the program
itself. By default, debug information goes to the log file, ~/.cache/mu/mu.log.
It can safely be deleted when mu is not running. When running with --debug
option, the log file can grow rather quickly. See the note on logging below.
** -q, --quiet
causes mu not to output informational messages and progress information to
standard output, but only to the log file. Error messages will still be sent to
standard error. Note that mu index is much faster with --quiet, so it is
recommended you use this option when using mu from scripts etc.
** --log-stderr
causes mu to not output log messages to standard error, in addition to sending
them to the log file.
** --nocolor
do not use ANSI colors. The environment variable ~NO_COLOR~ can be used as an
alternative to ~--nocolor~.
** -V, --version
prints mu version and copyright information.
** -h, --help
lists the various command line options.
# Local Variables:
# mode: org
# End:

12
man/copyright.inc.in Normal file
View File

@ -0,0 +1,12 @@
* COPYRIGHT
This manpage is part of ~mu~ @VERSION@.
Copyright © 2022 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later
<https://gnu.org/licenses/gpl.html>. This is free software: you are free to
change and redistribute it. There is NO WARRANTY, to the extent permitted by
law.
# Local Variables:
# mode: org
# End:

9
man/exit-code.inc Normal file
View File

@ -0,0 +1,9 @@
* EXIT CODE
This command returns 0 upon successful completion, or a non-zero exit code
otherwise.
# Local Variables:
# mode: org
# End:

98
man/meson.build
View File

@ -14,23 +14,81 @@
## along with this program; if not, write to the Free Software Foundation,
## Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
install_man(
['mu.1',
'mu-add.1',
'mu-bookmarks.5',
'mu-cfind.1',
'mu-easy.1',
'mu-extract.1',
'mu-fields.1',
'mu-find.1',
'mu-help.1',
'mu-index.1',
'mu-info.1',
'mu-init.1',
'mu-mkdir.1',
'mu-query.7',
'mu-remove.1',
'mu-script.1',
'mu-server.1',
'mu-verify.1',
'mu-view.1'])
#
# generate org include files
#
man_data=configuration_data()
man_data.set('VERSION', meson.project_version())
incs=[
'author.inc',
'bugs.inc',
'common-options.inc',
'copyright.inc.in',
'exit-code.inc',
'muhome.inc',
'prefooter.inc',
]
foreach inc: incs
# configure the .in ones
if inc.substring(-3) == '.in'
configure_file(input: inc,
output: '@BASENAME@',
configuration: man_data)
else # and copy the rest
configure_file(input: inc, output:'@BASENAME@.inc',
copy:true)
endif
endforeach
# man-pages is org-format.
man_orgs=[
'mu.1.org',
'mu-add.1.org',
'mu-bookmarks.5.org',
'mu-cfind.1.org',
'mu-easy.5.org',
'mu-extract.1.org',
'mu-fields.1.org',
'mu-find.1.org',
'mu-help.1.org',
'mu-index.1.org',
'mu-info.1.org',
'mu-init.1.org',
'mu-mkdir.1.org',
'mu-query.7.org',
'mu-remove.1.org',
'mu-server.1.org',
'mu-verify.1.org',
'mu-view.1.org'
]
foreach src : man_orgs
# copy to builddir so org-includes work.
configure_file(input: src, output:'@BASENAME@.org', copy:true)
# meson makes in tricky to use the results of e.g. configure_file
# in custom_commands..., so this is admittedly a little hacky.
org = join_paths(meson.current_build_dir(), src)
man = '@BASENAME@'
expr_tmpl = ''.join([
'(progn',
' (require \'ox-man)',
' (org-export-to-file \'man "@0@"))',
])
expr = expr_tmpl.format(org.substring(0,-4))
sectiondir = join_paths(mandir, 'man' + src.substring(-5, -4))
custom_target(src + '-to-man',
build_by_default: true,
input: src,
output: '@BASENAME@',
install: true,
install_dir: sectiondir,
depend_files: incs,
command: [emacs,
'--no-init-file',
'--batch',
org,
'--eval', expr])
endforeach

47
man/mu-add.1
View File

@ -1,47 +0,0 @@
.TH MU ADD 1 "May 2022" "User Manuals"
.SH NAME
mu add\- add one or more messages to the database
.SH SYNOPSIS
.B mu add <file> [<files>]
.SH DESCRIPTION
\fBmu add\fR is the command to add specific message files to the
database. Each file must be specified with an absolute path.
.SH OPTIONS
\fBmu add\fR does not have its own options, but the general options for
determining the location of the database (\fI--muhome\fR) are available. See
\fBmu-index\fR(1) for more information.
.SH RETURN VALUE
\fBmu add\fR returns 0 upon success; in general, the following error codes are
returned:
.nf
| code | meaning |
|------+-----------------------------------|
| 0 | ok |
| 1 | general error |
.fi
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1),
.BR mu-index (1),
.BR mu-remove (1)

28
man/mu-add.1.org Normal file
View File

@ -0,0 +1,28 @@
#+title: MU ADD
* NAME
~mu add~ - add one or more messages to the database
* SYNOPSIS
*mu [common-options] add [options] <file> [<files>]*
* DESCRIPTION
~mu add~ is the command to add specific message files to the database. Each file
must be specified with an absolute path.
* ADD OPTIONS
#+include: "muhome.inc" :minlevel 2
#+include: "common-options.inc" :minlevel 1
#+include: "exit-code.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-remove(1)*

36
man/mu-bookmarks.5
View File

@ -1,36 +0,0 @@
.TH MU-BOOKMARKS 5 "July 2019" "User Manuals"
.SH NAME
bookmarks \- file with bookmarks (shortcuts) for mu search expressions
.SH DESCRIPTION
Bookmarks are named shortcuts for search queries. They allow using a convenient
name for often-used queries. The bookmarks are also visible as shortcuts in the
mu experimental user interfaces, \fImug\fR and \fImug2\fR.
The bookmarks file is read from \fI<muhome>/bookmarks\fR. On Unix this would
typically be w be \fI~/.config/mu/bookmarks\fR, but this can be influenced using
the \fB\-\-muhome\fR parameter for \fBmu-find\fR(1) and \fBmug\fR(1).
The bookmarks file is a typical key=value \fB.ini\fR-file, which is best shown
by means of an example:
.nf
[mu]
inbox=maildir:/inbox # inbox
oldhat=maildir:/archive subject:hat # archived with subject containing 'hat'
.fi
The \fB[mu]\fR group header is required.
For practical uses of bookmarks, see \fBmu-find\fR(1).
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1), mu-find (1)

35
man/mu-bookmarks.5.org Normal file
View File

@ -0,0 +1,35 @@
#+title: MU-BOOKMARKS
* NAME
bookmarks - file with bookmarks (shortcuts) for mu search expressions
* DESCRIPTION
Bookmarks are named shortcuts for search queries. They allow using a convenient
name for often-used queries. The bookmarks are also visible as shortcuts in the
mu experimental user interfaces, =mug= and =mug2=.
The bookmarks file is read from =<muhome>/bookmarks=. On Unix this would typically
be w be =~/.config/mu/bookmarks=, but this can be influenced using the ~--muhome~
parameter for *mu-find(1)*.
The bookmarks file is a typical key=value *.ini*-file, which is best shown by
means of an example:
#+begin_example
[mu]
inbox=maildir:/inbox # inbox
oldhat=maildir:/archive subject:hat # archived with subject containing 'hat'
#+end_example
The *[mu]* group header is required. For practical uses of bookmarks, see
*mu-find(1)*.
#+include: "author.inc" :minlevel 1
#+include: "copyright.inc" :minlevel 1
* SEE ALSO
*mu(1)*, *mu-find(1)*

133
man/mu-cfind.1
View File

@ -1,133 +0,0 @@
.TH MU CFIND 1 "April 2019" "User Manuals"
.SH NAME
\fBmu cfind\fR is the \fBmu\fR command to find contacts in the \fBmu\fR
database and export them for use in other programs.
.SH SYNOPSIS
.B mu cfind [options] [<pattern>]
.SH DESCRIPTION
\fBmu cfind\fR is the \fBmu\fR command for finding \fIcontacts\fR (name and
e-mail address of people who were either an e-mail's sender or
receiver). There are different output formats available, for importing the
contacts into other programs.
.SH SEARCHING CONTACTS
When you index your messages (see \fBmu index\fR), \fBmu\fR creates a list of
unique e-mail addresses found and the accompanying name, and caches this
list. In case the same e-mail address is used with different names, the most
recent non-empty name is used.
\fBmu cfind\fR starts a search for contacts that match a \fIregular
expression\fR. For example:
.nf
$ mu cfind '@gmail\.com'
.fi
would find all contacts with a gmail-address, while
.nf
$ mu cfind Mary
.fi
lists all contacts with Mary in either name or e-mail address.
If you do not specify a search expression, \fBmu cfind\fR returns the full list
of contacts. Note, \fBmu cfind\fR uses a cache with the e-mail information,
which is populated during the indexing process.
The regular expressions are Perl-compatible (as per the PCRE-library used by
GRegex).
.SH OPTIONS
.TP
\fB\-\-format\fR=\fIplain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv\fR
sets the output format to the given value. The following are available:
.nf
| --format= | description |
|-------------+-----------------------------------|
| plain | default, simple list |
| mutt-alias | mutt alias-format |
| mutt-ab | mutt external address book format |
| wl | wanderlust addressbook format |
| org-contact | org-mode org-contact format |
| bbdb | BBDB format |
| csv | comma-separated values (*) |
.fi
(*) CSV is not fully standardized, but \fBmu cfind\fR follows some common
practices: any double-quote is replaced by a double-double quote (thus, "hello"
become ""hello"", and fields with commas are put in double-quotes. Normally,
this should only apply to name fields.
.TP
\fB\-\-personal\fR only show addresses seen in messages where one of 'my' e-mail
addresses was seen in one of the address fields; this is to exclude addresses
only seen in mailing-list messages. See the \fB\-\-my-address\fR parameter in
\fBmu index\fR.
.TP
\fB\-\-after=\fR\fI<timestamp>\fR only show addresses last seen 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 addresses last seen after 2009-06-01, you could specify
.nf
--after=`date +%s --date='2009-06-01'`
.fi
.SH RETURN VALUE
\fBmu cfind\fR returns 0 upon successful completion -- that is, at least one
contact was found. Anything else leads to a non-zero return value:
.nf
| code | meaning |
|------+--------------------------------|
| 0 | ok |
| 1 | general error |
| 2 | no matches (for 'mu cfind') |
.fi
.SH INTEGRATION WITH MUTT
You can use \fBmu cfind\fR as an external address book server for \fBmutt\fR.
For this to work, add the following to your \fImuttrc\fR:
.nf
set query_command = "mu cfind --format=mutt-ab '%s'"
.fi
Now, in mutt, you can search for e-mail addresses using the \fBquery\fR-command,
which is (by default) accessible by pressing \fBQ\fR.
.SH ENCODING
\fBmu cfind\fR output is encoded according to the current locale except for
\fI--format=bbdb\fR. This is hard-coded to UTF-8, and as such specified in the
output-file, so emacs/bbdb can handle things correctly, without guessing.
.SH BUGS
Please report bugs if you find them at \fBhttps://github.com/djcb/mu/issues\fR.
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1),
.BR mu-index (1),
.BR mu-find (1),
.BR pcrepattern(3)

116
man/mu-cfind.1.org Normal file
View File

@ -0,0 +1,116 @@
#+title: MU CFIND
* NAME
*mu cfind* is the *mu* command to find contacts in the *mu* database and export them
for use in other programs.
* SYNOPSIS
*mu [common-options] cfind [options] [<pattern>]*
* DESCRIPTION
*mu cfind* is the *mu* command for finding =contacts= (name and e-mail address of
people who were either an e-mail's sender or receiver). There are different
output formats available, for importing the contacts into other programs.
* SEARCHING CONTACTS
When you index your messages (see *mu index*), *mu* creates a list of unique e-mail
addresses found and the accompanying name, and caches this list. In case the
same e-mail address is used with different names, the most recent non-empty name
is used.
*mu cfind* starts a search for contacts that match a =regular expression=. For
example:
#+begin_example
$ mu cfind '@gmail\.com'
#+end_example
would find all contacts with a gmail-address, while
#+begin_example
$ mu cfind Mary
#+end_example
lists all contacts with Mary in either name or e-mail address.
If you do not specify a search expression, *mu cfind* returns the full list of
contacts. Note, *mu cfind* uses a cache with the e-mail information, which is
populated during the indexing process.
The regular expressions are Perl-compatible (as per the PCRE-library used by
GRegex).
* CFIND OPTIONS
** --format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv
sets the output format to the given value. The following are available:
| --format= | description |
|-------------+-----------------------------------|
| plain | default, simple list |
| mutt-alias | mutt alias-format |
| mutt-ab | mutt external address book format |
| wl | wanderlust addressbook format |
| org-contact | org-mode org-contact format |
| bbdb | BBDB format |
| csv | comma-separated values [1] |
[1] *CSV is not fully standardized, but *mu cfind* follows some common practices:
any double-quote is replaced by a double-double quote (thus, "hello" become
""hello"", and fields with commas are put in double-quotes. Normally, this
should only apply to name fields.
** --personal,-p only show addresses seen in messages where one of 'my' e-mail
addresses was seen in one of the address fields; this is to exclude addresses
only seen in mailing-list messages. See the ~--my-address~ parameter to *mu init*.
# ** --after=<timestamp> only show addresses last seen after
# =<timestamp>=. =<timestamp>= is a UNIX *time_t* value, the number of
# seconds since 1970-01-01 (in UTC).
# From the command line, you can use the *date* command to get this value. For
# example, only consider addresses last seen after 2009-06-01, you could specify
# #+begin_example
# --after=`date +%s --date='2009-06-01'`
# #+end_example
#+include: "muhome.inc" :minlevel 2
#+include: "common-options.inc" :minlevel 1
* INTEGRATION WITH MUTT
You can use *mu cfind* as an external address book server for *mutt*.
For this to work, add the following to your =muttrc=:
#+begin_example
set query_command = "mu cfind --format=mutt-ab '%s'"
#+end_example
Now, in mutt, you can search for e-mail addresses using the *query*-command,
which is (by default) accessible by pressing *Q*.
* ENCODING
*mu cfind* output is encoded according to the current locale except for
=--format=bbdb=. This is hard-coded to UTF-8, and as such specified in the
output-file, so emacs/bbdb can handle things correctly, without guessing.
* EXIT CODE
This command returns 0 upon successful completion, or a non-zero exit code
otherwise: 1 for a generals error and 2 for 'no matches'.
#+include: "bugs.inc" :minlevel 1
#+include: "author.inc" :minlevel 1
#+include: "copyright.inc" :minlevel 1
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-find(1)*

0
man/mu-easy.1 → man/mu-easy.5.org
View File

100
man/mu-extract.1
View File

@ -1,100 +0,0 @@
.TH MU EXTRACT 1 "July 2012" "User Manuals"
.SH NAME
\fBmu extract\fR is the \fBmu\fR command to display and save message parts
(attachments), and open them with other tools.
.SH SYNOPSIS
.B mu extract [options] <file>
.B mu extract [options] <file> <pattern>
.SH DESCRIPTION
\fBmu extract\fR is the \fBmu\fR sub-command for extracting MIME-parts (e.g.,
attachments) from mail messages. The sub-command works on message files, and
does not require the message to be indexed in the database.
For attachments, the file name used when saving it is the name of the
attachment in the message. If there is no such name, or when saving
non-attachment MIME-parts, a name is derived from the message-id of the
message.
If you specify a pattern (a case-insensitive regular expression) as the second
argument, all attachments with filenames matching that pattern will be
extracted. The regular expressions are Perl-compatible (as per the
PCRE-library).
Without any options, \fBmu extract\fR simply outputs the list of leaf
MIME-parts in the message. Only 'leaf' MIME-parts (including RFC822
attachments) are considered, \fBmultipart/*\fR etc. are ignored.
.SH OPTIONS
.TP
\fB\-a\fR, \fB\-\-save\-attachments\fR
save all MIME-parts that look like attachments.
.TP
\fB\-\-save\-all\fR
save all non-multipart MIME-parts.
.TP
\fB\-\-parts\fR=<parts>
only consider the following numbered parts
(comma-separated list). The numbers for the parts can be seen from running
\fBmu extract\fR without any options but only the message file.
.TP
\fB\-\-target\-dir\fR=<dir>
save the parts in the target directory rather than
the current working directory.
.TP
\fB\-\-overwrite\fR
overwrite existing files with the same name; by default overwriting is not
allowed.
.TP
\fB\-\-play\fR Try to 'play' (open) the attachment with the default
application for the particular file type. On MacOS, this uses the \fBopen\fR
program, on other platforms it uses \fBxdg-open\fR. You can choose a different
program by setting the \fBMU_PLAY_PROGRAM\fR environment variable.
.SH EXAMPLES
To display information about all the MIME-parts in a message file:
.nf
$ mu extract msgfile
.fi
To extract MIME-part 3 and 4 from this message, overwriting existing files
with the same name:
.nf
$ mu extract --parts=3,4 --overwrite msgfile
.fi
To extract all files ending in '.jpg' (case-insensitive):
.nf
$ mu extract msgfile '.*\.jpg'
.fi
To extract an mp3-file, and play it in the default mp3-playing application:
.nf
$ mu extract --play msgfile 'whoopsididitagain.mp3'
.fi
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1)

89
man/mu-extract.1.org Normal file
View File

@ -0,0 +1,89 @@
#+title: MU EXTRACT
* NAME
*mu extract* is the *mu* command to display and save message parts
(attachments), and open them with other tools.
* SYNOPSIS
*mu [common-options] extract [options] <file>*
*mu [common-options] extract [options] <file> <pattern>*
* DESCRIPTION
*mu extract* is the *mu* sub-command for extracting MIME-parts (e.g., attachments)
from mail messages. The sub-command works on message files, and does not require
the message to be indexed in the database.
For attachments, the file name used when saving it is the name of the attachment
in the message. If there is no such name, or when saving non-attachment
MIME-parts, a name is derived from the message-id of the message.
If you specify a pattern (a case-insensitive regular expression) as the second
argument, all attachments with filenames matching that pattern will be
extracted. The regular expressions are Perl-compatible (as per the
PCRE-library).
Without any options, *mu extract* simply outputs the list of leaf MIME-parts in
the message. Only 'leaf' MIME-parts (including RFC822 attachments) are
considered, *multipart/** etc. are ignored.
* EXTRACT OPTIONS
** -a, --save-attachments
save all MIME-parts that look like attachments.
** --save-all
save all non-multipart MIME-parts.
** --parts=<parts>
only consider the following numbered parts (comma-separated list). The numbers
for the parts can be seen from running *mu extract* without any options but only
the message file.
** --target-dir=<dir>
save the parts in the target directory rather than the current working
directory.
** --overwrite
overwrite existing files with the same name; by default overwriting is not
allowed.
** --play
Try to 'play' (open) the attachment with the default application for the
particular file type. On MacOS, this uses the *open* program, on other platforms
it uses *xdg-open*. You can choose a different program by setting the
*MU_PLAY_PROGRAM* environment variable.
#+include: "common-options.inc" :minlevel 1
* EXAMPLES
To display information about all the MIME-parts in a message file:
#+begin_example
$ mu extract msgfile
#+end_example
To extract MIME-part 3 and 4 from this message, overwriting existing files with
the same name:
#+begin_example
$ mu extract --parts=3,4 --overwrite msgfile
#+end_example
To extract all files ending in '.jpg' (case-insensitive):
#+begin_example
$ mu extract msgfile '.*\.jpg'
#+end_example
To extract an mp3-file, and play it in the default mp3-playing application:
#+begin_example
$ mu extract --play msgfile 'whoopsididitagain.mp3'
#+end_example
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu(1)*

32
man/mu-fields.1
View File

@ -1,32 +0,0 @@
.TH MU FIELDS 1 "April 2022" "User Manuals"
.SH NAME
mu fields\- list all message fields
.SH SYNOPSIS
.B mu fields [options]
.SH DESCRIPTION
\fBmu fields\fR is the \fBmu\fR command for showing a table of message fields
and their properties.
.SH OPTIONS
Inherits common options from
.BR mu(1)
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1)

22
man/mu-fields.1.org Normal file
View File

@ -0,0 +1,22 @@
#+title: MU FIELDS
* NAME
*mu fields* - list all message fields
* SYNOPSIS
*mu [common-options] fields
* DESCRIPTION
*mu fields* is the *mu* command for showing a table of message fields and their
properties.
#+include: "common-options.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu(1)*

338
man/mu-find.1
View File

@ -1,338 +0,0 @@
.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 list use can use the \fBmu fields\fR command; 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)

288
man/mu-find.1.org Normal file
View File

@ -0,0 +1,288 @@
#+title: MU FIND
* NAME
*mu find* - find e-mail messages in the *mu* database.
* SYNOPSIS
*mu [common-options] find [options] <search expression>*
* DESCRIPTION
*mu find* is the *mu* command for searching e-mail message that were stored earlier
using *mu index(1)*.
* SEARCHING MAIL
*mu find* starts a search for messages in the database that match some search
pattern. The search patterns are described in detail in *mu-query(7)*.
For example:
#+begin_example
$ mu find subject:snow and date:2009..
#+end_example
would find all messages in 2009 with 'snow' in the subject field, e.g:
#+begin_example
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
#+end_example
Note, this the default, plain-text output, which is the default, so you don't
have to use *--format=plain*. For other types of output (such as symlinks, XML or
s-expressions), see the discussion in the *OPTIONS*-section below about *--format*.
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 *and* between them.
For details on the possible queries, see *mu-query(7)*.
* FIND OPTIONS
Note, some of the important options are described in the *mu*(1) man-page
and not here, as they apply to multiple mu-commands.
The *find*-command has various options that influence the way *mu* displays the
results. If you don't specify anything, the defaults are ~fields="d f s"~,
~--sortfield=date~ and ~--reverse~.
** -f, --fields=<fields>
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:
#+begin_example
$ mu find subject:snow --fields "d f s"
#+end_example
lists 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:
#+begin_example
t *t*o: recipient
d Sent *d*ate of the message
f Message sender (*f*rom:)
g Message flags (fla*g*s)
l Full path to the message (*l*ocation)
s Message *s*ubject
i Message-*i*d
m *m*aildir
#+end_example
For the complate list, see *mu-fields(1)*.
The message flags are described in *mu-query(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'.
** -s, --sortfield=<field> and -z,--reverse
specify 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:
#+begin_example
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)
#+end_example
For the complete list use can use the *mu fields* command; see *mu-fields(1)*.
Thus, for example, to sort messages by date, you could specify:
#+begin_example
$ mu find fahrrad --fields "d f s" --sortfield=date --reverse
#+end_example
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.
** -n, --maxnum=<number>
If > 0, display maximally that number of entries. If not specified, all matching
entries are displayed.
** --summary-len=<number>
If > 0, use that number of lines of the message to provide a summary.
** --format=<plain|links|xquery|xml|sexp>
output results in the specified format:
- The default is *plain*, i.e normal output with one line per message.
- *links* 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).
- *xml* formats the search results as XML.
- *sexp* formats the search results as an s-expression as used in Lisp programming
environments.
- *xquery* shows the Xapian query corresponding to your search terms. This is
meant for for debugging purposes.
** --linksdir=<dir> and -c, --clearlinks
when using ~-format=links~, 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). *mu* will create the maildir if it does not exist yet.
If you specify ~--clearlinks~, 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.
#+begin_example
$ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks
#+end_example
stores links to found messages in =~/Maildir/search=. If the directory does not
exist yet, it will be created. Note: when *mu* creates a Maildir for these links,
it automatically inserts a =.noindex= file, to exclude the directory from *mu
index*.
** --after=<timestamp>
only show messages whose message files were last modified (*mtime*) after
=<timestamp>=. =<timestamp>= is a UNIX *time_t* value, the number of seconds since
1970-01-01 (in UTC).
From the command line, you can use the *date* command to get this value. For
example, only consider messages modified (or created) in the last 5 minutes, you
could specify
#+begin_example
--after=`date +%s --date='5 min ago'`
#+end_example
This is assuming the GNU *date* command.
** --exec=<command>
the ~--exec~ coption causes the =command= to be executed on each matched message;
for example, to see the raw text of all messages matching 'milkshake', you could
use:
#+begin_example
$ mu find milkshake --exec='less'
#+end_example
which is roughly equivalent to:
#+begin_example
$ mu find milkshake --fields="l" | xargs less
#+end_example
** -b, --bookmark=<bookmark>
use a bookmarked search query. Using this option, a query from your bookmark
file will be prepended to other search queries. See *mu-bookmarks(5)* for the
details of the bookmarks file.
** -u, --skip-dups
whenever there are multiple messages with the same message-id field, 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 *offlineimap*.
** -r, --include-related
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'.
** -t, --threads
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:
#+begin_example
| | normal | orphan | duplicate |
|-------------+--------+--------+-----------|
| first child | `-> | `*> | `=> |
| other | |-> | |*> | |=> |
#+end_example
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: http://www.jwz.org/doc/threading.html
#+include: "muhome.inc" :minlevel 2
#+include: "common-options.inc" :minlevel 1
* Integrating mu find with mail clients
** *mutt*
For *mutt* you can use the following in your =muttrc=; pressing the F8 key will
start a search, and F9 will take you to the results.
#+begin_example
# 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"
#+end_example
** *Wanderlust*
*Sam B* suggested the following on the *mu*-mailing list. First add the following to
your Wanderlust configuration file:
#+begin_example
(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 "[")
#+end_example
Now, you can search using the *g* key binding; you can also create permanent
virtual folders when the messages matching some expression by adding something
like the following to your =folders= file.
#+begin_example
VFolders {
[date:today..now]!mu "Today"
[size:1m..100m]!mu "Big"
[flag:unread]!mu "Unread"
}
#+end_example
After restarting Wanderlust, the virtual folders should appear.
* ENCODING
*mu find* output is encoded according the locale for =--format=plain=
(the default), and UTF-8 for all other formats (=sexp=,
=xml=).
* EXIT CODE
This command returns 0 upon successful completion, or a non-zero exit code
otherwise: 1 for a generals error and 2 for 'no matches'.
#+include: "bugs.inc" :minlevel 1
#+include: "author.inc" :minlevel 1
#+include: "copyright.inc" :minlevel 1
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-query(7)*, *mu-fields(1)*

34
man/mu-help.1
View File

@ -1,34 +0,0 @@
.TH MU HELP 1 "July 2012" "User Manuals"
.SH NAME
\fBmu help\fR is a \fBmu\fR command that gives help information about mu
commands.
.SH SYNOPSIS
.B mu help <command>
.SH DESCRIPTION
\fBmu help\fR provides help information about mu commands.
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu-index (1),
.BR mu-find (1),
.BR mu-cfind (1),
.BR mu-mkdir (1),
.BR mu-view (1),
.BR mu-extract (1),
.BR mu-easy (1),
.BR mu-bookmarks (5)

19
man/mu-help.1.org Normal file
View File

@ -0,0 +1,19 @@
#+title: MU HELP
* NAME
*mu help* is a *mu* command that gives help information about mu commands.
* SYNOPSIS
*mu [common-options] help [<command>]*
* DESCRIPTION
*mu help* provides help information about mu commands.
#+include: "common-options.inc" :minlevel 1
#+include: "exit-code.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1

196
man/mu-index.1
View File

@ -1,196 +0,0 @@
.TH MU-INDEX 1 "June 2022" "User Manuals"
.SH NAME
mu index \- index e-mail messages stored in Maildirs
.SH SYNOPSIS
.B mu index [options]
.SH DESCRIPTION
\fBmu index\fR is the \fBmu\fR command for scanning the contents of Maildir
directories and storing the results in a Xapian database. The data can then be
queried using
.BR mu-find (1)\.
Before the first time you run \fBmu index\fR, you must run \fBmu init\fR to
initialize the database.
\fBindex\fR understands Maildirs as defined by Daniel Bernstein for
\fBqmail\fR(7). In addition, it understands recursive Maildirs (Maildirs within
Maildirs), Maildir++. It can also deal with VFAT-based Maildirs which use '!'
or ';' as the separators instead of ':'.
E-mail messages which are not stored in something resembling a maildir
leaf-directory (\fIcur\fR and \fInew\fR) are ignored, as are the cache
directories for \fInotmuch\fR and \fIgnus\fR, and any dot-directory.
Starting with mu 1.5.x, symlinks are followed, and can be spread over multiple
filesystems; however note that moving files around is much faster when multiple
filesystems are not involved.
If there is a file called \fI.noindex\fR in a directory, the contents of that
directory and all of its subdirectories will be ignored. This can be useful to
exclude certain directories from the indexing process, for example directories
with spam-messages.
If there is a file called \fI.noupdate\fR in a directory, the contents of that
directory and all of its subdirectories will be ignored, unless we do a full
rebuild (with \fBmu init\fR). This can be useful to speed up things you have
some maildirs that never change. Note that you can still search for these
messages, this only affects updating the database. \fI.noupdate\fR is ignored
when you start indexing with an empty database (such as directly after \fImu
init\fR.
There also the \fB--lazy-check\fR which can greatly speed up indexing; see below
for details.
The first run of \fBmu index\fR may take a few minutes if you have a lot of mail
(tens of thousands of messages). Fortunately, such a full scan needs to be done
only once; after that it suffices to index the changes, which goes much faster.
See the 'Note on performance (i,ii,iii)' below for more information.
The optional 'phase two' of the indexing-process is the removal of messages from
the database for which there is no longer a corresponding file in the Maildir.
If you do not want this, you can use \fB\-n\fR, \fB\-\-nocleanup\fR.
When \fBmu index\fR catches one of the signals \fBSIGINT\fR, \fBSIGHUP\fR or
\fBSIGTERM\fR (e.g., when you press Ctrl-C during the indexing process), it
tries to shutdown gracefully; it tries to save and commit data, and close the
database etc. If it receives another signal (e.g., when pressing Ctrl-C once
more), \fBmu index\fR will terminate immediately.
.SH OPTIONS
Some of the general options are described in the \fBmu(1)\fR man-page and not
here, as they apply to multiple mu commands.
.TP
\fB\-\-lazy-check\fR
in lazy-check mode, \fBmu\fR does not consider messages for which the
time-stamp (ctime) of the directory they reside in has not changed
since the previous indexing run. This is much faster than the non-lazy
check, but won't update messages that have change (rather than having
been added or removed), since merely editing a message does not update
the directory time-stamp. Of course, you can run \fBmu-index\fR
occasionally without \fB\-\-lazy-check\fR, to pick up such messages.
.TP
\fB\-\-nocleanup\fR
disables the database cleanup that \fBmu\fR does by default after indexing.
.SS A note on performance (i)
As a non-scientific benchmark, a simple test on the author's machine (a
Thinkpad X61s laptop using Linux 2.6.35 and an ext3 file system) with no
existing database, and a maildir with 27273 messages:
.nf
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
66,65s user 6,05s system 27% cpu 4:24,20 total
.fi
(about 103 messages per second)
A second run, which is the more typical use case when there is a database
already, goes much faster:
.nf
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
0,48s user 0,76s system 10% cpu 11,796 total
.fi
(more than 56818 messages per second)
Note that each test flushes the caches first; a more common use case might
be to run \fBmu index\fR when new mail has arrived; the cache may stay
quite 'warm' in that case:
.nf
$ time mu index --quiet
0,33s user 0,40s system 80% cpu 0,905 total
.fi
which is more than 30000 messages per second.
.SS A note on performance (ii)
As per June 2012, we did the same non-scientific benchmark, this time with an
Intel i5-2500 CPU @ 3.30GHz, an ext4 file system and a maildir with 22589
messages. We start without an existing database.
.nf
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
27,79s user 2,17s system 48% cpu 1:01,47 total
.fi
(about 813 messages per second)
A second run, which is the more typical use case when there is a database
already, goes much faster:
.nf
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
0,13s user 0,30s system 19% cpu 2,162 total
.fi
(more than 173000 messages per second)
.SS A note on performance (iii)
As per July 2016, we did the same non-scientific benchmark, again with
the Intel i5-2500 CPU @ 3.30GHz, an ext4 file system. This time, the
maildir contains 72525 messages.
.nf
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
40,34s user 2,56s system 64% cpu 1:06,17 total
.fi
(about 1099 messages per second).
.SS A note on performance (iv)
A few years later and its June 2022. There's a lot more happening during indexing, but indexing became multi-threaded and machines are faster; e.g. this
is with an AMD Ryzen Threadripper 1950X (32) @ 3.399GHz.
The instructions are a little different since we have a proper repeatable
benchmark now. After building,
.nf
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
% THREAD_NUM=4 build/lib/tests/bench-indexer -m perf
# random seed: R02Sf5c50e4851ec51adaf301e0e054bd52b
1..1
# Start of bench tests
# Start of indexer tests
indexed 5000 messages in 20 maildirs in 3763ms; 752 μs/message; 1328 messages/s (4 thread(s))
ok 1 /bench/indexer/4-cores
# End of indexer tests
# End of bench tests
.fi
Things are again a little faster, even though the index does a lot more now
(text-normalizatian, and pre-generating message-sexps). A faster machine helps,
too!
.SH RETURN VALUE
\fBmu index\fR return 0 upon successful completion; any other number signals an
error.
.SH BUGS
Please report bugs if you find any:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR maildir (5),
.BR mu (1),
.BR mu-init (1),
.BR mu-find (1),
.BR mu-cfind (1)

182
man/mu-index.1.org Normal file
View File

@ -0,0 +1,182 @@
#+title: MU-INDEX
* NAME
*mu index* -- index e-mail messages stored in Maildirs
* SYNOPSIS
*mu [common-options] index*
* DESCRIPTION
*mu index* is the *mu* command for scanning the contents of Maildir directories and
storing the results in a Xapian database. The data can then be queried using
*mu-find(1)*.
Before the first time you run *mu index*, you must run *mu init* to initialize the
database.
*index* understands Maildirs as defined by Daniel Bernstein for *qmail(7)*. In
addition, it understands recursive Maildirs (Maildirs within Maildirs),
Maildir++. It also supports VFAT-based Maildirs which use '!' or ';' as the
separators instead of ':'.
E-mail messages which are not stored in something resembling a maildir
leaf-directory (=cur= and =new=) are ignored, as are the cache directories for
=notmuch= and =gnus=, and any dot-directory.
Starting with mu 1.5.x, symlinks are followed, and can be spread over multiple
filesystems; however note that moving files around is much faster when multiple
filesystems are not involved.
If there is a file called =.noindex= in a directory, the contents of that
directory and all of its subdirectories will be ignored. This can be useful to
exclude certain directories from the indexing process, for example directories
with spam-messages.
If there is a file called =.noupdate= in a directory, the contents of that
directory and all of its subdirectories will be ignored, unless we do a full
rebuild (with *mu init*). This can be useful to speed up things you have some
maildirs that never change. Note that you can still search for these messages,
this only affects updating the database. =.noupdate= is ignored when you start
indexing with an empty database (such as directly after =mu init=.
There also the *--lazy-check* which can greatly speed up indexing; see below for
details.
The first run of *mu index* may take a few minutes if you have a lot of mail (tens
of thousands of messages). Fortunately, such a full scan needs to be done only
once; after that it suffices to index the changes, which goes much faster. See
the 'Note on performance (i,ii,iii)' below for more information.
The optional 'phase two' of the indexing-process is the removal of messages from
the database for which there is no longer a corresponding file in the Maildir.
If you do not want this, you can use ~-n~, ~--nocleanup~.
When *mu index* catches one of the signals *SIGINT*, *SIGHUP* or *SIGTERM* (e.g., when
you press Ctrl-C during the indexing process), it attempts to shutdown
gracefully; it tries to save and commit data, and close the database etc. If it
receives another signal (e.g., when pressing Ctrl-C once more), *mu index* will
terminate immediately.
* INDEX OPTIONS
** --lazy-check
in lazy-check mode, *mu* does not consider messages for which the time-stamp
(ctime) of the directory they reside in has not changed since the previous
indexing run. This is much faster than the non-lazy check, but won't update
messages that have change (rather than having been added or removed), since
merely editing a message does not update the directory time-stamp. Of course,
you can run *mu-index* occasionally without ~--lazy-check~, to pick up such
messages.
** --nocleanup
disable the database cleanup that *mu* does by default after indexing.
#+include: "muhome.inc" :minlevel 2
#+include: "common-options.inc" :minlevel 1
* PERFORMANCE
** indexing in ancient times (2009?)
As a non-scientific benchmark, a simple test on the author's machine (a Thinkpad
X61s laptop using Linux 2.6.35 and an ext3 file system) with no existing
database, and a maildir with 27273 messages:
#+begin_example
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
66,65s user 6,05s system 27% cpu 4:24,20 total
#+end_example
(about 103 messages per second)
A second run, which is the more typical use case when there is a database
already, goes much faster:
#+begin_example
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
0,48s user 0,76s system 10% cpu 11,796 total
#+end_example
(more than 56818 messages per second)
Note that each test flushes the caches first; a more common use case might be to
run *mu index* when new mail has arrived; the cache may stay quite 'warm' in that
case:
#+begin_example
$ time mu index --quiet
0,33s user 0,40s system 80% cpu 0,905 total
#+end_example
which is more than 30000 messages per second.
** indexing in 2012
As per June 2012, we did the same non-scientific benchmark, this time with an
Intel i5-2500 CPU @ 3.30GHz, an ext4 file system and a maildir with 22589
messages. We start without an existing database.
#+begin_example
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
27,79s user 2,17s system 48% cpu 1:01,47 total
#+end_example
(about 813 messages per second)
A second run, which is the more typical use case when there is a database
already, goes much faster:
#+begin_example
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
0,13s user 0,30s system 19% cpu 2,162 total
#+end_example
(more than 173000 messages per second)
** indexing in 2016
As per July 2016, we did the same non-scientific benchmark, again with the Intel
i5-2500 CPU @ 3.30GHz, an ext4 file system. This time, the maildir contains
72525 messages.
#+begin_example
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time mu index --quiet
40,34s user 2,56s system 64% cpu 1:06,17 total
#+end_example
(about 1099 messages per second).
** indexing in 2022
A few years later and it is June 2022. There's a lot more happening during
indexing, but indexing became multi-threaded and machines are faster; e.g. this
is with an AMD Ryzen Threadripper 1950X (16 cores) @ 3.399GHz.
The instructions are a little different since we have a proper repeatable
benchmark now. After building,
#+begin_example
$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
% THREAD_NUM=4 build/lib/tests/bench-indexer -m perf
# random seed: R02Sf5c50e4851ec51adaf301e0e054bd52b
1..1
# Start of bench tests
# Start of indexer tests
indexed 5000 messages in 20 maildirs in 3763ms; 752 μs/message; 1328 messages/s (4 thread(s))
ok 1 /bench/indexer/4-cores
# End of indexer tests
# End of bench tests
#+end_example
Things are again a little faster, even though the index does a lot more now
(text-normalizatian, and pre-generating message-sexps). A faster machine helps,
too!
#+include: "prefooter.inc"
* SEE ALSO
*maildir(5)*, *mu(1)*, *mu-init(1)*, *mu-find(1)*, *mu-cfind(1)*

47
man/mu-info.1
View File

@ -1,47 +0,0 @@
.TH MU-INFO 1 "May 2022" "User Manuals"
.SH NAME
mu info \- show information about the mu database
.SH SYNOPSIS
.B mu info [options]
.SH DESCRIPTION
\fBmu info\fR is the \fBmu\fR command for getting information about the mu
database. Note that while running (e.g. \fBmu4e\fR), some of the information
may be slightly delayed due to database caching.
.SH OPTIONS
Note, some of the general options are described in the \fBmu(1)\fR man-page and
not here, as they apply to multiple mu commands.
.TP
\fB\-\-muhome\fR
use an alternative directory to store and read the database, write the logs,
etc. By default, \fBmu\fR uses XDG Base Directory Specification (e.g. on Linux
this defaults to \fI~/.cache/mu\fR, \fI~/.config/mu\fR). Earlier versions of
\fBmu\fR defaulted to \fI~/.mu\fR, which now requires \fI\-\-muhome=~/.mu\fR.
.SH RETURN VALUE
\fBmu init\fR returns 0 upon successful completion, or a non-zero exit code if
there was some error.
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR maildir (5),
.BR mu (1),
.BR mu-index (1)

25
man/mu-info.1.org Normal file
View File

@ -0,0 +1,25 @@
#+title: MU-INFO
* NAME
~mu info~ - show information about the mu database
* SYNOPSIS
*mu [common options] info*
* DESCRIPTION
~mu info~ is the ~mu~ command for getting information about the mu database. Note
that while running (e.g. ~mu4e~), some of the information may be slightly delayed
due to database caching.
#+include: "common-options.inc" :minlevel 1
#+include: "exit-code.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*maildir(5)*, *mu(1)*

79
man/mu-init.1
View File

@ -1,79 +0,0 @@
.TH MU-INIT 1 "May 2022" "User Manuals"
.SH NAME
mu init \- initialize the mu message database
.SH SYNOPSIS
.B mu init [options]
.SH DESCRIPTION
\fBmu init\fR is the subcommand for setting up the mu message
database. After \fBmu init\fR has completed, you can run \fBmu
index\fR
.SH OPTIONS
Note, some of the general options are described in the \fBmu(1)\fR
man-page and not here, as they apply to multiple mu commands.
.TP
\fB\-\-muhome\fR
use an alternative directory to store and read the database, write the logs,
etc. By default, \fBmu\fR uses XDG Base Directory Specification (e.g. on Linux
this defaults to \fI~/.cache/mu\fR, \fI~/.config/mu\fR).
Earlier versions of \fBmu\fR defaulted to \fI~/.mu\fR, which now requires
\fI\-\-muhome=~/.mu\fR.
Alternatively, use can use the \fBMUHOME\fR environment variable (the command-line takes precedence).
.TP
\fB\-m\fR, \fB\-\-maildir\fR=\fI<maildir>\fR
starts searching at \fI<maildir>\fR. By default, \fBmu\fR uses whatever the
\fBMAILDIR\fR environment variable is set to; if it is not set, it tries
\fI~/Maildir\fR if it already exists.
.TP
\fB\-\-my-address\fR=\fI<my-email-address>\fR
specifies that some e-mail addresses are 'my-address' (\fB\-\-my-address\fR can
be used multiple times). This is used by \fBmu cfind\fR -- any e-mail address
found in the address fields of a message which also has \fI<my-email-address>\fR
in one of its address fields is considered a \fIpersonal\fR e-mail address. This
allows you, for example, to filter out (\fBmu cfind --personal\fR) addresses
which were merely seen in mailing list messages.
\fI<my-email-address>\fR can be either a plain e-mail address (such as
\fBfoo@example.com\fR), or a regular-expression (of the 'Basic POSIX' flavor),
wrapped in \fB/\fR (such as \fB/foo-.*@example\\.com/\fR). Depending on your
shell program, the argument may need to b quoted.
.SH ENVIRONMENT
\fBmu init\fR uses \fBMAILDIR\fR to find the user's Maildir if it has not been
specified explicitly with \fB\-\-maildir\fR=\fI<maildir>\fR. If \fBMAILDIR\fR is
not set, \fBmu init\fR uses \fI~/Maildir\fR.
\fBMUHOME\fR can be used as an alternative to \fB\-\-muhome\fR.
.SH RETURN VALUE
\fBmu init\fR returns 0 upon successful completion, or a non-zero exit code if
there was some error.
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR maildir (5),
.BR mu (1),
.BR mu-index (1)

42
man/mu-init.1.org Normal file
View File

@ -0,0 +1,42 @@
#+title: MU-INIT
* NAME
mu init -- initialize the mu message database
* SYNOPSIS
*mu [common-options] init [options]*
* DESCRIPTION
*mu init* is the subcommand for setting up the mu message database. After *mu init*
has completed, you can run *mu index*
* INIT OPTIONS
** -m, --maildir=<maildir>
starts searching at =<maildir>=. By default, *mu* uses whatever the *MAILDIR*
environment variable is set to; if it is not set, it tries =~/Maildir= if it
already exists.
** --my-address=<my-email-address>
specifies that some e-mail addresses are 'my-address' (the option can be used
multiple times). Any message in which at least one of the contact fields
contains such an address is considered a 'personal' messages; this can then be
used for filtering in *mu-find(1)*, *mu-cfind(1)* and *mu4e*, e.g. to filter-out
mailing list messages.
=<my-email-address>= can be either a plain e-mail address (such as
*foo@example.com*), or a regular-expression (of the 'Basic POSIX' flavor), wrapped
in */* (such as =/foo-.*@example\\.com/=). Depending on your shell, the argument may
need to b quoted.
#+include: "muhome.inc" :minlevel 2
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu-index(1)*, *mu-find(1)*, *mu-cfind(1)*

45
man/mu-mkdir.1
View File

@ -1,45 +0,0 @@
.TH MU MKDIR 1 "July 2012" "User Manuals"
.SH NAME
mu mkdir\- create a new Maildir
.SH SYNOPSIS
.B mu mkdir [options] <dir> [<dirs>]
.SH DESCRIPTION
\fBmu mkdir\fR is the \fBmu\fR command for creating Maildirs. It does
\fBnot\fR use the mu database. With the \fBmkdir\fR command, you can create
new Maildirs with permissions 0755. For example,
.nf
mu mkdir tom dick harry
.fi
creates three maildirs, \fItom\fR, \fIdick\fR and \fIharry\fR.
If creation fails for any reason, \fBno\fR attempt is made to remove any parts
that were created. This is for safety reasons.
.SH OPTIONS
.TP
\fB\-\-mode\fR=<mode>
set the file access mode for the new maildir(s) as in \fBchmod(1)\fR.
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR maildir (5),
.BR mu (1),
.BR chmod (1)

37
man/mu-mkdir.1.org Normal file
View File

@ -0,0 +1,37 @@
#+title: MU MKDIR
* NAME
*mu mkdir* - create a new Maildir
* SYNOPSIS
*mu [common-options] mkdir [options] <dir> [<dirs>]*
* DESCRIPTION
*mu mkdir* is the *mu* command for creating Maildirs. It does not* use the mu
*database. With the *mkdir* command, you can create new Maildirs with
*permissions 0755. For example,
#+begin_example
$ mu mkdir tom dick harry
#+end_example
creates three maildirs, =tom=, =dick= and =harry=.
If creation fails for any reason, *no* attempt is made to remove any parts that
were created. This is for safety reasons.
* MKDIR OPTIONS
** --mode=<mode>
set the file access mode for the new maildir(s) as in *chmod(1)*.
#+include: "common-options.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*maildir(5)*, *chmod(1)*

361
man/mu-query.7
View File

@ -1,361 +0,0 @@
.TH MU QUERY 7 "22 April 2022" "User Manuals"
.SH NAME
mu query language \- a language for finding messages in \fBmu\fR databases.
.SH DESCRIPTION
The mu query language is a language used by \fBmu find\fR and \fBmu4e\fR to find
messages in \fBmu\fR's Xapian databases. The language is quite similar to
Xapian's default query-parser, but is an independent implementation that is
customized for the mu/mu4e use-case.
In this article, we give a structured but informal overview of the query
language and provide examples.
As a companion to this, we recommend the \fBmu fields\fR and \fBmu flags\fR
commands to get an up-to-date list of the available fields and flags.
\fBNOTE:\fR if you use queries on the command-line (say, for \fBmu find\fR), you
need to quote any characters that would otherwise be interpreted by the shell,
such as \fB""\fR, \fB(\fR and \fB)\fR and whitespace.
.de EX1
.nf
.RS
..
.de EX2
.RE
.fi
..
.SH TERMS
The basic building blocks of a query are \fBterms\fR; these are just
normal words like 'banana' or 'hello', or words prefixed with a
field-name which make them apply to just that field. See
\fBmu find\fR
for all the available fields.
Some example queries:
.EX1
vacation
subject:capybara
maildir:/inbox
.EX2
Terms without an explicit field-prefix, (like 'vacation' above) are
interpreted like:
.EX1
to:vacation or subject:vacation or body:vacation or ...
.EX2
The language is case-insensitive for terms and attempts to 'flatten'
any diacritics, so \fIangtrom\fR matches \fIÅngström\fR.
.PP
If terms contain whitespace, they need to be quoted:
.EX1
subject:"hi there"
.EX2
This is a so-called \fIphrase query\fR, which means that we match
against subjects that contain the literal phrase "hi there".
Remember that you need to escape those quotes when using this from the
command-line:
.EX1
mu find subject:\\"hi there\\"
.EX2
.SH LOGICAL OPERATORS
We can combine terms with logical operators -- binary ones: \fBand\fR,
\fBor\fR, \fBxor\fR and the unary \fBnot\fR, with the conventional
rules for precedence and association, and are case-insensitive.
.PP
You can also group things with \fB(\fR and \fB)\fR, so you can do
things like:
.EX1
(subject:beethoven or subject:bach) and not body:elvis
.EX2
If you do not explicitly specify an operator between terms, \fBand\fR
is implied, so the queries
.EX1
subject:chip subject:dale
.EX2
.EX1
subject:chip AND subject:dale
.EX2
are equivalent. For readability, we recommend the second version.
Note that a \fIpure not\fR - e.g. searching for \fBnot apples\fR is
quite a 'heavy' query.
.SH REGULAR EXPRESSIONS AND WILDCARDS
The language supports matching regular expressions that follow
ECMAScript; for details, see
.BR http://www.cplusplus.com/reference/regex/ECMAScript/
Regular expressions must be enclosed in \fB//\fR. Some examples:
.EX1
subject:/h.llo/ # match hallo, hello, ...
subject:/
.EX2
Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the
former matches messages in the '/foo' maildir, while the latter
matches all messages in all maildirs that match 'foo', such
as '/foo', '/bar/cuux/foo', '/fooishbar' etc.
Wildcards are an older mechanism for matching where a term with a
rightmost \fB*\fR (and \fIonly\fR in that position) matches any term
that starts with the part before the \fB*\fR; they are supported for
backward compatibility and \fBmu\fR translates them to regular
expressions internally:
.EX1
foo*
.EX2
is equivalent to
.EX1
/foo.*/
.EX2
As a note of caution, certain wild-cards and regular expression can
take quite a bit longer than 'normal' queries.
.SH FIELDS
We already saw a number of search fields, such as \fBsubject:\fR and
\fBbody:\fR. For the full table, see \fBmu fields\fR.
.EX1
bcc,h Bcc (blind-carbon-copy) recipient(s)
body,b Message body
cc,c Cc (carbon-copy) recipient(s)
changed,k Last change to message file (range)
date,d Send date (range)
embed,e Search inside embedded text parts
file,j Attachment filename
flag,g Message Flags
from,f Message sender
list,v Mailing list (e.g. the List-Id value)
maildir,m Maildir
mime,y MIME-type of one or more message parts
msgid,i Message-ID
prio,p Message priority (\fIlow\fR, \fInormal\fR or \fIhigh\fR)
size,z Message size range
subject,s Message subject
tag,x Tags for the message
thread,w Thread a message belongs to
to,t To: recipient(s)
The \fBmu fields\fR command is recommended to get the latest version.
.EX2
The shortcut character can be used instead of the full name:
.EX1
f:foo@bar
.EX2
is the same as
.EX1
from:foo@bar
.EX2
For queries that are not one-off, we would recommend the longer name
for readability.
There are also the special fields \fBcontact:\fR, which matches all
contact-fields (\fIfrom\fR, \fIto\fR, \fIcc\fR and \fIbcc\fR), and
\fBrecip\fR, which matches all recipient-fields (\fIto\fR, \fIcc\fR
and \fIbcc\fR). Hence, for instance,
.EX1
contact:fnorb@example.com
.EX2
is equivalent to
.EX1
(from:fnorb@example.com or to:fnorb@example.com or
cc:from:fnorb@example.com or bcc:fnorb@example.com)
.EX2
.SH DATE RANGES
The \fBdate:\fR field takes a date-range, expressed as the lower and
upper bound, separated by \fB..\fR. Either lower or upper (but not
both) can be omitted to create an open range.
Dates are expressed in local time and using ISO-8601 format
(YYYY-MM-DD HH:MM:SS); you can leave out the right part, and \fBmu\fR
adds the rest, depending on whether this is the beginning or end of
the range (e.g., as a lower bound, '2015' would be interpreted as the
start of that year; as an upper bound as the end of the year).
You can use '/' , '.', '-' and 'T' to make dates more human readable.
Some examples:
.EX1
date:20170505..20170602
date:2017-05-05..2017-06-02
date:..2017-10-01T12:00
date:2015-06-01..
date:2016..2016
.EX2
You can also use the special 'dates' \fBnow\fR and \fBtoday\fR:
.EX1
date:20170505..now
date:today..
.EX2
Finally, you can use relative 'ago' times which express some time
before now and consist of a number followed by a unit, with units
\fBs\fR for seconds, \fBM\fR for minutes, \fBh\fR for hours, \fBd\fR
for days, \fBw\fR for week, \fBm\fR for months and \fBy\fR for years.
Some examples:
.EX1
date:3m..
date:2017.01.01..5w
.EX2
.SH SIZE RANGES
The \fBsize\fR or \fBz\fR field allows you to match \fIsize ranges\fR
-- that is, match messages that have a byte-size within a certain
range. Units (b (for bytes), K (for 1000 bytes) and M (for 1000 * 1000
bytes) are supported). Some examples:
.EX1
size:10k..2m
size:10m..
.EX2
.SH FLAG FIELDS
The \fBflag\fR/\fBg\fR field allows you to match message flags. The
following fields are available:
.EX1
a,attach Message with attachment
d,draft Draft Message
f,flagged Flagged
l,list Mailing-list message
n,new New message (in new/ Maildir)
p,passed Passed ('Handled')
r,replied Replied
s,seen Seen
t,trashed Marked for deletion
u,unread new OR NOT seen
x,encrypted Encrypted message
z,signed Signed message
.EX2
Some examples:
.EX1
flag:attach
flag:replied
g:x
.EX2
Encrypted messages may be signed as well, but this is only visible
after decrypting and thus, invisible to \fBmu\fR.
.SH PRIORITY FIELD
The message priority field (\fBprio:\fR) has three possible values:
\fBlow\fR, \fBnormal\fR or \fBhigh\fR. For instance, to match
high-priority messages:
.EX1
prio:high
.EX2
.SH MAILDIR
The Maildir field describes the directory path starting \fBafter\fR
the Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part.
So for example, if there's a message with the file name
\fI~/Maildir/lists/running/cur/1234.213:2,\fR, you could find it (and
all the other messages in the same maildir) with:
.EX1
maildir:/lists/running
.EX2
Note the starting '/'. If you want to match mails in the 'root'
maildir, you can do with a single '/':
.EX1
maildir:/
.EX2
If you have maildirs (or any fields) that include spaces, you need to
quote them, ie.
.EX1
maildir:"/Sent Items"
.EX2
Note that from the command-line, such queries must be quoted:
.EX1
mu find 'maildir:"/Sent Items"'
.EX2
.SH MORE EXAMPLES
Here are some simple examples of \fBmu\fR queries; you can make many
more complicated queries using various logical operators, parentheses
and so on, but in the author's experience, it's usually faster to find
a message with a simple query just searching for some words.
Find all messages with both 'bee' and 'bird' (in any field)
.EX1
bee AND bird
.EX2
Find all messages with either Frodo or Sam:
.EX1
Frodo OR Sam
.EX2
Find all messages with the 'wombat' as subject, and 'capybara' anywhere:
.EX1
subject:wombat and capybara
.EX2
Find all messages in the 'Archive' folder from Fred:
.EX1
from:fred and maildir:/Archive
.EX2
Find all unread messages with attachments:
.EX1
flag:attach and flag:unread
.EX2
Find all messages with PDF-attachments:
.EX1
mime:application/pdf
.EX2
Find all messages with attached images:
.EX1
mime:image/*
.EX2
.SH CAVEATS
With current Xapian versions, the apostroph character is considered part of a
word. Thus, you cannot find \fID'Artagnan\fR by searching for \fIArtagnan\fR.
So, include the apostroph in search or use a regexp search.
Matching on spaces has changed compared to the old query-parser; this applies
e.g. to Maildirs that have spaces in their name, such as \fISent Items\fR. See
\fBMAILDIR\fR above.
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu-find (1)
.BR mu-fields (1)

334
man/mu-query.7.org Normal file
View File

@ -0,0 +1,334 @@
#+title: MU QUERY
* NAME
mu query language -- a language for finding messages in *mu* databases.
* DESCRIPTION
The mu query language is a language used by *mu find* and *mu4e* to find messages in
*mu*'s Xapian databases. The language is quite similar to Xapian's default
query-parser, but is an independent implementation that is customized for the
mu/mu4e use-case.
In this article, we give a structured but informal overview of the query
language and provide examples.
As a companion to this, we recommend the *mu fields* and *mu flags* commands to get
an up-to-date list of the available fields and flags.
*NOTE:* if you use queries on the command-line (say, for *mu find*), you need to
quote any characters that would otherwise be interpreted by the shell, such as
*""*, *(* and *)* and whitespace.
* TERMS
The basic building blocks of a query are *terms*; these are just normal words like
'banana' or 'hello', or words prefixed with a field-name which make them apply
to just that field. See *mu find* for all the available fields.
Some example queries:
#+begin_example
vacation
subject:capybara
maildir:/inbox
#+end_example
Terms without an explicit field-prefix, (like 'vacation' above) are interpreted
like:
#+begin_example
to:vacation or subject:vacation or body:vacation or ...
#+end_example
The language is case-insensitive for terms and attempts to 'flatten' any
diacritics, so =angtrom= matches =Ångström=.
If terms contain whitespace, they need to be quoted:
#+begin_example
subject:"hi there"
#+end_example
This is a so-called =phrase query=, which means that we match against subjects
that contain the literal phrase "hi there".
Remember that you need to escape those quotes when using this from the
command-line:
#+begin_example
mu find subject:\\"hi there\\"
#+end_example
* LOGICAL OPERATORS
We can combine terms with logical operators -- binary ones: *and*, *or*, *xor* and the
unary *not*, with the conventional rules for precedence and association, and are
case-insensitive.
You can also group things with *(* and *)*, so you can do things like:
#+begin_example
(subject:beethoven or subject:bach) and not body:elvis
#+end_example
If you do not explicitly specify an operator between terms, *and* is implied, so
the queries
#+begin_example
subject:chip subject:dale
#+end_example
#+begin_example
subject:chip AND subject:dale
#+end_example
are equivalent. For readability, we recommend the second version.
Note that a =pure not= - e.g. searching for *not apples* is quite a 'heavy' query.
* REGULAR EXPRESSIONS AND WILDCARDS
The language supports matching regular expressions that follow ECMAScript; for
details, see http://www.cplusplus.com/reference/regex/ECMAScript/
Regular expressions are enclosed in *//*. Some examples:
#+begin_example
subject:/h.llo/ # match hallo, hello, ...
subject:/
#+end_example
Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the former
matches messages in the '/foo' maildir, while the latter matches all messages in
all maildirs that match 'foo', such as '/foo', '/bar/cuux/foo', '/fooishbar'
etc.
Wildcards are an older mechanism for matching where a term with a rightmost ***
(and =only= in that position) matches any term that starts with the part before
the ***; they are supported for backward compatibility and *mu* translates them to
regular expressions internally:
#+begin_example
foo*
#+end_example
is equivalent to
#+begin_example
/foo.*/
#+end_example
As a note of caution, certain wild-cards and regular expression can take quite a
bit longer than 'normal' queries.
* FIELDS
We already saw a number of search fields, such as *subject:* and *body:*. For the
full table, see *mu-fields(1)*.
#+begin_example
bcc,h Bcc (blind-carbon-copy) recipient(s)
body,b Message body
cc,c Cc (carbon-copy) recipient(s)
changed,k Last change to message file (range)
date,d Send date (range)
embed,e Search inside embedded text parts
file,j Attachment filename
flag,g Message Flags
from,f Message sender
list,v Mailing list (e.g. the List-Id value)
maildir,m Maildir
mime,y MIME-type of one or more message parts
msgid,i Message-ID
prio,p Message priority (=low=, =normal= or =high=)
size,z Message size range
subject,s Message subject
tag,x Tags for the message
thread,w Thread a message belongs to
to,t To: recipient(s)
#+end_example
The shortcut character can be used instead of the full name:
#+begin_example
f:foo@bar
#+end_example
is the same as
#+begin_example
from:foo@bar
#+end_example
For queries that are not one-off, we would recommend the longer name
for readability.
There are also the special fields *contact:*, which matches all contact-fields
(=from=, =to=, =cc= and =bcc=), and *recip*, which matches all recipient-fields (=to=, =cc=
and =bcc=). Hence, for instance,
#+begin_example
contact:fnorb@example.com
#+end_example
is equivalent to
#+begin_example
(from:fnorb@example.com or to:fnorb@example.com or
cc:from:fnorb@example.com or bcc:fnorb@example.com)
#+end_example
* DATE RANGES
The *date:* field takes a date-range, expressed as the lower and upper bound,
separated by *..*. Either lower or upper (but not both) can be omitted to create
an open range.
Dates are expressed in local time and using ISO-8601 format (YYYY-MM-DD
HH:MM:SS); you can leave out the right part, and *mu* adds the rest, depending on
whether this is the beginning or end of the range (e.g., as a lower bound,
'2015' would be interpreted as the start of that year; as an upper bound as the
end of the year).
You can use '/' , '.', '-' and 'T' to make dates more human readable.
Some examples:
#+begin_example
date:20170505..20170602
date:2017-05-05..2017-06-02
date:..2017-10-01T12:00
date:2015-06-01..
date:2016..2016
#+end_example
You can also use the special 'dates' *now* and *today*:
#+begin_example
date:20170505..now
date:today..
#+end_example
Finally, you can use relative 'ago' times which express some time before now and
consist of a number followed by a unit, with units *s* for seconds, *M* for minutes,
*h* for hours, *d* for days, *w* for week, *m* for months and *y* for years. Some
examples:
#+begin_example
date:3m..
date:2017.01.01..5w
#+end_example
* SIZE RANGES
The *size* or *z* field allows you to match =size ranges= -- that is, match messages
that have a byte-size within a certain range. Units (b (for bytes), K (for 1000
bytes) and M (for 1000 * 1000 bytes) are supported). Some examples:
#+begin_example
size:10k..2m
size:10m..
#+end_example
* FLAG FIELD
The *flag/g* field allows you to match message flags. The following fields are
available:
#+begin_example
a,attach Message with attachment
d,draft Draft Message
f,flagged Flagged
l,list Mailing-list message
n,new New message (in new/ Maildir)
p,passed Passed ('Handled')
r,replied Replied
s,seen Seen
t,trashed Marked for deletion
u,unread new OR NOT seen
x,encrypted Encrypted message
z,signed Signed message
#+end_example
Some examples:
#+begin_example
flag:attach
flag:replied
g:x
#+end_example
Encrypted messages may be signed as well, but this is only visible after
decrypting and thus invisible to *mu*.
* PRIORITY FIELD
The message priority field (*prio:*) has three possible values: *low*, *normal* or
*high*. For instance, to match high-priority messages:
#+begin_example
prio:high
#+end_example
* MAILDIR
The Maildir field describes the directory path starting *after* the Maildir-base
path, and before the =/cur/= or =/new/= part. So for example, if there's a message
with the file name =~/Maildir/lists/running/cur/1234.213:2,=, you could find it
(and all the other messages in the same maildir) with:
#+begin_example
maildir:/lists/running
#+end_example
Note the starting '/'. If you want to match mails in the 'root' maildir, you can
do with a single '/':
#+begin_example
maildir:/
#+end_example
If you have maildirs (or any fields) that include spaces, you need to quote
them, ie.
#+begin_example
maildir:"/Sent Items"
#+end_example
Note that from the command-line, such queries must be quoted:
#+begin_example
mu find 'maildir:"/Sent Items"'
#+end_example
* MORE EXAMPLES
Here are some simple examples of *mu* queries; you can make many more complicated
queries using various logical operators, parentheses and so on, but in the
author's experience, it's usually faster to find a message with a simple query
just searching for some words.
Find all messages with both 'bee' and 'bird' (in any field)
#+begin_example
bee AND bird
#+end_example
Find all messages with either Frodo or Sam:
#+begin_example
Frodo OR Sam
#+end_example
Find all messages with the 'wombat' as subject, and 'capybara' anywhere:
#+begin_example
subject:wombat and capybara
#+end_example
Find all messages in the 'Archive' folder from Fred:
#+begin_example
from:fred and maildir:/Archive
#+end_example
Find all unread messages with attachments:
#+begin_example
flag:attach and flag:unread
#+end_example
Find all messages with PDF-attachments:
#+begin_example
mime:application/pdf
#+end_example
Find all messages with attached images:
#+begin_example
mime:image/*
#+end_example
* CAVEATS
With current Xapian versions, the apostroph character is considered part of a
word. Thus, you cannot find =D'Artagnan= by searching for =Artagnan=. So, include
the apostroph in search or use a regexp search.
Matching on spaces has changed compared to the old query-parser; this applies
e.g. to Maildirs that have spaces in their name, such as =Sent Items=. See *MAILDIR*
above.
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu-find(1)*, *mu-fields(1)*

48
man/mu-remove.1
View File

@ -1,48 +0,0 @@
.TH MU REMOVE 1 "May 2022" "User Manuals"
.SH NAME
\fBmu remove\fR is the \fBmu\fR command to remove messages from the database.
.SH SYNOPSIS
.B mu remove [options] <file> [<files>]
.SH DESCRIPTION
\fBmu remove\fR removes specific messages from the database, each of them
specified by their filename. The files do not have to exist in the file
system.
.SH OPTIONS
\fBmu remove\fR does not have its own options, but the general options for
determining the location of the database (\fI--muhome\fR) are available. See
\fBmu-index(1)\fR for more information.
.SH RETURN VALUE
\fBmu remove\fR returns 0 upon success; in general, the following error codes are
returned:
.nf
| code | meaning |
|------+-----------------------------------|
| 0 | ok |
| 1 | general error |
.fi
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1),
.BR mu-index (1),
.BR mu-add (1)

26
man/mu-remove.1.org Normal file
View File

@ -0,0 +1,26 @@
#+title: MU REMOVE
* NAME
*mu remove* - command to remove messages from the database.
* SYNOPSIS
*mu [common-options] remove [options] <file> [<files>]*
* DESCRIPTION
*mu remove* removes specific messages from the database, each of them specified by
their filename. The files do not have to exist in the file system.
* REMOVE OPTIONS
#+include: "muhome.inc" :minlevel 2
#+include: "common-options.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-add(1)*

84
man/mu-script.1
View File

@ -1,84 +0,0 @@
.TH MU SCRIPT 1 "October 2021" "User Manuals"
.SH NAME
mu script\- show the available mu scripts, and/or run them.
.SH SYNOPSIS
.B mu script [options] [<pattern>]
.B mu <script-name> [<script-options>]
.SH DESCRIPTION
\fBmu script\fR is the \fBmu\fR command to list available \fBmu\fR scripts.
The scripts are to be implemented in the Guile programming language, and
therefore only work if your \fBmu\fR is built with support for Guile. In
addition, many scripts require you to have \fBgnuplot\fR installed.
Without any parameters, \fBmu script\fR lists the available scripts. If you
provide a pattern (a regular expression), only the scripts whose name or
one-line description match this pattern are listed. See the examples below.
\fBmu\fR ships with a number of scripts.
.SH OPTIONS
.TP
\fB\-\-verbose\fR,\fB\-v\fR
when listing the available scripts, show the long descriptions.
\fB\-\-\fR
all options on the right side of the \fB\-\-\fR are passed to the script.
.SH EXAMPLES
List all available scripts (one-line descriptions):
.nf
$ mu script
.fi
List all available scripts matching \fImonth\fR (long descriptions):
.nf
$ mu script -v month
.fi
Run the \fImsgs-per-month\fR script for messages matching 'hello', and pass it
the \fI--textonly\fR parameter:
.nf
$ mu msgs-per-month --query=hello --textonly
.fi
.SH RETURN VALUE
\fBmu script\fR returns 0 when all went well, and returns some non-zero error
code when this is not the case.
.SH FILES
You can make your own Scheme scripts accessible through \fBmu script\fR by
putting them in either \fI<XDG_DATA_HOME>/mu/scripts\fR (e.g., \fI~/.local/share/mu/scripts\fR) or, if \fImuhome\fR is specified, in
It is a good idea to document the scripts by using some
special comments in the source code:
.nf
;; INFO: this is my script -- one-line description
;; INFO: (longer description)
;; INFO: --option1=<foo> (describe option1)
;; INFO: etc.
.fi
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1),
.BR guile (1)

61
man/mu-server.1
View File

@ -1,61 +0,0 @@
.TH MU-SERVER 1 "January 2020" "User Manuals"
.SH NAME
mu server \- the mu backend for the mu4e e-mail client
.SH SYNOPSIS
.B mu server [options]
.SH DESCRIPTION
\fBmu server\fR starts a simple shell in which one can query and manipulate the
mu database. The output uses s-expressions. \fBmu server\fR is not meant for use
by humans, except for debugging purposes. Instead, it is designed specifically
for the \fBmu4e\fR e-mail client.
In this man-page, we document the commands \fBmu server\fR accepts, as well as
their responses. In general, the commands sent to the server are s-expressions
of the form:
.nf
(<command-name> :param1 value1 :param2 value2)
.fi
For example, to view a certain message, the command would be:
.nf
(view :docid 12345)
.fi
Parameters can be sent in any order; they must be of the correct type though.
See \fBlib/utils/mu-sexp-parser.hh\fR and \fBlib/utils/mu-sexp-parser.cc\fR in
source-tree for the details.
.SH OUTPUT FORMAT
\fBmu server\fR accepts a number of commands, and delivers its results in
the form:
.nf
\\376<length>\\377<s-expr>
.fi
\\376 (one byte 0xfe), followed by the length of the s-expression expressed as
an hexadecimal number, followed by another \\377 (one byte 0xff), followed by
the actual s-expression.
By prefixing the expression with its length, it can be processed more
efficiently. The \\376 and \\377 were chosen since they never occur in valid
UTF-8 (in which the s-expressions are encoded).
.sh COMMANDS
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1)

69
man/mu-server.1.org Normal file
View File

@ -0,0 +1,69 @@
#+title: MU-SERVER
* NAME
mu server - the mu backend for the mu4e e-mail client
* SYNOPSIS
mu [common-options] server
* DESCRIPTION
*mu server* starts a simple shell in which one can query and manipulate the mu
database. The output uses s-expressions. *mu server* is not meant for use by
humans, except for debugging purposes. Instead, it is designed specifically for
the *mu4e* e-mail client.
In this man-page, we document the commands *mu server* accepts, as well as their
responses. In general, the commands sent to the server are s-expressions of the
form:
#+begin_example
(<command-name> :param1 value1 :param2 value2)
#+end_example
For example, to view a certain message, the command would be:
#+begin_example
(view :docid 12345)
#+end_example
Parameters can be sent in any order; they must be of the correct type though.
See *lib/utils/mu-sexp-parser.hh* and *lib/utils/mu-sexp-parser.cc* in source-tree
for the details.
* OUTPUT FORMAT
*mu server* accepts a number of commands, and delivers its results in the form:
#+begin_example
\\376<length>\\377<s-expr>
#+end_example
\\376 (one byte 0xfe), followed by the length of the s-expression expressed as
an hexadecimal number, followed by another \\377 (one byte 0xff), followed by
the actual s-expression.
By prefixing the expression with its length, it can be processed more
efficiently. The \\376 and \\377 were chosen since they never occur in valid
UTF-8 (in which the s-expressions are encoded).
* SERVER OPTIONS
** --commands
List available commands (and try with ~--verbose~)
** --eval <expression>
Evaluate a mu4e server s-expression
#+include: "muhome.inc" :minlevel 2
#+include: "common-options.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu(1)*

69
man/mu-verify.1
View File

@ -1,69 +0,0 @@
.TH MU VERIFY 1 "April 2022" "User Manuals"
.SH NAME
mu verify\- verify message signatures and display information about them
.SH SYNOPSIS
.B mu verify [options] <msgfile>
.SH DESCRIPTION
\fBmu verify\fR is the \fBmu\fR command for verifying message signatures (such
as PGP/GPG signatures) and displaying information about them. The sub-command
works on message files, and does not require the message to be indexed in the
database.
.SH OPTIONS
.TP
\fB\-r\fR, \fB\-\-auto\-retrieve\fR
attempt to find keys online (see the \fBauto-key-retrieve\fR option in the
\fBgnupg(1)\fR documentation).
.SH EXAMPLES
To display aggregated (one-line) information about the verification status in a
message:
.nf
$ mu verify msgfile
.fi
To display information about all the signatures:
.nf
$ mu verify --verbose msgfile
.fi
If you only want to use the exit code, you can use:
.nf
$ mu verify --quiet msgfile
.fi
which does not give any output unless there is an error.
.SH RETURN VALUE
\fBmu verify\fR returns 0 when all signatures could be verified to be good, and
returns some non-zero error code when this is not the case.
When there are no signatures, returns 0 as well.
.nf
| code | meaning |
|------+--------------------------------|
| 0 | ok |
| 1 | some non-verified signature(s) |
.fi
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1)

51
man/mu-verify.1.org Normal file
View File

@ -0,0 +1,51 @@
#+title: MU VERIFY
* NAME
mu verify - verify message signatures and display information about them
* SYNOPSIS
*mu [common-options] verify [options] <msgfile>*
* DESCRIPTION
*mu verify* is the *mu* command for verifying message signatures (such as PGP/GPG
signatures) and displaying information about them. The sub-command works on
message files, and does not require the message to be indexed in the database.
* VERIFY OPTIONS
** -r, --auto-retrieve
attempt to find keys online (see the *auto-key-retrieve* option in the *gnupg(1)*
documentation).
** decrypt
attempt to decrypt the message
#+include: "common-options.inc" :minlevel 1
* EXAMPLES
To display aggregated (one-line) information about the verification status in a
message:
#+begin_example
$ mu verify msgfile
#+end_example
To display information about all the signatures:
#+begin_example
$ mu verify --verbose msgfile
#+end_example
If you only want to use the exit code, you can use:
#+begin_example
$ mu verify --quiet msgfile
#+end_example
which does not give any output unless there is an error.
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu(1)*

53
man/mu-view.1
View File

@ -1,53 +0,0 @@
.TH MU VIEW 1 "April 2022" "User Manuals"
.SH NAME
mu view\- display an e-mail message file
.SH SYNOPSIS
.B mu view [options] <file> [<files>]
.SH DESCRIPTION
\fBmu view\fR is the \fBmu\fR command for displaying e-mail message files. It
works on message files and does \fInot\fR require the message to be indexed in
the database.
The command shows some common headers (From:, To:, Cc:, Bcc:, Subject: and
Date:), the list of attachments and the plain-text body of the message (if
any).
.SH OPTIONS
.TP
\fB\-\-summary-len\fR=\fI<number>\fR
instead of displaying the full message, output a summary based upon the first
\fI<number>\fR lines of the message.
.TP
\fB\-\-terminate\fR
terminate messages with \\f (\fIform-feed\fR) characters when displaying
them. This is useful when you want to further process them.
.TP
\fB\-\-decrypt\fR
attempt to decrypt encrypted message bodies. This is only possible if \fBmu\fR
was built with crypto-support.
.TP
\fB\-\-auto-retrieve\fR
attempt to retrieve crypto-keys automatically from the network, when needed.
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu (1)

42
man/mu-view.1.org Normal file
View File

@ -0,0 +1,42 @@
#+title: MU VIEW
* NAME
mu view - display an e-mail message file
* SYNOPSIS
mu [common options] view [options] <file> [<files>]
* DESCRIPTION
*mu view* is the *mu* command for displaying e-mail message files. It works on
message files and does =not= require the message to be indexed in the database.
The command shows some common headers (From:, To:, Cc:, Bcc:, Subject: and
Date:), the list of attachments and the plain-text body of the message (if any).
* VIEW OPTIONS
** --summary-len=<number>
instead of displaying the full message, output a summary based upon the first
=<number>= lines of the message.
** --terminate
terminate messages with \\f (=form-feed=) characters when displaying them. This is
useful when you want to further process them.
** --decrypt
attempt to decrypt encrypted message bodies. This is only possible if *mu*
was built with crypto-support.
** --auto-retrieve
attempt to retrieve crypto-keys automatically from the network, when needed.
#+include: "common-options.inc" :minlevel 1
* BUGS
* SEE ALSO
*mu(1)*

188
man/mu.1
View File

@ -1,188 +0,0 @@
.TH MU 1 "May 2022" "User Manuals"
.SH NAME
mu \- a set of tools to deal with Maildirs and message files, in particular to
index and search e-mail messages.
.SH SYNOPSIS
In alphabetical order:
.B mu [options]
general mu command.
.B mu add
add specific messages to the database. See
.BR mu-add(1)
.B mu cfind [options] [<regexp>]
find contacts. See
.BR mu-cfind(1)
.B mu extract [options] <file> [<parts>] [<regexp>]
extract attachments and other MIME-parts. See
.BR mu-extract(1)
.B mu find [options] <search expression>
find messages. See
.BR mu-find(1)
.B mu help [command]
get help for some command. See
.BR mu-help(1)
.B mu index [options]
(re)index the messages in a Maildir. See
.BR mu-index(1)
.B mu info [options]
show information about the mu database
.BR mu-info(1)
.B mu init [options]
initialize the mu database
.BR mu-init(1)
.B mu mkdir [options] <dir> [<dirs>]
create a new Maildir. See
.BR mu-mkdir(1)
.B mu remove [options]
remove specific messages from the database. See
.BR mu-remove(1)
.B mu script [options]
run a mu (Guile) script. See
.BR mu-script(1)
.B mu server [options]
start a server process (for \fBmu4e\fR-internal use). See
.BR mu-server(1)
.B mu view <file> [<files>]
view a specific message. See
.BR mu-view(1)
.SH DESCRIPTION
\fBmu\fR is a set of tools for dealing with Maildirs and the e-mail messages
in them.
\fBmu\fR's main purpose is to enable searching of e-mail messages. It
does so by periodically scanning a Maildir directory tree and
analyzing the e-mail messages found (this is called 'indexing'). The
results of this analysis are stored in a database, which can then be
queried.
In addition to indexing and searching, \fBmu\fR also offers
functionality for viewing messages, extracting attachments and
creating maildirs, and searching and exporting contact information.
\fBmu\fR can be used from the command line or can be integrated with various
e-mail clients.
This manpage gives a general overview of the available commands
(\fBindex\fR, \fBfind\fR, etc.); each \fBmu\fR command has its own
man-page as well.
.SH COLORS
Some \fBmu\fR sub-commands support colorized output, and do so by
default. If you don't want colors, you can use \fI--nocolor\fR.
Currently, \fBmu find\fR, \fBmu view\fR, \fBmu cfind\fR and \fBmu extract\fR
support colors.
.SH ENCODING
\fBmu\fR's output is in the current locale, with the exceptions of the output
specifically meant for output to UTF8-encoded files. In practice, this means
that the output of commands \fBindex\fR, \fBview\fR,
\fBextract\fR is always encoded according to the current locale.
The same is true for \fBfind\fR and \fBcfind\fR, with some exceptions, where
the output is always UTF-8, regardless of the locale.
For \fBcfind\fR the exception is \fI--format=bbdb\fR. This is hard-coded to
UTF-8, and as such specified in the output-file, so emacs/bbdb can handle it
correctly without guessing.
For \fBfind\fR the output is encoded according the locale for
\fI--format=plain\fR (the default), and UTF-8 for all other formats
(\fIjson\fR, \fIsexp\fR, \fIxml\fR).
.SH DATABASE AND FILE
Commands \fBmu index\fR and \fBfind\fR and \fBcfind\fR work with the database,
while the other ones work on individual mail files. Hence, running \fBview\fR,
\fBmkdir\fR and \fBextract\fR does not require the mu database.
The various commands are discussed in more detail in their own separate
man-pages; here the general options are discussed.
.SH OPTIONS
\fBmu\fR offers several general options that apply to all commands,
including \fBmu\fR without any command.
.TP
\fB\-\-muhome\fR
use an alternative directory to store and read the database, write the logs,
etc. By default, \fBmu\fR uses XDG Base Directory Specification (e.g. on Linux
by default \fI~/.cache/mu\fR, \fI~/.config/mu\fR). Earlier versions of \fBmu\fR defaulted
to \fI~/.mu\fR, which now requires \fI\-\-muhome=~/.mu\fR.
.TP
\fB\-d\fR, \fB\-\-debug\fR
makes \fBmu\fR generate extra debug information,
useful for debugging the program itself. By default, debug information goes to
the log file, \fI~/.cache/mu/mu.log\fR. It can safely be deleted when \fBmu\fR is
not running. When running with \fB--debug\fR option, the log file can grow
rather quickly. See the note on logging below.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
causes \fBmu\fR not to output informational
messages and progress information to standard output, but only to the log
file. Error messages will still be sent to standard error. Note that \fBmu
index\fR is \fBmuch\fR faster with \fB\-\-quiet\fR, so it is recommended you
use this option when using \fBmu\fR from scripts etc.
.TP
\fB\-\-log-stderr\fR
causes \fBmu\fR to \fBnot\fR output log messages to standard error, in
addition to sending them to the log file.
.TP
\fB\-V\fR, \fB\-\-version\fR
prints \fBmu\fR version and copyright information.
.TP
\fB\-h\fR, \fB\-\-help\fR
lists the various command line options.
.SH ENVIRONMENT
\fBMUHOME\fR can be used as an alternative to \fB\-\-muhome\fR. The latter has precedence.
\fBNO_COLOR\fR can be used as an alternative to \fB\-\-nocolor\fR.
.SH ERROR CODES
The various mu subcommands typically exit with 0 (zero) upon success, and
non-zero when some error occurred.
.SH BUGS
Please report bugs if you find them:
.BR https://github.com/djcb/mu/issues
.SH AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
.SH "SEE ALSO"
.BR mu-index (1), mu-find (1), mu-cfind (1), mu-mkdir (1), mu-view (1),
.BR mu-extract (1), mu-easy (1), mu-bookmarks (5), mu-query (7)
.BR https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

89
man/mu.1.org Normal file
View File

@ -0,0 +1,89 @@
#+title: MU
* NAME
~mu~ - a set of tools to deal with Maildirs and message files, in particular to
index and search e-mail messages.
* SYNOPSIS
~mu~ [COMMON-OPTIONS] [[COMMAND] [COMMAND-OPTIONS]]
For information about the commmon options, see *COMMON OPTIONS*.
* DESCRIPTION
~mu~ is the general command shows help about the specific commands:
- ~add~: add specific messages to the database.
- ~cfind~: find contacts
- ~extract~: extract attachments and other MIME-parts
- ~find~: find messages in the database
- ~help~: get help for some command
- ~index~: (re)index the messages in a Maildir
- ~info~: show information about the mu database
- ~init~: initialize the mu database
- ~mkdir~: create a new Maildir
- ~remove~: remove specific messages from the database
- ~server~: start a server process (for ~mu4e~-internal use)
- ~view~: view a specific message
Each of the commands have their own manpage ~mu-<command~>~.
~mu~ is a set of tools for dealing with Maildirs and the e-mail messages
in them.
~mu~'s main purpose is to enable searching of e-mail messages. It
does so by periodically scanning a Maildir directory tree and
analyzing the e-mail messages found (this is called 'indexing'). The
results of this analysis are stored in a database, which can then be
queried.
In addition to indexing and searching, ~mu~ also offers
functionality for viewing messages, extracting attachments and
creating maildirs, and searching and exporting contact information.
~mu~ can be used from the command line or can be integrated with various
e-mail clients.
This manpage gives a general overview of the available commands
(~index~, ~find~, etc.); each ~mu~ command has its own
man-page as well.
* COLORS
Some ~mu~ commands support colorized output, and do so by default. If you don't
want colors, you can use ~--nocolor~.
* ENCODING
~mu~'s output is in the current locale, with the exceptions of the output
specifically meant for output to UTF8-encoded files. In practice, this means
that the output of commands ~index~, ~view~, ~extract~ is always encoded according to
the current locale.
The same is true for ~find~ and ~cfind~, with some exceptions, where
the output is always UTF-8, regardless of the locale:
- For ~cfind~ the exception is ~--format=bbdb~. This is hard-coded to UTF-8, and as
such specified in the output-file, so emacs/bbdb can handle it correctly
without guessing.
- For ~find~ the output is encoded according the locale for ~--format=plain~ (the
default), and UTF-8 for all other formats.
* DATABASE AND FILE
Commands ~mu index~ and ~find~ and ~cfind~ work with the database, while the other
ones work on individual mail files. Hence, running ~view~, ~mkdir~ and ~extract~ does
not require the mu database.
#+include: "common-options.inc" :minlevel 1
#+include: "exit-code.inc" :minlevel 1
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
~mu-add(1)~, ~mu-cfind(1)~, ~mu-extract(1)~, ~mu-find(1)~, ~mu-help(1)~, ~mu-index(1)~,
~mu-info(1)~, ~mu-init(1)~, ~mu-mkdir(1)~, ~mu-remove(1)~, ~mu-server(1)~, ~mu-view(1)~,
~mu-query(7)~, ~mu-easy(1)~

12
man/muhome.inc Normal file
View File

@ -0,0 +1,12 @@
** --muhome
use a non-default directory to store and read the database, write the logs, etc.
By default, ~mu~ uses the XDG Base Directory Specification (e.g. on GNU/Linux this
defaults to =~/.cache/mu= and =~/.config/mu=). Earlier versions of ~mu~ defaulted to
=~/.mu=, which now requires =--muhome=~/.mu=.
The environment variable ~MUHOME~ can be used as an alternative to ~--muhome~. The
latter has precedence.
# Local Variables:
# mode: org
# End:

9
man/prefooter.inc Normal file
View File

@ -0,0 +1,9 @@
#+include: "bugs.inc" :minlevel 1
#+include: "author.inc" :minlevel 1
#+include: "copyright.inc" :minlevel 1
# Local Variables:
# mode: org
# End:

9
meson.build
View File

@ -190,10 +190,17 @@ install_data('NEWS.org',
# subdirs
subdir('lib')
subdir('mu')
subdir('man')
if emacs.found()
subdir('man')
else
message('emacs not found; not generating manpages')
endif
if emacs.found()
subdir('mu4e')
else
message('emacs not found; not preparing mu4e support')
endif
if not get_option('guile').disabled() and guile_dep.found()