The very unofficial .emacs home The very unofficial dotemacs home
emacs
Sections
home
what is this all about ?
customization basics
special topics
local dotfiles
dotfiles on the web
new and updated pages
useful sites and pages
search locally
EMacro
OS/2 Emacs
Special topics
dotfiles and custom
multiple Emacs and OS
errors in your dotfile
Latest Additions
local files:
John J. Glynn
David Jolley

linked files:


articles:


links:
The Emacs wiki

Why should I customize Emacs ?

If the standard configuration of your Emacs distribution works right out of the box for you, there is no need to customize anything.
But hey, you're here, looking for Emacs customization info, so it seems as if not anything works the way you would like it to work.

This is one strength of Emacs:
you can change almost anything to fulfill your needs.

How can it be done ?

There are a couple of ways to do this.
  • Use Emacs build in customization features
    This is the easy way, Emacs guides you through the process and displays Information about what and how to custumize. All the packages of the standard Emacs distribution and most of the additional packages floating around support this. Customize is available since Emacs 20.xx
    If you'd like to see a nearly full expanded tree of customization groups and entries, take a look, but be warned, it is a big one.
    This might give you an idea what you can do with customization buffers.
  • Use customization files, read on startup
    This is a bit more difficult to handle than customization buffers because you exactly have to know what to customize and how to do it. On the other hand this has a lot of pros:
    • You're able to customize older packages which are not aware of custom
    • You're able to use your customization with multiple versions of Emacs on multiple machines with different operating systems
    • You're able to set up customizations for multiple users with a site-start.el
    • You're able to customize all aspects of a package, not only those which are present in the customization buffers.
    • You're able to add small or big extensions via the definition of your own hooks, functions and more.
    • And last, but not least, your able to put in comments about why and how you did it and send me a copy to publish it on this site.
  • Write your own extensions to Emacs
    This is the most elaborate way to teach Emacs how to do a certain thing. You should be a lisp programmer and have good knowledge of Emacs and elisp. This way you can do almost anything with Emacs. It's up to you fantasy !
This site is about Emacs dotfiles, so prepare to roll your own dotfile.

What is a dotfile ?

If you're using Emacs on a unix machine you'll probably already have some, because most Unix programs store their information in dotfiles. Using Emacs on M$ systems or on a Mac is a bit different, they don't know anything about dotfiles. So here is a short excurse about dotfiles:

A dotfile is a text based configuration file. The name of these files begin with a dot (like .emacs). That's why they are called dotfiles. The reason for the filename beginning with a dot is that those files are considered to be hidden files on a Unix system. This way you won't see them until you really want to. The dotfiles are placed in the users home directory, which is another feature of Unix not known by M$ or Apple. There is no common format for the content of a dotfile beside the fact that all of them are text files. This way they can be viewed and changed by the user with a normal editor (if he/she knows what he/she does) and can also be modified by any other program which can work with text files. The internal format of the dotfile depends on the program which is configured by the file.

Emacs dotfiles consist of a collection of elisp expressions which are read on startup and evaluated.

Where to put the dotfile

Into your home directory, of course.
M$ user should first set up their home:
Make a new directory anywhere on your hardisk, network drive or anywhere else where you can permanetly reach it. The name doesn't matter, but home seems to be a quite clear choice. Setup an environment variable named HOME which points to the directory you've created.

Goeff Voelker has described this in deep in his FAQ
I don't know for sure wether the Mac has environment variables, but I think Andrew Chois GNU Emacs port for the Mac comes correctly setup together with an Emacs dotfile.

If all is setup the right way, you can open a new or existing .emacs in your home directory by typing C-x C-f ~/.emacs

How to organize it

If you just want to customize a few simple variables you don't have to think about organizing your dotfile, but if you want to do more, I strongly recommend to divide the dotfile into separate sections with leading comments about what the sections are good for.

I've had four major sections in my dotfile: a general section for variables and other simple customizations, a w32 specific section, a section for loading and customizing specific modes (mainly programming modes) and a section to try out all these packages I don't know.

Organizing your dotfiles makes it easier to add things from other peoples dotfiles because you can see if you've already customized a certain variable or mode. This also gives you the option to divide it into separate files if it grows more and more.

A lot of files available via this site are organized this way, so there must be a reason for this.

Managing multiple Emacs versions and multiple platforms

Well, normally you'll use one kind of Emacs, but what if you're working in a company which uses GNU Emacs on Win NT and at home you've decided to use XEmacs on your Linux box ? Or vice versa ? It would be really helpful to use one configuration on both machines. But how ? GNU Emacs and XEmacs are a bit different and Win and Linux are more than different !

There is a solution for this. Emacs provides a version info you can ask for. Enter the following in the buffer named *scratch*:

(insert "\n" (emacs-version))
and evaluate it by typing C-x C-e
Doing this you should see a string like
GNU Emacs 20.4.1 (i386-suse-linux, X toolkit) 
of Mon Nov  8 1999 on Bareis
or
GNU Emacs 20.6.1 (i386-*-nt4.0.1381)
of Tue Feb 29 2000 on buffy
or what ever.

As you can see, the type of Emacs, its version number and the operating system are available. The OS is a copy of the variable system-configuration. To be on the sunny side if somebody decides to remove this from the emacs-version, you should compare your OS against system-configuration instead of comparing it against emacs-version (thanks to Rob Davenport for pointing this out).
This way, you can easily test what Emacs you're running and on which platform.

Here is a template to insert into your .emacs which handles different flavours of Emacs on different platforms.

;;
;; check wich Emacs we are running, and on which platform
(cond
     ((string-match "GNU" (emacs-version))
        (message "customizing GNU Emacs")
	; put all the GNU Emacs specific customization in here
        ; But first do the things which depend on the OS:
        ;   setting the load-path and 
        ;   loading packages available only for a certain OS 
	(cond 
             ((string-match "linux" system-configuration)
                (message "customizing GNU Emacs for Linux")
                ; anything special about Linux begins here 

                ; and ends here
	     )
             ((string-match "nt4" system-configuration)
                (message "customizing GNU Emacs for Win NT")
                ; anything special about Windows begins here 

                ; and ends here
	     )
        ; anything special for the OS ends here
        )
        ; all the common things for different OS start here


        ; and end here

     ; GNU Emacs specific stuff ends here
     )
     ((string-match "XEmacs" (emacs-version))
        (message "customizing XEmacs")
	; put all the XEmacs specific customization in here
        ; to handle OS specific things look at the GNU Emacs section.


     ; XEmacs specific stuff ends here
     )
)
Be sure set the right strings for your OS as shown by system-configuration.

How to split the dotfile into pieces

As time goes by, your .emacs will grow and grow. Handling multiple Emacs versions and multiple OS also might make your dotfile quite large and cluttered.

To do the next step, you should split it into separate files and only use the .emacs to load these files. This can simply be done by inserting a statement like this:

(if (file-exists-p "NameAndPathOfTheFile")
    (load-file "NameAndPathOfTheFile"))
This way the template above could look like:
;; -------------------------------------------------------------------
;; load customizations split into pieces for better maintainance
;; put information about what was loaded into the messages buffer
;; -------------------------------------------------------------------
;;
;; check which Emacs we are running and on which platform
;; load the right customizations.
;;
(cond
    ((string-match "GNU" (emacs-version))
	(cond 
             ((string-match "linux" system-configuration)
                (if (file-exists-p "~/.emacs-gnu-linux")
		    (progn
                     (message "loading GNU Emacs customizations for Linux")
                     (load-file "~/.emacs-gnu-linux"))))
             ((string-match "nt4" system-configuration)
		(if (file-exists-p "~/.emacs-gnu-win")
                    (progn 
                     (message "loading GNU Emacs customizations for Win NT")
                     (load-file "~/.emacs-gnu-win"))))
        )
        (if (file-exists-p "~/.emacs-gnu-all")
            (progn
             (message "loading GNU Emacs customizations common to all OS")
             (load-file "~/.emacs-gnu-all")))
    ) ; matched GNU
    ((string-match "XEmacs" (emacs-version))
	(cond 
             ((string-match "linux" system-configuration)
                (if (file-exists-p "~/.emacs-xemacs-linux")
                    (progn
                     (message "loading XEmacs customizations for Linux")
                     (load-file "~/.emacs-xemacs-linux"))))
             ((string-match "win32" system-configuration)
		(if (file-exists-p "~/.emacs-xemacs-win")
                    (progn
                     (message "loading XEmacs customizations for Win")
                     (load-file "~/.emacs-xemacs-win"))))
        )
        (if (file-exists-p "~/.emacs-xemacs-all")
            (progn
             (message "loading XEmacs customizations common to all OS")
             (load-file "~/.emacs-xemacs-all")))
    ) ; matched XEmacs
)
(if (file-exists-p "~/.emacs-all")
    (progn
     (message "loading Emacs customizations common to all Emacs and all OS")
     (load-file "~/.emacs-all")))
Now all you have to do is to fill the various files with the right content and add more files as you need them. If you try to use the same dotfile at home and at work, it might be a good idea to get mail and news related things into separate files, different for home and work.
As always with Emacs, there are several ways to do this:
One way, fitting to the load on demand strategy metioned above could be:
(if (file-exists-p ".emacs-home")
    (load-file ".emacs-home"))
(if (file-exists-p ".emacs-work")
    (load-file ".emacs-work"))
This won't work well if both files are present :)
Rob Davenport suggested an other solution for this:
As I was getting it working on my machine I also thought about how to partition it so I could use the same Emacs on my work and home PC. The best thing I came up with was to use:
  (cond ((string-match "HOMEPC" (system-name))
           ... define home email address etc.
        )
        ((string-match "WORKPC" (system-name))
           ... define work email address etc.
        )
  )
(where HOMEPC and WORKPC are the machine names of the home and work PCs involved, respectively.)

What next ?

Just do it !
All content copyright by the contributors. Website maintained with Emacs , wsmake and html-helper-mode
Emacs community logo by Daniel Lundin Last updated on Sat Jan 22 14:57:03 2005 by Ingo Koch