muttrc(5)

NAME
muttrc - Configuration file for the Mutt Mail User Agent

DESCRIPTION

A mutt configuration 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.

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 which should be evaluated. For example, backquotes are evaluated inside of double quotes, but not 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, provided that the split points don't appear in the middle of command names.

It is also possible to substitute the output of a Unix command in an initialization file. This is accomplished by enclosing the command in backquotes (`command`).

UNIX environment variables can be accessed like the way it is done in shells like sh and bash: Prepend the name of the variable by a dollar (“$”) sign.

COMMANDS

alias [-group name [...]] key address [, address [ ... ]]
unalias [ *  | key ]

    alias defines an alias key for the given addresses. Each address will be resolved into either an email address (user@example.com) or a named email address (User Name <user@example.com>). The address may be specified in either format, or in the format “user@example.com (User Name)”. unalias removes the alias corresponding to the given key or all aliases when “*” is used as an argument. The optional -group argument to alias causes the aliased address(es) to be added to the named group.

group [-group name] [-rx EXPR [ ... ]] [-addr address [ ... ]]
ungroup [-group name ] [ * | [[-rx EXPR [ ... ]] [-addr address [ ... ]]]

    group is used to directly add either addresses or regular expressions to the specified group or groups. The different categories of arguments to the group command can be in any order. The flags -rx and -addr specify what the following strings (that cannot begin with a hyphen) should be interpreted as: either a regular expression or an email address, respectively. ungroup is used to remove addresses or regular expressions from the specified group or groups. The syntax is similar to the group command, however the special character * can be used to empty a group of all of its contents.

    These address groups can also be created implicitely by the alias, lists, subscribe and alternates commands by specifying the optional -group option.

    Once defined, these address groups can be used in patterns to search for and limit the display to messages matching a group.

alternates [-group name] regexp [ , regexp [ ... ]]
unalternates [ *  | regexp [ , regexp [ ... ]] ]

    alternates is used to inform mutt about alternate addresses where you receive mail; you can use regular expressions to specify alternate addresses. This affects mutt's idea about messages from you, and messages addressed to you. unalternates removes a regular expression from the list of known alternates. The -group flag causes all of the subsequent regular expressions to be added to the named group.

alternative_order type[/subtype] [ ... ]
unalternative_order [ *  | type/subtype] [...]

    alternative_order command permits you to define an order of preference which is used by mutt to determine which part of a multipart/alternative body to display. A subtype of “*” matches any subtype, as does an empty subtype. unalternative_order removes entries from the ordered list or deletes the entire list when “*” is used as an argument.

auto_view type[/subtype] [ ... ]
unauto_view type[/subtype] [ ... ]

    This commands permits you to specify that mutt should automatically convert the given MIME types to text/plain when displaying messages. For this to work, there must be a mailcap(5) entry for the given MIME type with the copiousoutput flag set. A subtype of “*” matches any subtype, as does an empty subtype.

mime_lookup type[/subtype] [ ... ]
unmime_lookup type[/subtype] [ ... ]

    This command permits you to define a list of "data" MIME content types for which mutt will try to determine the actual file type from the file name, and not use a mailcap(5) entry given for the original MIME type. For instance, you may add the application/octet-stream MIME type to this list.

bind map1,map2,... key function
    This command binds the given key for the given map or maps to the given function. Multiple maps may be specified by separating them with commas (no whitespace is allowed).

    Valid maps are: generic, alias, attach, browser, editor, index, compose, pager, pgp, postpone, mix.

    For more information on keys and functions, please consult the Mutt Manual.

account-hook [!]regexp command
    This hook is executed whenever you access a remote mailbox. Useful to adjust configuration settings to different IMAP or POP servers.

charset-hook alias charset
    This command defines an alias for a character set. This is useful to properly display messages which are tagged with a character set name not known to mutt.

iconv-hook charset local-charset
    This command defines a system-specific name for a character set. This is useful when your system's iconv(3) implementation does not understand MIME character set names (such as iso-8859-1), but instead insists on being fed with implementation-specific character set names (such as 8859-1). In this specific case, you'd put this into your configuration file:

    iconv-hook iso-8859-1 8859-1

message-hook [!]pattern command
    Before mutt displays (or formats for replying or forwarding) a message which matches the given pattern (or, when it is preceded by an exclamation mark, does not match the pattern), the given command is executed. When multiple message-hooks match, they are executed in the order in which they occur in the configuration file.

folder-hook [!]regexp command
    When mutt enters a folder which matches regexp (or, when regexp is preceded by an exclamation mark, does not match regexp), the given command is executed.

    When several folder-hooks match a given mail folder, they are executed in the order given in the configuration file.

macro map key sequence [ description ]
    This command binds the given sequence of keys to the given key in the given map or maps. For valid maps, see bind. To specify multiple maps, put only a comma between the maps.

color object foreground background [  regexp ]
color index foreground background [  pattern ]
uncolor index pattern [ pattern ... ]

    If your terminal supports color, these commands can be used to assign foreground/backgound combinations to certain objects. Valid objects are: attachment, body, bold, header, hdrdefault, index, indicator, markers, message, normal, quoted, quotedN, search, signature, status, tilde, tree, underline. The body and header objects allow you to restrict the colorization to a regular expression. The index object permits you to select colored messages by pattern.

    Valid colors include: white, black, green, magenta, blue, cyan, yellow, red, default, colorN.

mono object attribute [ regexp ]
mono index attribute [ pattern ]

    For terminals which don't support color, you can still assign attributes to objects. Valid attributes include: none, bold, underline, reverse, and standout.

[un]ignore pattern [ pattern ... ]
    The ignore command permits you to specify header fields which you usually don't wish to see. Any header field whose tag begins with an “ignored” pattern will be ignored.

    The unignore command permits you to define exceptions from the above mentioned list of ignored headers.

lists [-group name] regexp [ regexp ... ]
unlists regexp [ regexp ... ]
subscribe [-group name] regexp [ regexp ... ]
unsubscribe regexp [ regexp ... ]

    Mutt maintains two lists of mailing list address patterns, a list of subscribed mailing lists, and a list of known mailing lists. All subscribed mailing lists are known. Patterns use regular expressions.

    The lists command adds a mailing list address to the list of known mailing lists. The unlists command removes a mailing list from the lists of known and subscribed mailing lists. The subscribe command adds a mailing list to the lists of known and subscribed mailing lists. The unsubscribe command removes it from the list of subscribed mailing lists. The -group flag adds all of the subsequent regular expressions to the named group.

mbox-hook [!]pattern mailbox
    When mutt changes to a mail folder which matches pattern, mailbox will be used as the “mbox” folder, i.e., read messages will be moved to that folder when the mail folder is left.

    The first matching mbox-hook applies.

mailboxes filename [ filename ... ]
unmailboxes [ * | filename ... ]

    The mailboxes specifies folders which can receive mail and which will be checked for new messages. When changing folders, pressing space will cycle through folders with new mail. The unmailboxes command is used to remove a file name from the list of folders which can receive mail. If "*" is specified as the file name, the list is emptied.

my_hdr string
unmy_hdr field

    Using my_hdr, you can define headers which will be added to the messages you compose. unmy_hdr will remove the given user-defined headers.

hdr_order header1 header2 [ ... ]
    With this command, you can specify an order in which mutt will attempt to present headers to you when viewing messages.

save-hook [!]pattern filename
    When a message matches pattern, the default file name when saving it will be the given filename.

fcc-hook [!]pattern filename
    When an outgoing message matches pattern, the default file name for storing a copy (fcc) will be the given filename.

fcc-save-hook [!]pattern filename
    This command is an abbreviation for identical fcc-hook and save-hook commands.

send-hook [!]pattern command
    When composing a message matching pattern, command is executed. When multiple send-hooks match, they are executed in the order in which they occur in the configuration file.

send2-hook [!]pattern command
    Whenever a message matching pattern is changed (either by editing it or by using the compose menu), command is executed. When multiple send2-hooks match, they are executed in the order in which they occur in the configuration file. Possible applications include setting the $sendmail variable when a message's from header is changed.

    send2-hook execution is not triggered by use of enter-command from the compose menu.

reply-hook [!]pattern command
    When replying to a message matching pattern, command is executed. When multiple reply-hooks match, they are executed in the order in which they occur in the configuration file, but all reply-hooks are matched and executed before send-hooks, regardless of their order in the configuration file.

crypt-hook pattern key-id
    The crypt-hook command provides a method by which you can specify the ID of the public key to be used when encrypting messages to a certain recipient. The meaning of "key ID" is to be taken broadly: This can be a different e-mail address, a numerical key ID, or even just an arbitrary search string.

push string
    This command adds the named string to the keyboard buffer.

set [no|inv|&|?]variable[=value] [ ... ]
toggle variable [ ... ]
unset variable [ ... ]
reset variable [ ... ]

    These commands are used to set and manipulate configuration varibles.

    Mutt knows four basic types of variables: boolean, number, string and quadoption. Boolean variables can be set (true), unset (false), or toggled. Number variables can be assigned a positive integer value.

    String variables consist of any number of printable characters. Strings must be enclosed in quotes if they contain spaces or tabs. You may also use the “C” escape sequences \n and \t for newline and tab, respectively.

    Quadoption variables are used to control whether or not to be prompted for certain actions, or to specify a default action. A value of yes will cause the action to be carried out automatically as if you had answered yes to the question. Similarly, a value of no will cause the the action to be carried out as if you had answered “no.” A value of ask-yes will cause a prompt with a default answer of “yes” and ask-no will provide a default answer of “no.”

    The reset command resets all given variables to the compile time defaults. If you reset the special variable all, all variables will reset to their compile time defaults.

source filename
    The given file will be evaluated as a configuration file.

spam pattern format
    nospam pattern
    These commands define spam-detection patterns from external spam filters, so that mutt can sort, limit, and search on ``spam tags'' or ``spam attributes'', or display them in the index. See the Mutt manual for details.

unhook [ *  | hook-type ]
    This command will remove all hooks of a given type, or all hooks when “*” is used as an argument. hook-type can be any of the -hook commands documented above.

PATTERNS

In various places with mutt, including some of the abovementioned hook commands, you can specify patterns to match messages.

  Constructing Patterns

A simple pattern consists of an operator of the form “~character”, possibly followed by a parameter against which mutt is supposed to match the object specified by this operator. For some characters, the ~ may be replaced by another character to alter the behavior of the match. These are described in the list of operators, below.

With some of these operators, the object to be matched consists of several e-mail addresses. In these cases, the object is matched if at least one of these e-mail addresses matches. You can prepend a hat (“^”) character to such a pattern to indicate that all addresses must match in order to match the object.

You can construct complex patterns by combining simple patterns with logical operators. Logical AND is specified by simply concatenating two simple patterns, for instance “~C mutt-dev ~s bug”. Logical OR is specified by inserting a vertical bar (“|”) between two patterns, for instance “~C mutt-dev | ~s bug”. Additionally, you can negate a pattern by prepending a bang (“!”) character. For logical grouping, use braces (“()”). Example: “!(~t mutt|~c mutt) ~f elkins”.

  Simple Patterns

Mutt understands the following simple patterns:

~A  all messages
~b EXPR
    messages which contain EXPR in the message body.
=b STRING
    messages which contain STRING in the message body. If IMAP is enabled, searches for STRING on the server, rather than downloading each message and searching it locally.
~B EXPR
    messages which contain EXPR in the whole message.
~c EXPR
    messages carbon-copied to EXPR
%c GROUP
    messages carbon-copied to any member of GROUP
~C EXPR
    messages either to: or cc: EXPR
%C GROUP
    messages either to: or cc: to any member of GROUP
~d MIN-MAX
    messages with “date-sent” in a Date range
~D  deleted messages
~e EXPR
    messages which contain EXPR in the “Sender” field
%e GROUP
    messages which contain a member of GROUP in the “Sender” field
~E  expired messages
~f EXPR
    messages originating from EXPR
%f GROUP
    messages originating form any member of GROUP
~F  flagged messages
~g  PGP signed messages
~G  PGP encrypted messages
~h EXPR
    messages which contain EXPR in the message header
~H EXPR
    messages with spam tags matching EXPR
~i EXPR
    messages which match EXPR in the “Message-ID” field
~k  messages containing PGP key material
~l  messages addressed to a known mailing list (defined by either subscribe or list)
~L EXPR
    messages either originated or received by EXPR
%L GROUP
    messages either originated or received by any member of GROUP
~m MIN-MAX
    message in the range MIN to MAX
~n MIN-MAX
    messages with a score in the range MIN to MAX
~N  new messages
~O  old messages
~p  messages addressed to you (as defined by alternates)
~P  messages from you (as defined by alternates)
~Q  messages which have been replied to
~r MIN-MAX
    messages with “date-received” in a Date range
~R  read messages
~s EXPR
    messages having EXPR in the “Subject” field.
~S  superseded messages
~t EXPR
    messages addressed to EXPR
~T  tagged messages
~u  messages addressed to a subscribed mailing list (defined by subscribe commands)
~U  unread messages
~v  message is part of a collapsed thread.
~V  cryptographically verified messages
~x EXPR
    messages which contain EXPR in the “References” field
~X MIN-MAX
    messages with MIN - MAX attachments
~y EXPR
    messages which contain EXPR in the “X-Label” field
~z MIN-MAX
    messages with a size in the range MIN to MAX
~=  duplicated messages (see $duplicate_threads)
~$  unreferenced message (requries threaded view)
~(PATTERN)
    messages in threads containing messages matching a certain pattern, e.g. all threads containing messages from you: ~(~P)

In the above, EXPR is a regular expression.

With the ~m, ~n, ~X, and ~z operators, you can also specify ranges in the forms <MAX, >MIN, MIN-, and -MAX.

  Matching dates

The ~d and ~r operators are used to match date ranges, which are interpreted to be given in your local time zone.

A date is of the form DD[/MM[/[cc]YY]], that is, a two-digit date, optionally followed by a two-digit month, optionally followed by a year specifications. Omitted fields default to the current month and year.

Mutt understands either two or four digit year specifications. When given a two-digit year, mutt will interpret values less than 70 as lying in the 21st century (i.e., “38” means 2038 and not 1938, and “00” is interpreted as 2000), and values greater than or equal to 70 as lying in the 20th century.

Note that this behaviour is Y2K compliant, but that mutt does have a Y2.07K problem.

If a date range consists of a single date, the operator in question will match that precise date. If the date range consists of a dash (“-”), followed by a date, this range will match any date before and up to the date given. Similarly, a date followed by a dash matches the date given and any later point of time. Two dates, separated by a dash, match any date which lies in the given range of time.

You can also modify any absolute date by giving an error range. An error range consists of one of the characters +, -, *, followed by a positive number, followed by one of the unit characters y, m, w, or d, specifying a unit of years, months, weeks, or days. + increases the maximum date matched by the given interval of time, - decreases the minimum date matched by the given interval of time, and * increases the maximum date and decreases the minimum date matched by the given interval of time. It is possible to give multiple error margins, which cumulate. Example: 1/1/2001-1w+2w*3d

You can also specify offsets relative to the current date. An offset is specified as one of the characters <, >, =, followed by a positive number, followed by one of the unit characters y, m, w, or d. > matches dates which are older than the specified amount of time, an offset which begins with the character < matches dates which are more recent than the specified amount of time, and an offset which begins with the character = matches points of time which are precisely the given amount of time ago.

CONFIGURATION VARIABLES

SEE ALSO

iconv(1), iconv(3), mailcap(5), maildir(5), mbox(5), mutt(1), printf(3), regex(7), strftime(3)

The Mutt Manual

The Mutt home page: http://www.mutt.org/

AUTHOR

Michael Elkins, and others. Use <mutt-dev@mutt.org> to contact the developers.