Modifying the .emacs File Directly

It's possible to customize Emacs in just about any way you can imagine. Almost everything you see on the screen, every command, keystroke, message, and so on, can be changed. As you may imagine, most customizations involve the Emacs startup file .emacs.

The previous section discussed the interactive customization tool, Custom, but left out some of the details on what happens any time you "save for future sessions." Custom places the configuration information in your .emacs file. Some things simply cannot be done through Custom (yet). Once you get familiar with the types of statements that go into your .emacs file, you may also just find it easier to add a line or two directly.

We should emphasize that using Custom or editing .emacs by hand is not an either-or proposition. When you save options via Custom, it adds its settings to the end of your .emacs file and warns you not to edit them by hand. Despite this prohibition, you can easily add your own customizations to the beginning of that file. To illustrate this, Example 10-1 shows a sample .emacs file for Mac OS X that shows edits made directly by the user as well as sections added by Custom (shown in bold)


Some changes require a knowledge of Emacs Lisp programming (see Chapter 11); others are simple enough without such knowledge. In this chapter, we cover a variety of useful customizations that require no programming knowledge. For now, however, you need to know this: every Emacs command corresponds to a Lisp function, which has the form:

(function-name arguments
               )

For example, if you want to move the cursor forward by a word, you type M-f. What you are actually doing is running the Lisp function:

(forward-word 1)

Two important comments concerning .emacs files are in order. First, if you are inserting code into your .emacs file, you may end up putting in something that causes Emacs to fail or behave strangely. If this happens, you can invoke Emacs without running your .emacs file: simply invoke Emacs with the command-line option -q, and Emacs will not run your .emacs file. (Chapter 13 gives instructions for starting Emacs from the command-line on Windows and Mac OS X.) You can then examine the file to figure out what went wrong.

The other comment is perhaps the most important piece of advice we can give you concerning customizing your Emacs environment: steal mercilessly from other users. In particular, if you are dealing with a messy situation involving a configuration problem or a subtle point about some specialized mode, it is possible that some other user has solved the problem(s) already. This is not dishonest or subversive in any way; rather, it is encouraged by the makers of GNU Emacs, who would rather software be shared than kept to oneself. Emacs even provides an easy way to try out other users' .emacs files: invoke Emacs with the option -u username, and username's .emacs file will run instead of yours. (Of course, this works only with users on multiuser systems.)

In fact, numerous example .emacs files are available on the Web. (Check out "the very unofficial" .emacs site, http://www.dotemacs.de/.)

Here's a quick example of a (very) simple .emacs file:

;; Turn on font-lock mode to color text in certain modes 
(global-font-lock-mode t)

;; Make sure spaces are used when indenting code
(setq-default indent-tabs-mode nil)

The lines beginning with two semicolons are comments. They're meant to help you understand what is being configured. Sometimes they also list possible values or the previous value. You can say anything you want in a comment—as long as it fits on one line. If you need to spill over onto a second or third line, just begin each successive line with ;;.

Blank lines are ignored. Every other line (that's not blank or a comment) is considered part of a Lisp program that is executed to configure your Emacs session. In this example, we first call the global-font-lock-mode function with an argument of t (true, or "on"). Next we make sure that using the Tab key when writing code doesn't actually insert a tab character but uses spaces instead. (This is a good thing to do when writing code—otherwise your code can come out very messy on systems that use a different tab width.) We use the setq-default function to assign the indent-tabs-mode a nil (false or "off") value. Using setq-default has the advantage of setting the default value only—modes that choose to override this value may still do so.

If you're a seasoned Lisp programmer, you can do anything you would normally have access to in Lisp. There are certainly particular functions and variables you need to know about to be effective, but it is just a Lisp program.

For the rest of us, this file mostly consists of blocks of Lisp found on the Internet or on a colleague's computer. You edit in your personal values and hope it all works. Really. If you use Custom to manage all of your configuration changes, you don't even have to look at .emacs unless you want to add your own lines at the beginning of the file or look at what Custom has done.

The great thing about configuring a text editor is that you can use the editor itself to make the changes. You can visit the .emacs file just as you would any other file. The only thing to watch out for is where you are. Some folks put backup copies of this file in strange places. You want to edit the file that came from your home directory. If you're unsure of where you are, you can use the full name ~/.emacs which Emacs translates to the proper directory.

Note also that .emacs is not required. If you haven't had any reason to customize Emacs, it might not exist. But you should feel free to create it when you're ready to start tailoring your environment. (Making your first change via Custom will also create .emacs if it doesn't exist.)

The best way to deal with this file really is to find an example file and make small changes to it. Use those ;; comments liberally. If you're going to change a line in your .emacs file, make a copy of it first:

;; Turn off font-lock
;;(global-font-lock-mode t)
(global-font-lock-mode nil)

That way you can easily get back to a known, working version of your .emacs file. If things get really bad, just start over. Rename your current .emacs file and then copy and paste small chunks of it at a time.

For changes required by modules and other packages, the documentation for those modules usually includes example lines for insertion into your .emacs. For example, the JDEE site includes a sample .emacs file that can be used as-is or appended to an existing file. (And if you want to get fancy, you can leave the JDEE sample in a separate file and simply include a load-file call from your .emacs file. More on load-file can be found in the Elisp documentation.)