Next: Mail Folders, Previous: MH Spool, Up: Choosing a Mail Back End
nnmaildir stores mail in the maildir format, with each maildir
corresponding to a group in Gnus. This format is documented here:
http://cr.yp.to/proto/maildir.html and here:
http://www.qmail.org/man/man5/maildir.html. nnmaildir
also stores extra information in the .nnmaildir/ directory
within a maildir.
Maildir format was designed to allow concurrent deliveries and
reading, without needing locks. With other back ends, you would have
your mail delivered to a spool of some kind, and then you would
configure Gnus to split mail from that spool into your groups. You
can still do that with nnmaildir, but the more common
configuration is to have your mail delivered directly to the maildirs
that appear as group in Gnus.
nnmaildir is designed to be perfectly reliable: C-g will
never corrupt its data in memory, and SIGKILL will never
corrupt its data in the filesystem.
nnmaildir stores article marks and NOV data in each
maildir. So you can copy a whole maildir from one Gnus setup to
another, and you will keep your marks.
Virtual server settings:
directorynnmaildir servers (it's very unlikely that
you'd need more than one), you need to create a directory and populate
it with maildirs or symlinks to maildirs (and nothing else; do not
choose a directory already used for other purposes). Each maildir
will be represented in Gnus as a newsgroup on that server; the
filename of the symlink will be the name of the group. Any filenames
in the directory starting with `.' are ignored. The directory is
scanned when you first start Gnus, and each time you type g in
the group buffer; if any maildirs have been removed or added,
nnmaildir notices at these times.
The value of the directory parameter should be a Lisp form
which is processed by eval and expand-file-name to get
the path of the directory for this server. The form is evaled
only when the server is opened; the resulting string is used until the
server is closed. (If you don't know about forms and eval,
don't worry—a simple string will work.) This parameter is not
optional; you must specify it. I don't recommend using
"~/Mail" or a subdirectory of it; several other parts of Gnus
use that directory by default for various things, and may get confused
if nnmaildir uses it too. "~/.nnmaildir" is a typical
value.
target-prefixeval and
expand-file-name. The form is evaled only when the
server is opened; the resulting string is used until the server is
closed.
When you create a group on an nnmaildir server, the maildir is
created with target-prefix prepended to its name, and a symlink
pointing to that maildir is created, named with the plain group name.
So if directory is "~/.nnmaildir" and
target-prefix is "../maildirs/", then when you create
the group foo, nnmaildir will create
~/.nnmaildir/../maildirs/foo as a maildir, and will create
~/.nnmaildir/foo as a symlink pointing to
../maildirs/foo.
You can set target-prefix to a string without any slashes to
create both maildirs and symlinks in the same directory; in
this case, any maildirs found in directory whose names start
with target-prefix will not be listed as groups (but the
symlinks pointing to them will be).
As a special case, if target-prefix is "" (the default),
then when you create a group, the maildir will be created in
directory without a corresponding symlink. Beware that you
cannot use gnus-group-delete-group on such groups without the
force argument.
directory-filesdirectory-files (such as directory-files itself). It is
used to scan the server's directory for maildirs. This
parameter is optional; the default is
nnheader-directory-files-safe if
nnheader-directory-files-is-safe is nil, and
directory-files otherwise.
(nnheader-directory-files-is-safe is checked only once when the
server is opened; if you want to check it each time the directory is
scanned, you'll have to provide your own function that does that.)
get-new-mailnil, then after scanning for new mail in the group
maildirs themselves as usual, this server will also incorporate mail
the conventional Gnus way, from mail-sources according to
nnmail-split-methods or nnmail-split-fancy. The default
value is nil.
Do not use the same maildir both in mail-sources and as
an nnmaildir group. The results might happen to be useful, but
that would be by chance, not by design, and the results might be
different in the future. If your split rules create new groups,
remember to supply a create-directory server parameter.
nnmaildir uses several group parameters. It's safe to ignore
all this; the default behavior for nnmaildir is the same as the
default behavior for other mail back ends: articles are deleted after
one week, etc. Except for the expiry parameters, all this
functionality is unique to nnmaildir, so you can ignore it if
you're just trying to duplicate the behavior you already have with
another back end.
If the value of any of these parameters is a vector, the first element
is evaluated as a Lisp form and the result is used, rather than the
original value. If the value is not a vector, the value itself is
evaluated as a Lisp form. (This is why these parameters use names
different from those of other, similar parameters supported by other
back ends: they have different, though similar, meanings.) (For
numbers, strings, nil, and t, you can ignore the
eval business again; for other values, remember to use an extra
quote and wrap the value in a vector when appropriate.)
expire-agenever to specify that
articles should never be expired. If this parameter is not set,
nnmaildir falls back to the usual
nnmail-expiry-wait(-function) variables (the
expiry-wait group parameter overrides nnmail-expiry-wait
and makes nnmail-expiry-wait-function ineffective). If you
wanted a value of 3 days, you could use something like [(* 3 24
60 60)]; nnmaildir will evaluate the form and use the result.
An article's age is measured starting from the article file's
modification time. Normally, this is the same as the article's
delivery time, but editing an article makes it younger. Moving an
article (other than via expiry) may also make an article younger.
expire-group "backend+server.address.string:group.name"
and if it is not the name of the same group that the parameter belongs
to, then articles will be moved to the specified group during expiry
before being deleted. If this is set to an nnmaildir
group, the article will be just as old in the destination group as it
was in the source group. So be careful with expire-age in the
destination group. If this is set to the name of the same group that
the parameter belongs to, then the article is not expired at all. If
you use the vector form, the first element is evaluated once for each
article. So that form can refer to
nnmaildir-article-file-name, etc., to decide where to put the
article. Even if this parameter is not set, nnmaildir
does not fall back to the expiry-target group parameter or the
nnmail-expiry-target variable.
read-onlyt, nnmaildir will treat the articles
in this maildir as read-only. This means: articles are not renamed
from new/ into cur/; articles are only found in
new/, not cur/; articles are never deleted; articles
cannot be edited. new/ is expected to be a symlink to the
new/ directory of another maildir—e.g., a system-wide mailbox
containing a mailing list of common interest. Everything in the
maildir outside new/ is not treated as read-only, so for
a shared mailbox, you do still need to set up your own maildir (or
have write permission to the shared mailbox); your maildir just won't
contain extra copies of the articles.
directory-filesdirectory-files. It is
used to scan the directories in the maildir corresponding to this
group to find articles. The default is the function specified by the
server's directory-files parameter.
distrust-Lines:nil, nnmaildir will always count the lines of an
article, rather than use the Lines: header field. If
nil, the header field will be used if present.
always-marks['(read expire)]. Whenever
Gnus asks nnmaildir for article marks, nnmaildir will
say that all articles have these marks, regardless of whether the
marks stored in the filesystem say so. This is a proof-of-concept
feature that will probably be removed eventually; it ought to be done
in Gnus proper, or abandoned if it's not worthwhile.
never-marks['(tick expire)]. Whenever
Gnus asks nnmaildir for article marks, nnmaildir will
say that no articles have these marks, regardless of whether the marks
stored in the filesystem say so. never-marks overrides
always-marks. This is a proof-of-concept feature that will
probably be removed eventually; it ought to be done in Gnus proper, or
abandoned if it's not worthwhile.
nov-cache-sizennmaildir keeps NOV data in memory
for a limited number of articles in each group. (This is probably not
worthwhile, and will probably be removed in the future.) This
parameter's value is noticed only the first time a group is seen after
the server is opened—i.e., when you first start Gnus, typically.
The NOV cache is never resized until the server is closed
and reopened. The default is an estimate of the number of articles
that would be displayed in the summary buffer: a count of articles
that are either marked with tick or not marked with
read, plus a little extra.
Articles are stored in the cur/ subdirectory of each maildir.
Each article file is named like uniq:info, where uniq
contains no colons. nnmaildir ignores, but preserves, the
:info part. (Other maildir readers typically use this part of
the filename to store marks.) The uniq part uniquely
identifies the article, and is used in various places in the
.nnmaildir/ subdirectory of the maildir to store information
about the corresponding article. The full pathname of an article is
available in the variable nnmaildir-article-file-name after you
request the article in the summary buffer.
An article identified by uniq has its NOV data (used
to generate lines in the summary buffer) stored in
.nnmaildir/nov/uniq. There is no
nnmaildir-generate-nov-databases function. (There isn't much
need for it—an article's NOV data is updated automatically
when the article or nnmail-extra-headers has changed.) You can
force nnmaildir to regenerate the NOV data for a
single article simply by deleting the corresponding NOV
file, but beware: this will also cause nnmaildir to
assign a new article number for this article, which may cause trouble
with seen marks, the Agent, and the cache.
An article identified by uniq is considered to have the mark
flag when the file .nnmaildir/marks/flag/uniq exists.
When Gnus asks nnmaildir for a group's marks, nnmaildir
looks for such files and reports the set of marks it finds. When Gnus
asks nnmaildir to store a new set of marks, nnmaildir
creates and deletes the corresponding files as needed. (Actually,
rather than create a new file for each mark, it just creates hard
links to .nnmaildir/markfile, to save inodes.)
You can invent new marks by creating a new directory in
.nnmaildir/marks/. You can tar up a maildir and remove it from
your server, untar it later, and keep your marks. You can add and
remove marks yourself by creating and deleting mark files. If you do
this while Gnus is running and your nnmaildir server is open,
it's best to exit all summary buffers for nnmaildir groups and
type s in the group buffer first, and to type g or
M-g in the group buffer afterwards. Otherwise, Gnus might not
pick up the changes, and might undo them.