swift 11/08/17 19:49:12
Bug #304623 - Rewrite of guide-to-mutt.xml. Thanks to Fabian Groffen
Revision Changes Path
file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml?rev=1.20&view=markup
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml?r1=1.19&r2=1.20
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- guide-to-mutt.xml 17 Sep 2006 16:08:36 -0000 1.19
+++ guide-to-mutt.xml 17 Aug 2011 19:49:12 -0000 1.20
@@ -1,259 +1,128 @@
<?xml version='1.0' encoding="UTF-8"?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml,v 1.19 2006/09/17 16:08:36 neysx Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml,v 1.20 2011/08/17 19:49:12 swift Exp $ -->
-<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
+<!DOCTYPE guide SYSTEM "http://www.gentoo.org/dtd/guide.dtd">
<title>QuickStart Guide to Mutt E-Mail</title>
- <mail link="mikpolniak@...">Mike Polniak</mail>
- <mail link="email@example.com">Ken Nowack</mail>
- <mail link="hitch17@...">John Hitchings</mail>
+ <mail link="firstname.lastname@example.org">Fabian Groffen</mail>
-This guide shows you how to begin using the powerful command line tools for
-e-mail: fetchmail, procmail, mutt, nbsmtp, msmtp.
+This guide shows you how to begin using the powerful command line e-mail
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
-<title>Introduction to E-Mail</title>
+<title>The Mutt e-mail client</title>
If you're not a fan of e-mail clients with fancy graphical user interfaces, or
-if you would just like to experiment with other mail clients before deciding
-which is best for you, here is the easy way to begin using these powerful
-command line tools:
-<b>fetchmail, procmail, mutt & smtp</b>
-These programs are not only powerful and highly customizable but also small and
-efficient. Once you are up and running with this e-mail system you will be
-amazed at what you can do with it.
+you just like to be able to quickly read some mail over an SSH connection, the
+class of console-based mail clients might be for you.
-Because this is a quick start guide, we will eliminate the Mail Transfer Agent
-(MTA) such as sendmail, postfix or exim. This means no complex MTA
-configuration. It also eliminates using port 25 for mail service.
+Mutt is one of the current console-based mail clients that's still under active
+development and has a vast crowd of active supporters (and users). It is
+powerful, highly customisable, small and efficient.
-We can do this because fetchmail can force the mail it retrieves directly to a
-Mail Delivery Agent (MDA) rather than forwarding to port 25. And we don't need
-to use a complex MTA for plain old outgoing mail delivery.
-These are the programs you will need to get your e-mail running.
-<pre caption="Getting needed programs">
-# <i>emerge fetchmail nbsmtp procmail mutt</i>
-Then just four quick steps to configure files and you will be up and running a
-brand new e-mail system.
+While Mutt was originally designed to read mail from the local mbox mail spool
+(e.g. <path>/var/spool/mail/</path>), nowadays it comes with full support for
+Maildir stored folders, remote fetching from POP3 servers and complete
+management of IMAP accounts. For a full description of what Mutt can do, please
+read the Mutt manual and Mutt website at <uri>http://www.mutt.org/</uri>.
-After each step you can run a test to make sure the setup is correct. This
-means you will have a complete working e-mail system when you are done.
-Fetchmail fetches mail from remote servers and forwards it to your local
-machines delivery system. To use it you need to set up a
-<path>.fetchmailrc</path> file in your home directory like this example:
-<pre caption="Sample .fetchmailrc">
-<i>poll mail.myisp.net protocol pop3 user "myname" password "mypasswd"</i>
-Once you have created a <path>.fetchmailrc</path> file, you have to change the
-permissions on the file using the chmod command. The file must be readable only
-by the file owner. Set the permissions with the following command:
-<pre caption="Changing Permissions">
-$ <i>chmod 600 .fetchmailrc</i>
-To see fetchmail in action, use the verbose mode (-v). To fetch all messages
-use -a. And you must use the option -m to tell fetchmail to send the mail to
-While testing, it's a good idea to tell fetchmail to keep (-k) the mail on the
-remote server in case something goes wrong and you need to fetch it again.
-Run it now to see fetchmail in action!
+Starting your Mutt adventure simply requires you to emerge it.
+Unfortunately, Mutt has a lots of options, which enable or disable certain
+functionalities of Mutt. We now briefly discuss the most important USE-flags
+that you may want to enable based on your intended usage of Mutt. Please note
+that enabling most of them won't harm your Mutt, but may make it do more than an
+experienced Mutt user would like.
-<pre caption="Fetchmail test #1">
-$ <i>fetchmail -akv -m "/usr/bin/procmail -d %T"</i>
+<pre caption="Mutt's USE-flags">
+% <i>emerge -pv mutt</i>
+[ebuild N ] mail-client/mutt-1.5.21-r1 USE="gdbm gpg imap mbox nls nntp \
+ sidebar smime smtp ssl -berkdb -crypt -debug -doc -gnutls \
+ -idn -pop -qdbm -sasl -tokyocabinet"
-Once you have a working mail system you can set this as a cron job or put it in
-a monitor like gkrellm. Fetchmail can also run in a daemon mode for which you
-specify a polling interval in seconds.
+First off, for newcomers, the <c>imap</c> USE-flag is most probably the most
+important one. Enabling it won't hurt anything, so if you're unsure what
+account you're going to use Mutt with, just enable it. Most email providers,
+even free ones such as GMail, use IMAP these days, for it is the most convenient
+way to store email that is accessed from multiple clients at the same time
+and/or different locations. Because IMAP keeps all mail at the server, Mutt
+just downloads the messages that you want to view.
-Procmail is the processor that filters the mail that is forwarded to it by
-fetchmail. It also acts as the MDA to deliver mail to your mailboxes where mutt
-(your e-mail client) can read it.
+Often you happen to jump through a couple of messages a couple of times shortly
+after each other, which would require to download the same message over and
+over again. Since this simply is a waste, Mutt uses a so-called header cache
+(hcache) to keep the most important bits of messages that it needs. This
+hcache is backed by a db-library, of which four flavours exist: <c>gdbm</c>,
+<c>berkdb</c>, <c>qdbm</c> and <c>tokyocabinet</c>. If you don't have any
+preference yourself, pick gdbm or berkdb. Most likely you will have both
+already installed on your system. Enabling the USE-flags for more than one
+hcache backend will make Mutt choose one it likes best. It will always use
+at most one.
-To use procmail you need to create a <path>.procmailrc</path> file in your home
-directory. For our quickstart purposes we will use a very simple
-<path>.procmailrc</path> that will filter mail from three gentoo mailing lists
-into these mailboxes:<e>gentoo-dev, gentoo-user</e> and <e>gentoo-announce</e>
+While IMAP is important for reading mail, sending mail requires a mail server.
+Mutt can talk to a mail server that exists on the local system, but often that's
+not the case, or simply not a good solution for e.g. laptop users that often
+travel around. Mutt comes with SMTP support which gets enabled by the <c>smtp</c>
+USE-flag. Again, enabling it if you're not sure doesn't harm. Mutt's SMTP
+support allows you just to send mail over a mail server of your choice; usually
+the one that you are given by your email provider.
-The procmail filter rules are called recipes, and I have also included recipes
-to filter out some spam.
-<pre caption="Sample .procmailrc">
-MAILDIR=$HOME/MuttMail ##you better make sure it exists
-#VERBOSE=on...is only used for debugging
-##recipe lines begin with :0
-##dont put comments on recipe lines
-##disable a recipe with the false condition !
-##condition lines begin with * and regex is your friend
-##conditions are anded and everything after * is fed straight into egrep
-##one action line follows the conditions, in this case it is a mailbox name
-#catch duplicates using formail
-:0 Whc: .msgid.lock
-| $FORMAIL -D 16384 .msgid.cache
-#people we always allow mail from
-#now flush some spam out
-#no more html messages
-#now put my mail lists into mailboxes
-#catch any other gentoo mail
-# Last rule: mail that gets #
-# this far goes in default box #
-# End of file
-It is only required to make the MAILDIR <path>$HOME/MuttMail</path> as Procmail
-will create all the mailbox files as needed in this directory using the names
-on the action lines. For some useful links visit
-You can now test <path>.procmailrc</path> by re-running the fetchmail command
-we tested in the first step. Remember the -k option to keep all mail on the
-remote server so we have it if we need to rerun it.
+Both IMAP and SMTP mostly go over encrypted channels these days, hence if you
+enabled any of both, it is wise to also enable either of the <c>ssl</c> or
+<c>gnutls</c> USE-flags. Both just add the secure variants (imaps and smtps) to
+Mutt's list of supported protocols using either OpenSSL's or GNUTLS'
+implementation. If you don't have a strong preference for either, just go for
+<c>ssl</c>. Most likely this is in your global USE already anyway.
-<pre caption="Procmail test #1">
-$ <i>fetchmail -akv -m "/usr/bin/procmail -d %T"</i>
-Now that fetchmail and procmail have run, go to <path>$HOME/MuttMail</path> and
-read your messages with <c>less</c> or your file manager.
+Last but not least, there is the <c>sidebar</c> USE-flag. It enables an
+extension to Mutt that can show a navigation pane of available mailboxes on the
+left hand side of the screen. While this is not a recommended feature for
+absolute newcomers (it is nowhere mentioned in any official docs, since it
+simply isn't official), more experienced users might like its functionality.
+Luckily, just enabling the USE-flag doesn't make it visible at all, meaning you
+don't even notice it's enabled.
@@ -261,244 +130,184 @@
-<title>Mutt e-mail client</title>
-Mutt is used to read and compose e-mail. It is powerful and highly customizable
-but also small and efficient.
+After you emerged mutt with your USE-flags of choice, the only necessary step is
+to create a <path>.muttrc</path> file in your home directory. Muttrc's are to
+be found in many places on the web and in Mutt's documentation. In
+<path>/usr/share/doc/mutt-<version>/samples</path> you can find some
+muttrc samples that are from the official distribution. We discuss a very
+minimal <path>.muttrc</path> for an IMAP based account with SMTP mail delivery
+<pre caption="A .muttrc example file">
+# character set on messages that we send
+# if there is no character set given on incoming messages, it is probably windows
+# make sure Vim knows mutt is a mail client and that we compose an UTF-8 encoded message
+set editor="vim -c 'set syntax=mail ft=mail enc=utf-8'"
+# just scroll one line instead of full page
+# we want to see some MIME types inline, see below this code listing for explanation
+# make default search pattern to search in To, Cc and Subject
+set simple_search="~f %s | ~C %s | ~s %s"
+# threading preferences, sort by threads
+# show spam score (from SpamAssassin only) when reading a message
+spam "X-Spam-Score: ([0-9\\.]+).*" "SA: %1"
+set pager_format = " %C - %[%H:%M] %.20v, %s%* %?H? [%H] ?"
+# do not show all headers, just a few
+unignore From To Cc Bcc Date Subject
+# and in this order
+hdr_order From: To: Cc: Bcc: Date: Subject:
+# brighten up stuff with colours, for more colouring examples see:
+color normal white black
+color hdrdefault green default
+color quoted green default
+color quoted1 yellow default
+color quoted2 red default
+color signature cyan default
+color indicator brightyellow red
+color error brightred default
+color status brightwhite blue
+color tree brightmagenta black
+color tilde blue default
+color attachment brightyellow default
+color markers brightred default
+color message white black
+color search brightwhite magenta
+color bold brightyellow default
+# if you don't like the black progress bar at the bottom of the screen,
+# comment out the following line
+color progress white black
+# personality settings
+set realname = "Andrew Dalziel"
+set from = "andy@..."
+# this file must exist, and contains your signature, comment it out if
+# you don't want a signature to be used
+set signature = ~/.signature
+# aliases (sort of address book)
+# IMAP connection settings
+# IMAP account settings
+# use headercache for IMAP (make sure this is a directory for performance!)
+# mailboxes we want to monitor for new mail
-Mutt supports reading and writing of four different mailbox formats: mbox,
-MMDF, MH and Maildir. The mailbox type is autodetected. In our case we are
-using the mbox format, where all messages of a mailbox are stored in a single
-Mutt also has the ability to work with folders located on a remote IMAP server.
-See IMAP Support in section 4.11 of the Mutt manual and the Mutt web site
-When you emerged mutt in the first step it installed a configuration file in
-<path>/etc/mutt/Muttrc</path>. You also need to create a <path>.muttrc</path>
-file in your home directory.
-<pre caption="Sample .muttrc">
-<comment>(Be sure to read the fine Mutt manual in /usr/share/doc/mutt*)
-(Any settings here override the system settings in /etc/mutt/Muttrc)</comment>
-# <i>cp /etc/mutt/Muttrc ~/.muttrc</i>
-# <i>nano -w .muttrc</i>
-set pager_index_lines=6 #show a mini-index in pager
-set pgp_verify_sig=no #dont show pgp in pager
-set status_on_top #put status line at top
-set sort=threads #sort by message threads in index
-set status_format=" %r %b %f %n Del %d Msgs %m %l %> (%P)"
-set pager_format="%-10.10i %[!%a %b %d %R]"
-set date_format="!%H:%M %a %d %b "
-set index_format="%4C %Z %[%b%d] %-15.15F %s"
-set folder_format="%2C %t %8s %d %N %f"
-#set sendmail="/usr/bin/nbsmtp -d isp.net -h smtp.isp.net -f yourname@..."
-#set from="default-mailaddress" #set to your from address
-set record="$HOME/MuttMail/sent" #sent mail is saved here
-set delete=yes #delete without prompting
-set include=yes #quote msg in reply
-set fast_reply=yes #no prompting on reply
-set beep=no #no noise
-set markers=no #no + on wrapped lines
-set confirmappend=no #no prompt for save to =keep
-set to_chars=" +TCF" #no L for mail_list
-set folder = $HOME/MuttMail
-save-hook .* =keep #default mbox to (s)ave mail is =keep
-subscribe gentoo-user gentoo-dev #subscribed to these lists
-bind pager h display-toggle-weed #toggle headers with h key
-# simulate the old url menu
-macro index \cb |urlview\n 'call urlview to extract URLs out of a message'
-macro pager \cb |urlview\n 'call urlview to extract URLs out of a message'
-#run fetchmail by hitting key of G
-macro index G "!fetchmail -a -m 'procmail -d %T'\r"
-macro pager G "!fetchmail -a -m 'procmail -d %T'\r"
-#use to edit .muttrc and then source it...no restart necessary
-macro generic ,sm ":source $HOME/.muttrc\r"
-macro generic \cj "!rxvt -bg wheat -e joe $HOME/.muttrc\r"
-# default list of header fields to weed out when displaying mail
-#ignore them all and then unignore what you want to see
-unignore Date To From: Subject X-Mailer Organization User-Agent
-hdr_order Date From To Subject X-Mailer User-Agent Organization
-##your Mutt has to have some colors
-##these are for four levels of quoted text
-##they override the system settings in /etc/mutt/Muttrc
-#color quoted green default
-color quoted1 magenta blue
-#color quoted2 yellow default
-#color quoted3 red default
-#color signature cyan cyan
-#this color setup is copied from /etc/mutt/Muttrc.color
-#comment it out if you want the default colors in /etc/mutt/Muttrc
-# Je vois la vie en rose :-)
-color hdrdefault brightcyan blue
-color header brightwhite blue "^from:"
-color header brightwhite blue "^subject:"
-color quoted brightgreen blue
-color signature brightwhite blue
-color indicator blue green
-color error red black
-mono error bold
-color status black cyan
-mono status bold
-color tree yellow blue
-color tilde brightmagenta blue
-color body brightwhite blue "[-a-z_0-9.]+@[-a-z_0-9.]+"
-mono body bold "[-a-z_0-9.]+@[-a-z_0-9.]+"
-color body brightyellow black "^Good signature"
-mono body bold "^Good signature"
-color body brightwhite red "^Bad signature from.*"
-mono body bold "^Bad signature from.*"
-color normal white blue
-color message green black
-color attachment brightgreen blue
+# mailing lists we are on (these are regexps!)
-# End of file...but it can go on and on and on....:)
+# SMTP mailing configuration (for sending mail)
-For the record, this is just a sample <path>.muttrc</path>. There are many more
-options that you can configure, such as integration with GPG. Have a look at
-<uri>http://www.dotfiles.com/index.php?app_id=27</uri> for more examples and
-You are now ready to test your <path>.muttrc</path>.
-<pre caption="Testing .muttrc">
-$ <i>mutt -y</i>
-This should open Mutt with a menu showing the Mutt mailboxes that you created
-in Test 2 when you ran the fetchmail command.
-Type the ? for help in navigating the Mutt Mailboxes.
-The final step is setting up nbsmtp the 'No-Brainer SMTP' used to send mail to
-your SMTP server. This setup is the easiest of all, as it only requires adding
-an entry in your <path>.muttrc</path> file.
-domain: The domain you want nbsmtp to say it belongs to. This will almost
-invariably be the same as the domain in your e-mail address.
+It is good practice to review all settings from the example above. There are
+many more, and some preferences may actually not match yours. Keep that in mind
+when you feel that Mutt at first doesn't really work the way you like.
-from@addr: This is the address you want nbsmtp to say the message is from. Note
-that this can be different than the "From:" line in your MUA.
+The example <path>.muttrc</path> above sets up an IMAP account, uses an SMTP
+server to send mail, stores its cache in <path>/var/tmp/.mutt</path>, reads the
+known address aliases (think of it as an address book) from
+<path>~/.aliases</path> and appends the signature from <path>~/.signature</path>
+when composing new mail. For some IMAP servers it may be necessary to change the
+spool, record and postponed directories, as the folders <path>Sent</path> and
+<path>Drafts</path> may be under a folder called <path>INBOX</path>. Simply
+trying this out with Mutt is the simplest way to figure this out.
-host: This is the smtp server you are sending to.
+Once your <path>.muttrc</path> is setup, you are ready to launch Mutt by just
+running <c>mutt</c>. If you entered a valid IMAP server url, Mutt will prompt
+you for your password and afterwards load all messages for you. Note that the
+first time entering your mailbox may take a while if you have quite some
+messages, since Mutt's header cache is still empty. If this succeeds you're in
+your IMAP mailbox ready to go.
-<pre caption="Adding SMTP support">
-$ <i>nano -w .muttrc</i>
-set sendmail="/usr/bin/nbsmtp -d isp.net -h smtp.isp.net -f urname@..."
-You are now ready to send a message. So in the Mutt pager or index hit the
-<c>m</c> key to compose a test message to send to your e-mail address. Mutt
-will use the value of the EDITOR or VISUAL for the composition editor unless
-you set <c>editor=</c> in the <path>.muttrc</path>. When you are done composing
-hit <c>y</c> to send your message. If there are no errors you will see 'sending
-mail' followed by 'Mail sent.'
+Navigation is intuitive, as is reading messages by just pressing the enter key
+or space bar. Mutt is quite Vim alike in that it uses key strokes to perform
+most of its actions. You best read Mutt's manual on the web to get yourself
+known with all existing functions (or press ? in Mutt) and what key they are
+bound to, or better, what key you like it to be bound to. Some essential keys
+are <c>m</c> (for message) to start composing a new message, <c>q</c> for quit,
+<c>r</c> for reply, <c>s</c> for save and <c>p</c> for print.
-Remember in <path>.muttrc</path> we have set where to save sent mail with
+One of the features that Mutt has that is still not in today's most savvy email
+clients is the ability to display attachments inline through some viewer. The
+auto_view directive in the .muttrc file tells Mutt which attachments (based on
+their MIME-type) it should view inline. To figure out how to do that, Mutt uses
+mailcap files to lookup how to display a certain MIME-type. Usually the system
+wide mailcap file isn't sufficient here, so you better start a
+<path>~/.mailcap</path> file to put items in there for <c>copiousoutput</c> that
+Mutt can display inline.
-Now to complete the test, run fetchmail again to get all your mail and verify
-you have received the message you sent to your e-mail address. When you find
-your test message, hit the <c>h</c> key to toggle a view of all the headers and
-see the complete mail transfer path.
+In the example <path>.muttrc</path> above <c>auto_view</c> is enabled for
+<c>application/msword</c> and <c>application/pdf</c> files. These two show
+the extreme usefulness of this capability, because it means meeting notes sent
+as doc file now are perfectly fine readable without having to save the
+attachment and open it in OpenOffice. Instead the text just shows up in the
+message reader, that is, if you have a matching entry in your
-There is one more program you probably want to add called urlview. This
-extracts the urls in message texts and sends them to your browser.
-<pre caption="Getting urlview">
-# <i>emerge urlview</i>
+<pre caption="Example .mailcap file">
+application/msword; antiword '%s'; copiousoutput; description=Word Document;
+application/pdf; pdftotext '%s' -; copiousoutput; description=PDF Document;
-Then create <path>~/.urlview</path> by copying the configuration file from
-<path>/usr/share/doc/urlview*/</path> and setting your browser command.
-You now have a powerful and highly customizable mail system. To take advantage
-of its flexibility, read all the manuals and docs and find the many user
-configuration files available on the web: search for <path>procmailrc</path> and
+The above <path>.mailcap</path> example tells mutt what to do to "view"
+<c>msword</c> and <c>pdf</c> files. For the former it should run a program
+called <c>antiword</c> (emerge <c>app-text/antiword</c>), for the latter the
+program <c>pdftotext</c> (emerge <c>app-text/poppler</c>). You can go wild with
+these to for example display rendered HTML (give <c>app-text/vilistextum</c> a
+try), render vcards, or show ASCII representation of attached images. All you
+need to do is define how to call the program in your <path>.mailcap</path>, and
+tell Mutt to try to view it inline using the <c>auto_view</c> directive.
@@ -506,86 +315,21 @@
-If you need to pass a username and password to your SMTP server, you can edit
-the <c>set sendmail</c> command in your <path>.muttrc</path> to include <c>-U
-<username> -P <password></c>, like this:
-<pre caption="Setting username and password for SMTP">
-set sendmail="/usr/bin/nbsmtp -U <i>username</i> -P <i>password</i> -d isp.net -h smtp.isp.net -f urname@..."
-If you do not want this information to be present in your <path>.muttrc</path>
-file, you can also create a <path>.nbsmtprc</path> file in which you include all
-<pre caption="~/.nbsmtprc example">
-auth_user = <i>username</i>
-auth_pass = <i>password</i>
-<title>Alternative: Using msmtp</title>
-<c>msmtp</c> is a simple alternative to <c>nbsmtp</c> with similar
-<pre caption="Installing msmtp">
-# <i>emerge msmtp</i>
-Now login as a normal user and configure msmtp by creating a
-<path>~/.msmtprc</path> file, filling in your SMTP server's information.
-Remember to set the permissions to a secure value!
-<pre caption="Configuring msmtp">
-$ <i>nano -w .msmtprc</i>
-<comment>#see man page for more auth options</comment>
-<comment>#If your SMTP Server supports TLS encryption, uncomment the next line
-Now set the permissions of the file to a secure value:
-<pre caption="Setting the permissions for the configuration file">
-$ <i>chmod 600 .msmtprc</i>
-Finally, edit or add the following line to <path>.muttrc</path>
-<pre caption="Using msmtp with Mutt">
-$ <i>nano -w .muttrc</i>
-Fire up <c>mutt</c> and send yourself a test email to see if it worked! See
-the msmtp man page for more options and another example.
+Mutt is a very versatile console email client. If you like the concept, Mutt
+can be altered to behave in nearly any way through its configuration. Search
+the web to find others explaining how they did "it", or find one of the many
+patches that exist to make Mutt do even more. Gentoo applies a couple of very
+popular patches to Mutt, so make sure to check <c>mutt -v</c> if you want
+something more to make sure it is not yet already at your disposal. While
+learning Mutt is not necessarily easy, once it is in your fingers, it can make
+your mail experience much faster and efficient than with other clients.
+Searching for example is quite powerful if you know how to hit the right flags
+and know which regular expression narrows your search down. Enjoy Mutting!