Table of Contents
When NeoMutt starts up it looks for two configuration files – one “system” file and one “user” file.
NeoMutt first reads the system configuration file, then the user configuration file. The two files are merged in the sense that "last setting wins". That is, if a setting is defined in both files, the user configuration file's value for that setting is the one that takes precedence and becomes effective.
NeoMutt searches for several different file names when looking for config. It looks for NeoMutt config files before Mutt config files and versioned config before plain config. For example:
This allows the user to create separate NeoMutt and Mutt config files on the same system.
NeoMutt will search for a system config file in
a neomutt directory in several places. First it
searches the locations specified in the
XDG_CONFIG_DIRS environment variable, which
defaults to /etc/xdg. Next, it looks in
/etc. Finally, it tries
/usr/share.
The system config file will not be read if the “-n” option is used on the command line.
NeoMutt will read just one file, the first file it finds, from the list below.
Table 3.2. NeoMutt system config file locations
| File Location | Notes |
|---|---|
| /etc/xdg/neomutt/neomuttrc | |
| /etc/xdg/neomutt/Muttrc | Note the case of the filename |
| /etc/neomuttrc | |
| /etc/Muttrc | Note the case of the filename |
| /usr/share/neomutt/neomuttrc | |
| /usr/share/neomutt/Muttrc | Note the case of the filename |
NeoMutt will search for a user config file in several places. First
it looks in the directory specified in the
XDG_CONFIG_HOME environment variable, which
defaults to ~/.config/neomutt. Next, it looks in
~ (your home directory). Finally, it tries
~/.neomutt.
You may specify your own location for the user config file using the “-F” option on the command line.
NeoMutt will read just one file, the first file it finds, from the list below.
Table 3.3. NeoMutt user config file locations
| File Location |
|---|
| ~/.config/neomutt/neomuttrc |
| ~/.config/neomutt/muttrc |
| ~/.config/mutt/neomuttrc |
| ~/.config/mutt/muttrc |
| ~/.neomutt/neomuttrc |
| ~/.neomutt/muttrc |
| ~/.mutt/neomuttrc |
| ~/.mutt/muttrc |
| ~/.neomuttrc |
| ~/.muttrc |
The majority of NeoMutt's config will be read from two files: the
system config in /etc and the user config in, e.g.
~/.neomuttrc
The last file that gets read will overwrite any settings from previous config files. This means that an administrator can set some defaults which the user can override.
Additionally, there are a handful of config items which can be set using an environment variable. They have a lower priority than the NeoMutt config files: $editor, $from, $mailcap_path, $news_server, shell, $spoolfile, $tmpdir, $visual.
Finally, it's possible to
set some variables directly on the
command-line using the -e option.
Table 3.4. Config Priority
| Priority | Where | Example |
|---|---|---|
| Highest | Command line | neomutt -e 'set from="John Doe <john@example.com>"' |
| User Config | ~/.neomuttrc | |
| System Config | /etc/neomuttrc | |
| Environment | export EDITOR="/usr/bin/vim" | |
| Lowest | Built-in | Defaults hard-coded into NeoMutt |
An initialization file consists of a series of commands. Each line of the file may contain one or more commands. When multiple commands are used, they must be separated by a semicolon (“;”).
The hash mark, or pound sign (“#”), is used as a “comment” character. You can use it to annotate your initialization file. All text after the comment character to the end of the line is ignored.
Example 3.2. Commenting configuration files
my_hdr X-Disclaimer: Why are you listening to me? # This is a comment
Single quotes (“'”) and double quotes (“"”) can be used to quote strings which contain spaces or other special characters. The difference between the two types of quotes is similar to that of many popular shell programs, namely that a single quote is used to specify a literal string (one that is not interpreted for shell variables or quoting with a backslash [see next paragraph]), while double quotes indicate a string for which should be evaluated. For example, backticks are evaluated inside of double quotes, but not for single quotes.
“\” quotes the next character, just as in shells such as bash and zsh. For example, if want to put quotes “"” inside of a string, you can use “\” to force the next character to be a literal instead of interpreted character.
“\\” means to insert a literal “\” into the line. “\n” and “\r” have their usual C meanings of linefeed and carriage-return, respectively.
A “\” at the end of a line can be used to split commands over multiple lines as it “escapes” the line end, provided that the split points don't appear in the middle of command names. Lines are first concatenated before interpretation so that a multi-line can be commented by commenting out the first line only.
Example 3.4. Splitting long configuration commands over several lines
set status_format="some very \ long value split \ over several lines"
It is also possible to substitute the output of a Unix command in an initialization file. This is accomplished by enclosing the command in backticks (``). In Example 3.5, “Using external command's output in configuration files”, the output of the Unix command “uname -a” will be substituted before the line is parsed. Since initialization files are line oriented, only the first line of output from the Unix command will be substituted.
Example 3.5. Using external command's output in configuration files
my_hdr X-Operating-System: `uname -a`
Both environment variables and NeoMutt variables can be accessed by prepending “$” to the name of the variable. For example,
will cause NeoMutt to save outgoing messages to a folder named
“sent_on_kremvax” if the environment variable
$HOSTNAME is set to “kremvax.” (See
$record for details.)
NeoMutt expands the variable when it is a