Next: Mail Folders, Previous: MH Spool, Up: Choosing a Mail Back End

##### 6.4.13.5 Maildir

`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:

`directory`
  For each of your `nnmaildir` 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 `eval`ed 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-prefix`
  This should be a Lisp form which is processed by `eval` and `expand-file-name`. The form is `eval`ed 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-files`
  This should be a function with the same interface as `directory-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-mail`
  If non-`nil`, 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.

##### 6.4.13.6 Group parameters

`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-age`
  An integer specifying the minimum age, in seconds, of an article before it will be expired, or the symbol `never` 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`
  If this is set to a string such as a full Gnus group name, like

                "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-only`
  If this is set to `t`, `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-files`
  A function with the same interface as `directory-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:`
  If non-`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`
  A list of mark symbols, such as `['(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`
  A list of mark symbols, such as `['(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-size`
  An integer specifying the size of the NOV memory cache. To speed things up, `nnmaildir` 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.

##### 6.4.13.7 Article identification

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.

##### 6.4.13.8 NOV data

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.

##### 6.4.13.9 Article marks

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.