An Emacs Tutorial: Beginner’s Guide to Emacs

Emacs is a complex beast with thousands of commands and even more settings that can be customized. No wonder so many people find it difficult to get their footing and opt for simpler editors. That’s a shame, because although Emacs is complicated it does come with an excellent and exhaustive manual.

With that in mind, I have found there’s a gap between what the Tutorial sets out to do (basic movement and editing) and what people need to actually get started. This guide will help you move past the tutorial and should hopefully explain away some of the more typical questions that people have about Emacs.

Once you’re done with this tutorial then I highly recommend you read my book Mastering Emacs – it’s 280 pages long and it will take you from knowing nothing (or almost nothing) about Emacs to fluently mastering not only how to navigate and edit, but also how to make use of Emacs’s extensive, self-documenting help system.

Important Concepts

Emacs is very, very complicated – but it is also very, very old. That age is reflected in the sometimes arcane and baroque ways it handles things.

Terminology

The Buffer

In Emacs, a buffer is the area in which you write things. It’s where your source code is displayed and it’s where most of your time is spent.

A buffer need not point to a file; it can exist in the aether and never see the light of day on your filesystem. It can also be a transient thing (like the help file or the output from your compiler). In Emacs it is common to create and dispose of buffers as needed. If you need to do some quick string manipulation it’s very common to simply create a throwaway buffer (usually named “12312eqwdowqjd” or something to that effect), do your thing and then kill it.

The Window and The Frame

This is where Emacs terminology differs from the established standard. In Emacs a window is what people in other environments would call a frame – and vice versa.

A window is something a buffer is contained in. And windows, in turn, are contained in a frame. You can have multiple windows in a frame, but only one buffer in a window.

A buffer is said to be active when the point is in it; that is, if you were to type, your text would be input into that buffer.

The Point

The point is the caret, or cursor, in other editors and in most operating systems. Don’t confuse it with the mouse cursor though.

Modes

Modes are Emacs’ way of switching between key bindings, functionality, syntax highlighting and pretty much any other mutable item in Emacs. Modes are always buffer-specific, and they come in two flavors: major modes and minor modes.

In Emacs a buffer can only have one major mode, but any number of minor modes. That Emacs can only have one major mode is actually a serious obstacle in “multi-language” modes like a lot of web-based languages as they tend to mix very different languages in one file (HTML, CSS and Javascript for instance). There are some packages out there that provide support for this like nXhtml, an excellent package for most web-focused languages.

Minor modes are similar to major modes in that, when enabled in a buffer, provide a variety of changes and customizations. You tend to have lots of minor modes running in a buffer without necessarily noticing it. To get a complete list of all modes running and all the keybindings they introduce, type C-h m.

Best Practices / Quality of Life improvements

Some of the “best practices” here are contentious subjects and I’m sure I’ll get a flurry of e-mails and comments supporting or opposing them. But that’s life. Fact is though, if you’re starting out in Emacs you probably come from other environments (like Windows or Mac OS) where things are done this way and not that way.

The beauty of Emacs is that you can often have your cake and eat it (though you may have to write some emacs-lisp in order to do both.)

Your .emacs file

The .emacs file is the place where all your emacs customizations are typically kept. The .emacs file is also called the init file. This file is different from your custom file as that is where your Customization settings are stored - but more on Customize later.

When Emacs is starting it will look for the init file in ~/.emacs, ~/.emacs.el or ~/.emacs.d/init.el. As MS-DOS cannot have filenames beginning with a dot, an underscore is used instead (i.e., _emacs).

The tilde is obviously your home directory on Linux/Mac, but on Windows it will default to somewhere in your User’s My Documents directory.

*Windows Users*: I *highly* recommend creating an environment variable called HOME and then point that to a directory that will act as a “faux” home directory.

Evaluating changes and new code

So you’ve found a snippet on the internet and now you want to try it out. If you put it in your

.emacs file first, then the simplest way to load it is exiting Emacs and restarting it. However, that is not the most efficient way though:

If you have many distinct pieces of code you can select them and type M-x eval-region to evaluate the region; you can also type M-x eval-buffer to re-evaluate the entire buffer.

To evaluate one piece of code individually you’re better off just putting your point somewhere in the expression and typing C-M-x.

Changing Emacs Settings

Emacs has many, many settings, switches and toggles.

But changing settings in Emacs has always remained a tricky subject to teach newbies, whether you know Lisp or not. The big problem stems from the inconsistent way that settings are stored and retrieved; some aren’t settings at all but functions that you toggle on or off (like tool-bar-mode or menu-bar-mode for instance) and others take elisp functions that you have to write first.

Some settings are local to each buffer; others still are global, and some are re-set per “invocation”.

Where you put the commands to override settings will in turn depend on the specific package and functionality. I’ve tried to list some of the more obvious groupings here:

• Global; fire and forget.
• Local to a mode, so it should be set in that mode’s hook.
• Local to a buffer, so its default value should be overriden (for global changes) or when that buffer is created or initialised (for local changes)
• File local (settings are stored in a file, typically in a source code file’s header)
• Directory local (settings are stored in a special file and are read when files in that directory or any sub directory are opened)
• Files specific to a package or module, like Abbrevs and Yasnippet.
• “Customize” settings, more on those below.

To make matters worse, there’s another way of changing settings in Emacs: the Customize Menu.

The Customize Menu was introduced a long time ago as a way of standardizing and centralizing user settings. Chances are, if you’ve ever changed your syntax highlighter settings you’ve probably used it.

You can invoke it by typing M-x customize. Try it; browse around and go ahead and change things – Emacs is meant to be customized!

Your settings are saved to a file dictated by the variable custom-file (to read its value type C-h v custom-file) and are read once when Emacs starts up.

It is my personal recommendation that any changes that you can make through Customize are done so. Unless you really know your way around Emacs and possibly elisp it is by far the simplest and most user friendly way of doing it.

However, because I often reference changes directly I will suggest the more direct, brute, approach to changing things; this way is not necessarily better or worse, but it is easier to convey on a blog as the format the Customize menu uses is not conducive to “copying and pasting”.

I will ensure that whatever customizations or changes I mention here are, with few exceptions, “plug and play” – just drop them in the file I tell you to and you’re ready to rock.

What Emacs Version should I use?

You should be running GNU Emacs. There are other Emacsen out there, but GNU Emacs is the one I will concern myself with, as that is what I and the vast majority of Emacs users use.

The only other “competitor” to Emacs is XEmacs, a competing project that forked from Emacs back in the 90s and for a long time had GNU Emacs playing catch-up. Now, though, the roles have reversed: GNU Emacs is far more advanced, far stabler and has a much larger community.

For GNU Emacs you should, barring technical limitations, use Emacs 23.2 or any newer release after that.

GNU Emacs, unlike a lot of software products, rarely crash and suffer few major regressions between releases. So there’s no need to worry about upgrading as most releases are backwards compatible and aim to keep as many third-party modules working. For example, it is possible to download a compiled and working version of the latest Emacs release for MS-DOS!

Running Emacs in a Terminal

OK, so this is one of my pet peeves. I see many, many people run Emacs in a terminal emulator on top of their graphical window manager. Stop it, please.

I know it’s nostalgic and it takes you back to the roots of Emacs and pre-millennial computing and yes, I’m sure Richard Stallman himself runs it directly from a terminal. But please don’t.

I help out a lot of people on IRC asking how they can work around the byzantine keyboard limitations of terminal emulators and why C-s freezes their Emacs session (hint: it’s a paleolithic remnant from the mainframe days called software flow control.)

If you find yourself in a spot where using a Terminal across a SSH session is the most effective way to accomplish the task at hand, don’t let me stop you. But if you’re running Emacs locally in a terminal on your own machine you’re intentionally handicapping yourself and disabling a lot of useful features that aren’t available to you in a terminal, like proper font and color support.

To help convince you let me dispel a few common “reasons”:

• Reason: It is the only effective way to edit files remotely.

  You can probably use TRAMP to manipulate files remotely. For tasks where that is not possible Emacs in a terminal may well be the only thing that’ll get the job done Right Now.

• Reason: Emacs in a terminal is faster.

  Maybe. It’ll still take as long to load as before, as loading libraries will happen regardless of the environment you’re running it in. If you’re talking about graphical lag then that is certainly a possibility. Emacs’s display engine has gotten slower as more and more features are piled on. It shouldn’t be a problem for most modern computers though.

• Reason: Emacs in a terminal means I can use screen to switch between shells.

  You should consider running your shells inside Emacs directly. Emacs has most of the facilities needed to emulate a dumb terminal (with stdin, stdout and stderr redirected to Emacs) or even an almost fully-compatible ANSI-capable terminal.

• Reason: I like the minimalist look of Emacs in a terminal

  That’s easy to fix. Put the following in your .emacs file to hide all the extraneous crap:

  (menu-bar-mode -1)
  (tool-bar-mode -1)
  (scroll-bar-mode -1)

  That’ll hide the menu-bar, tool-bar and scroll-bar.

CUA Mode

The first thing I want to mention is CUA-mode. CUA (Common User Access) was IBM’s attempt at reining in all the conflicting ways users could interact with their programs. Most of the standards set forth back then have carried over into most modern operating systems and the programs running on them.

Emacs does not play nice with most of those standards, mostly because Emacs has been around for a lot longer, and partly because – unlike WordPerfect, WordStar and similar “killer apps” of the 90s – they no longer exist or have changed their user interfaces.

Common conflicts include the eponymous C-x and C-c keyboard modifiers. To most of us they are cut text and copy text respectively, but in Emacs they are modifier keys.

Thankfully for the CUA fans out there there is an aptly-named mode called “CUA Mode”. To enable it type M-x cua-mode.

However, cua-mode is not perfect. There are side-effects and flaws you need to be aware of:

• cua-mode redefines C-z, C-x, C-c and C-v (undo, cut, copy and paste respectively)
• C-x and C-c will behave like it would without cua-mode when you do not have text selected (no “region”)
• When the region is active it will act like normal CUA editing operations: cut, copy, paste – and so on.
• If you want to use the C-x or C-c as modifier keys with a region active you must either type the modifier key twice in a row really fast or use the shift key with the prefix key (C-S-x, for example).
• You are likely to run into peculiarities with more exotic modes and features in Emacs that may not be aware of cua-mode.
• You are ignoring the many advantages Emacs’ own text editing facilities provide – facilities that are far more advanced and feature-rich than your standard CUA-style editor commands.

And don’t forget, you can still use S-DEL, C-INS and S-INS to cut, copy and paste respectively.

Personally, I never bothered with cua-mode. Surprisingly I don’t find it difficult to switch between the different “mental modes” when I’m not using Emacs.

I’d recommend you don’t bother with it either though. It’s too much effort to compromise with such a core part of Emacs, especially when you will probably never use some of the more advanced editing concepts as a result.

Line numbers

It is possible to enable line numbers in the margin of the active buffer by running M-x linum-mode. To enable it globally for all buffers run M-x global-linum-mode.

To enable it globally and permanently add this to your .emacs file:

(global-linum-mode 1)

Now you can customize it further with:

M-x customize-group RET linum RET

IDO Mode

Ido, short for “Interactively Do Things”, is a fantastic addon that is bundled with Emacs. Basically it makes switching between buffers (and optionally files) really easy as you simply type parts of a name and Ido will automatically narrow the list to just the ones matching the search text.

I use Ido for everything (and it is extensible enough that you can use it to power your own code that requires completion) and I feel it is a must to use it in Emacs. No more fiddling around with typing out long, complicated buffer names or futile TAB’ing.

I’ll write a longer post espousing the virtues of Ido at some other point, but for now I recommend you put this in your .emacs file:

(ido-mode 1)

(setq ido-enable-flex-matching t)

IF you want Ido mode to work with C-x C-f (find-files) then add this as well:

(setq ido-everywhere t)

Some people find Ido’s find-files support a bit intrusive. Just remember that if you type C-f Ido will revert to the old-style completion engine!

Hiding the splash screen and banner

Emacs by default will pester you with a splash screen and a message in the echo area. To disable both, and have emacs default to its *scratch* buffer, add this to your .emacs:

(setq inhibit-startup-message t
inhibit-startup-echo-area-message t)  

Rebinding the CAPS LOCK key

If you ever plan on making Emacs your home away from home, your first step is to rebind your CAPS LOCK key. I know some people actually use it, but I’m one of the people who do not. So to me, rebinding CAPS LOCK is a good way to avoid the dreaded emacs pinky (so named because your pinky has to contort itself to reach the CTRL key on most keyboards.)

Getting used to the rebound CTRL key will take some time, so I suggest rebinding CAPS LOCK but leaving your old CTRL key intact so you wean yourself off the old CTRL key. On MS Windows I recommend SharpKeys, a free tool that permanently rebinds the keys. On Linux you can use xmodmap or the ‘System -> Prefs -> Keyboard’ section if you’re using Ubuntu and Gnome.

And finally, to make up for the fact that you no longer have a CAPS LOCK key I suggest learning the following keys instead:

• To UPCASE A REGION type C-x C-u; to UPCASE a single word, type M-u
• To downcase a region type C-x C-l; to downcase a single word, type M-l
• To Capitalize A Region type M-x capitalize-region; to Capitalize a single word, type M-c

You can use the universal argument construct to alter how many words are transformed ahead of point; and to make the transformation go backwards (behind point) use the negative argument modifier.

Making Emacs Auto Indent

For some insane reason Emacs will not auto-indent the point when you press RET. To do that you must type C-j. I don’t like that at all; yes, there are perfectly valid reasons for why you wouldn’t want to indent automagically. I prefer to enable it globally and then disable it locally for each mode I do not like.

Here’s how you would enable it globally:

(define-key global-map (kbd "RET") 'newline-and-indent)

How do I customize the Font and Background

There are a couple of ways of telling Emacs how to do this. I personally prefer using the Customize menu.

To customize the default font and color, type M-x customize-face RET default RET.

To customize the default syntax highlighter (also called “font locking”) typeM-x customize-group RET font-lock-faces RET.

Don’t forget to save your settings.

Undoing changes

Emacs has a very unique clipboard (called kill ring) and undo feature (called the undo ring) that few other editors have. Both are based on the concept that it should be impossible (or next to it, anyway) to lose your changes. So don’t worry about undoing changes and then editing your document; the changes you undid are still there. Simply “undo” the changes you just made and eventually Emacs will “undo” the “undone” changes. Confused? Yeah, me too.

Most people type C-x u or C-_. I prefer the far more accesible C-/, but then again I use US keyboard settings.

Loading New Packages

Packages, modules, files, collections. I don’t think the Emacs community ever really settled on a particular word for one or more files you download and load. I tend to prefer package or module myself, though.

Loading packages is usually a simple matter of, well, reading the manual… OK, so that’s not an answer but that’s usually true. It does happen though that the file does not come with a manual – maybe you got it on EmacsWiki and the author never intended for it to be used by newbies.

So if you’re stuck without a manual try opening the file (in Emacs of course!) and look in the comment header for instructions. Most files will have the instructions listed there and possibly even some usage examples, depending on what the package sets out to do.

If that fails, you can try loading it yourself with this generic, handy-dandy guide.

Setting up your load path

Your load path is where Emacs will search for files to load.

To inspect the load path you can type C-h v load-path RET. That command asks Emacs to tell us the value (and any documentation associated with the variable) and print it in a buffer.

If you put your package anywhere in one of those places, Emacs will find it. That’s not very flexible though, and you may not have permissions to write in any of them. So let’s add our own. Add this to your .emacs, substituting the example path below with one of your own choosing. I recommend ~/.emacs.d/ or another sub-directory to your home directory.

;; You can change the path here
(add-to-list 'load-path "~/.emacs.d/")

Now that you’ve added a custom path you can put your files in there. If your package has lots of files and its own directory structure you can go ahead and explicitly instead.

Loading the package

Emacs can load files in one of several ways:

• By invoking (require 'feature) if the package has (provide 'feature) somewhere in the file.
• By explicitly calling (load-library "packagefilename"). I would recommend this unless you know the name of the feature provided by the package.

Whichever way you pick, add it to your .emacs – but add it after you update the load-path!

Testing that it worked

Now you can either restart Emacs and see if it works, or you can select commands you added above and run M-x eval-region. If it worked, not much will happen. You can switch to the buffer *Messages* and see if you can spot any errors.

Now you’re ready to use your new package.

Conclusion

That covers some of the major questions the tutorial leaves unanswered, plus a few of my own personal preferences thrown in for good measure. Feel free to share yours by either contacting me or posting a comment.

Further Reading

I recommend reading my article series Effective Editing in Emacs. It will teach you how to move, edit and find what you’re looking for – all things people spend years mastering.