MAIRIXRC(5)

💖 MAIRIXRC(5) 💖

it's the File Formats Manual era and we're talking about mairixrc — the config file for mairix(1). bestie, this is where you tell mairix where your mail lives and where to dump the search results. let's get into it 🫶

---

🎀 NAME 🎀

mairixrc — configuration file for mairix(1)

---

🌸 SYNOPSIS 🌸

$HOME/.mairixrc

---

✨ DESCRIPTION ✨

okay so. the mairixrc file is the little note you leave for mairix that says where all your mail folders are at. and ALSO where the search results should get written. two jobs, one file, iconic. 💅

mairix goes looking for this file at $HOME/.mairixrc, unless you hit it with the -f option, in which case it looks wherever you told it. your call, queen.

now for the part you cannot skip, no cap: the directives base, mfolder, and database must always show up in the file. and you also gotta have some folder definitions — that means at least one of the maildir, mh, or mbox directives. minimum viable config, let's go 🦋

---

💬 Comments 💬

any line that starts with a # is a comment. that's it. mairix skips right over it like it's not even there. perfect for leaving yourself little notes or dramatic emotional commentary between your directives ✍️

---

📜 Directives 📜

💾 base=base-directory

this defines the path to the common parent directory of all your maildir folders. basically the home base that everything else is measured against 🏠

---

🌐 imap_server=hostname

if you've got any IMAP source folders specified, OR your results folder is an IMAP folder, this is where you put the host name of the IMAP server. heads up: the port is currently always 143. no changing it, that's the vibe.

this option is mutually exclusive with the imap_pipe option — pick one, babe, you can't have both 💀

---

🚰 imap_pipe=shell-command

if you've got any IMAP source folders specified, OR your results folder is an IMAP folder, this defines a shell command you can use to connect to the IMAP server and talk to it over UNIX pipes instead of a TCP/IP connection. cute little shortcut, very demure.

this option is mutually exclusive with the imap_server option. again. one or the other 🙈

---

👤 imap_username=username

if you've got any IMAP source folders specified, OR your results folder is an IMAP folder, this is the user name used to log in to the IMAP server.

this parameter is optional, BUT — and this is the tea — IMAP servers normally require clients to log in, so realistically you're gonna have to set it. the one example where you don't need it? if the imap_pipe option is in use and the shell command established a connection with an IMAP server in a pre-authenticated state. so basically, a very specific situation. you'll know if it's you 💅

---

🔑 imap_password=password

if you've got any IMAP source folders specified, OR your results folder is an IMAP folder, this is the password used to log in to the IMAP server.

this parameter is optional too, but same deal as above — IMAP servers normally require clients to log in, so it's normally necessary to specify it. the server said prove it, and you said bet 🔐

---

📬 maildir=list-of-folder-specifications

this is a colon-separated list of the Maildir folders you want indexed, written out relative to base. any entry that ends with ... gets recursively scanned to find any Maildir folders underneath it. it's giving "get everything in here, i don't care how deep" 🕳️

you can include more than one line starting with maildir. when you do that, mairix joins the lines together with colons, as though you'd given one single list of folders on one extremely long line. same energy, different formatting.

each colon-separated entry can also be a wildcard. the wildcard syntax lives down under mbox (below), go peek at it. for example:

maildir=zzz/foo*...

will match maildir folders like these (relative to the base-directory):

zzz/foobar/xyz
zzz/fooquux
zzz/foo
zzz/fooabc/u/v/w

and this one:

maildir=zzz/foo[abc]*

will match maildir folders like these (relative to the folder_base):

zzz/fooa
zzz/fooaaaxyz
zzz/foobcd
zzz/fooccccccc

now, if a folder name contains a colon, you write it using the sequence \: to escape the colon. otherwise the backslash character is just treated normally, no drama. (and if the folder name literally contains the sequence \:, bestie… you're out of luck. 😭)

---

📭 mh=list-of-folder-specifications

this is a colon-separated list of the MH folders you want indexed, relative to base. any entry ending in ... gets recursively scanned to find any MH folders underneath it. same recursive energy as maildir ✨

more than one line starting with mh can be included, and mairix joins those lines together with colons, as though a single list of folders had been given on one single very long line.

each colon-separated entry may be a wildcard — scroll up to the maildir discussion (above) and down to mbox (below) for the syntax and semantics of specifying wildcards.

mairix recognizes the types of MH folders created by these email applications, and honestly, the range? we love versatility:

• xmh
• sylpheed
• claws-mail
• evolution
• NNML
• Mew

---

📦 mbox=list-of-folder-specifications

this is a colon-separated list of the mbox folders you want indexed, relative to base.

each colon-separated item in the list can be suffixed by .... if the item matches a regular file, that file is treated as an mbox folder and the ... suffix is simply ignored. if the item matches a directory, a recursive scan of everything inside that directory happens, and all regular files are initially considered as mbox folders. (any directories found in this scan get themselves scanned too, because the scan is recursive — it goes all the way down, no skips 💅)

each colon-separated item may contain wildcard operators, but only in its final path component. the wildcard operators currently supported are:

• * — match zero or more characters (each character matched is arbitrary)
• ? — match exactly one arbitrary character
• [abcs-z] — character class: match a single character from the set a, b, c, s, t, u, v, w, x, y and z.

to include a literal ] in the class, place it immediately after the opening [. to include a literal - in the class, place it immediately before the closing ].

if these metacharacters are included in non-final path components, they have no special meaning. nope. they're just vibing as regular characters.

here are some examples:

mbox=foo/bar*

matches foo/bar, foo/bar1, foo/barrrr etc

mbox=foo*/bar*

matches foo*/bar, foo*/bar1, foo*/barrrr etc

mbox=foo/*

matches foo/bar, foo/bar1, foo/barrrr, foo/foo, foo/x etc

mbox=foo...

matches any regular file in the tree rooted at foo

mbox=foo/*...

same as before

mbox=foo/[a-z]*...

matches foo/a, foo/aardvark/xxx, foo/zzz/foobar, foo/w/x/y/zzz, but not foo/A/foobar

---

regular files that are mbox folder candidates get examined internally. only files containing standard mbox From separator lines will be scanned for messages. no separator, no entry, that's the rule 🚪

if a regular file has a name ending in .gz, and gzip support is compiled into the mairix binary, the file will be treated as a gzipped mbox. and if a regular file has a name ending in .bz2, and bzip support is compiled into the mairix binary, the file will be treated as a bzip2'd mbox. compressed and unbothered 🎀

more than one line starting with mbox can be included — mairix joins those lines together with colons, as though a single list of folders had been given on a single very long line.

⚠️ okay so important: mairix performs no locking of mbox folders when it's accessing them. if a mail delivery program is modifying the mbox at the same time, it is likely that one or messages in the mbox will never get indexed by mairix — until the database is removed and recreated from scratch, anyway. the assumption is that mairix will be used to index archive folders rather than incoming ones, so this is unlikely to be much of a problem in reality. so like… it's probably fine, but now you know 👀

and for the limits, write these down: mairix can support a maximum of 65536 separate mboxes, and a maximum of 65536 messages within any one mbox. that's the ceiling, bestie.

---

☁️ imap=list-of-folders

this is a colon-separated list of the IMAP folders you want indexed. living in the cloud, absolutely valid ☁️✨

these folders must all be located on the same account on the same IMAP server. the configuration options imap_server and imap_pipe specify how to connect to the IMAP server — so yeah, you need one of those.

more than one line starting with imap can be included. in this case, mairix joins the lines together with colons, as though a single list of folders had been given on a single very long line. consistent queen 💅

---

🚫 omit=list-of-glob-patterns

this is a colon-separated list of glob patterns for folders to be omitted from the indexing. what's it for? it lets you use wide wildcards and recursive elements in the maildir, mh, and mbox directives, with the omit option selectively removing the folders you don't actually want in there. inclusion with boundaries. growth 🌱

within the glob patterns, a single * matches any sequence of characters other than /. however, ** matches any sequence of characters including /. this is the whole trick — it lets you build glob patterns with a wildcard for just one directory component, or for any number of directory components. pick your fighter ✨

the omit option can be specified as many times as required, so the list of patterns doesn't all have to fit on one line. room to breathe 🫶

as an example:

mbox=bulk...
omit=bulk/spam*

will index all mbox folders at any level under the bulk subdirectory of the base folder, except for those folders whose names start bulk/spam, e.g. bulk/spam, bulk/spam2005 etc.

in contrast:

mbox=bulk...
omit=bulk/spam**

will index all mbox folders at any level under the bulk subdirectory of the base folder, except for those folders whose names start bulk/spam, e.g. bulk/spam, bulk/spam2005, bulk/spam/2005, bulk/spam/2005/jan etc. see the difference? the double star eats through the slashes, the single star does not. iykyk 🔥

---

✅ nochecks

this one takes no arguments. if a line starting with nochecks is present, it's the equivalent of specifying the -Q flag to every indexing run. set it and forget it, low maintenance 👑

---

📂 mfolder=match-folder-name

this defines the name of the folder (within the directory specified by base) into which the search mode writes its output. that's your results folder, bestie, the one that gets the good stuff 💖

(if the mformat used is raw or excerpt, then this setting is not used and may be omitted. so in that case, don't worry about it.)

the mfolder setting may be over-ridden for a particular search by using the -o option to mairix. flexible, we respect it.

and here's the safety feature, listen up: mairix will refuse to output search results to a folder that appears to be amongst those that are indexed. this is to prevent accidental deletion of emails. it's protecting you from yourself, and honestly? thank you mairix 🙏

---

If the first character of the mfolder value is / or ., it is taken as a pathname in its own right. This allows you to specify absolute paths and paths relative to the current directory where the mfolder should be written. Otherwise, the value of mfolder is appended to the value of base, in the same way as for the source folders. 🫶

• mformat=format — This defines the type of folder used for the match folder where the search results go. There are six valid settings for format, namely maildir, mh, mbox, imap, raw, or excerpt. If the raw setting is used then mairix will just print out the path names of the files that match and no match folder will be created. If the excerpt setting is used, mairix will also print out the To:, Cc:, From:, Subject: and Date: headers of the matching messages. maildir is the default if this option is not defined. The setting is case-insensitive. ✨
• database=path-to-database — This defines the path where mairix's index database is kept. You can keep this file anywhere you like. 🦋

Currently, mairix will place a single database file at the location indicated by path-to-database. However, a future version of mairix may instead place a directory containing several files at this location. 👑

path-to-database should be an absolute pathname (starting with /). If a relative pathname is used, it will be interpreted relative to the current directory at the time mairix is run, (not relative to the location of the mairixrc file or anything like that.) 😭

• follow_mbox_symlinks — This takes no arguments. By default, mairix will skip symlinks to mboxes when indexing. If a line starting with follow_mbox_symlinks is present, mairix will follow them instead of skipping them. 🌸

✨ Expansions ✨

The part of each line in .mairixrc following the equals sign can contain the following types of expansion: 💅

Home directory expansion

If the sequence ~/ appears at the start of the text after the equals sign, it is expanded to the user's home directory. Example: 👑

database=~/Mail/mairix_database

Environment expansion

If a $ is followed by a sequence of alpha-numeric characters (or ´_'), the whole string is replaced by looking up the corresponding environment variable. Similarly, if $ is followed by an open brace ({), everything up to the next close brace is looked up as an environment variable and the result replaces the entire sequence. 💜

Suppose in the shell we do

export FOO=bar

and the .mairixrc file contains

maildir=xxx/$FOO
mbox=yyy/a${FOO}b

this is equivalent to

maildir=xxx/bar
mbox=yyy/abarb

If the specified environment variable is not set, the replacement is the empty string. 😭

✨ NOTES ✨

An alternative path to the configuration file may be given with the -f option to mairix(1). 🌈

---

And that's the tea, bestie! This was the January 2006 edition of MAIRIXRC(5) — you absolutely slayed reading it. No cap, fr fr. 💖