Emacs Bootstrap Tutorial

This tutorial is aimed to help users who need to know the very basics of invoking and learning GNU Emacs. It was written because many tutorials seem to overwhelm the reader with too much detail, causing them to give up on Emacs entirely because "it's just too complicated". This strives to give sufficient detail to get you started, but shows how to get more info later when it is desired, all within one Emacs session. This tutorial presumes you have X windows up and running, and are not executing Emacs in text-only mode.

Very important things to do before you start

Be sure to disable your X window managers (GNOME/KDE) bindings of things like Alt-x (any letter, not just x, actually) so that they are allowed to pass to other X applications. This is because those key bindings come under heavy use in Emacs. If you don't do that, then the X window manager will process those keybindings, and not pass them on to the Emacs session. Increase your type repeat rate. This will make it much faster to scroll around in Emacs buffers with C-n and C-p (explained below). Doing this should help the new user move around efficiently until they need to learn the more obscure key bindings that are useful in certain modes (such as ever so useful C-M-u binding inside C and C++ buffers).

Magic decoder ring for Emacs concepts

The Emacs Manual that comes with (or should come with it unless they Linux distribution packages it separately) your Emacs has an abbreviated way of describing about key bindings that can seem strange to the new user:

• C-n means that you should hold the Control key down, press n, and then let go of both keys.
• C-h m means that you should hold down the Control key, then press h, then let go of both keys, and then press m.
• C-h C-m means that you should press and hold the Control key, then press h, release h, then press m and then release all keys.
• M-x to mean that you should press and hold the Alt key, then press x, and then release both keys. If you are a vi user making the transition to Emacs, you will find yourself hitting the Escape key (which isn't very efficient since it takes your left hand off of the keyboard), which is an alternative to holding down the Alt key.
• C-M-u means that you should press and hold the Alt and Control keys together, then press the u key, then release all keys.

When you start reading parts of the Emacs Manual (or the Elisp Reference manual), you will see references to the "point". The "point" is where new characters will be inserted into a buffer when you are typing interactively. The cursor will be blinking on a given character, and when you type a new character, that new character will push the character under the cursor to the right. This is similar in concept to how the "i" command in vi works.

Starting Emacs with nothing

When you first start out, you will not have any ~/.emacs configuration file, and that is ok for now. For this tutorial, we will stick with this basic configuration that lacks a ~/.emacs file, because you can still learn a lot with the uncustomized Emacs session. Invoke Emacs in a mode that doesn't load the ~/.emacs configuration file by typing (into a terminal window): emacs -q. What you should see in the X window that pops up is some text and maybe a picture of some strange looking animal. Some of that text is highlighted in blue and act as links that you can click on with your mouse (or navigate to with the cursor and hit Enter). This area of the Emacs window containing pictures and text is called a "buffer", and it is not associated with any file. I explain the concept of buffers later on in the Emacs windows versus X windows versus buffers section. Only a limited number of keys are actually bound in this initial buffer. Hit the TAB key until the cursor is sitting on the Emacs Tutorial link, and hit the Enter key. A new buffer will be displayed that contains a tutorial that explains basic key navigation. Use C-n and C-p to move line by line up and down in that tutorial buffer until you read about the other keybindings. Read through that tutorial enough to get comfortable with using the control key with other keys to move the cursor around in the buffer. Then type C-x C-f to open up a buffer on a new or existing file. Look for the prompt at the bottom of the window. That prompt is called the "minibuffer" and is used for prompts for things like file names, as well as the area to emit messages for errors and warnings. Enter in a path to a file name, backspacing over the previous file as needed, and then hit Enter. Here is where you type in new text. Depending upon the mode you are in (a C file? A text file?), the coloration of the text will change. This is called fontification in Emacs, and is explained in the manual. If you opened a file in some protected area, such as /etc, then when you start typing, a message will show up in the minibuffer stating that the buffer is read-only. That is because you lack the permissions to edit it. How do you get to read the manual from inside Emacs? Type C-h i, then scroll down to the Emacs Manual. But there are other useful bindings that you will be using a lot as a beginner, explained next.

Useful Emacs key bindings

Here are the bindings that I think are most useful to know about when you are first starting out. This is just the tip of the iceberg of key bindings available in Emacs. You can't learn them all right away, nor should you have to, so Emacs provides you with a way to discover more bindings as you see the need (C-h b and C-h k). Here they are:

• C-g -- Get back to normal text editing if you find yourself stuck in some mode you don't understand.
• C-x C-f -- Opens (finds in Emacs parlance) a buffer that is visiting a file. You may or may not be able to edit and save the buffer to that file, depending upon the filesystems permissions.
• C-x C-s -- Save the current buffer to the file it is visiting. If the buffer is not visiting a file, you will be prompted for the file into which to save. Notice that this is not C-s which is what you would use in some editors, and that is intensional. Think about it! How often do you need so search around in the same text file for stuff, as opposed to saving? Most of the time, the more frequent operation is incremental search (C-s), and saving the buffer is less often (C-x C-s).
• C-x C-w -- Write the buffer to another file.
• C-h b -- Pops up a new buffer in another window (see Emacs windows versus X windows below for the Emacs definition of window versus the X Windows definition) that summarizes all of the keybindings in the buffer in which you typed C-h b. This is how you can find out all about the keybindings associated with a given buffer. Type C-x o to go to the other buffer (C-x o is explained below). Scroll down until you see something interesting, such as the binding for C-a, then hit the TAB key to position the cursor on the function name to the right of the key binding (e.g., for C-a it would be move-beginning-of-line). Then hit the Enter key. The window will change its buffer over to a new buffer specifically for describing the move-beginning-of-line function. In that new buffer, keep hitting the TAB key until you see the cursor sitting on the "back" link, then hit Enter. When you do that, you will be back into the buffer that summarizes the key bindings.
• C-h k -- Typing this in any buffer will then cause Emacs to prompt you (at the bottom of the Emacs frame) to type in one or more key sequences until it determines a binding, and then displays a help buffer showing what that binding is bound to. Try it: In any buffer, hit C-h k, then type the letter a. A new buffer will likely show up displaying the function a is bound to (e.g., it most likely will be bound to a function called self-insert-command which is used for many of the letters such as a through z, punctuation characters, etc., but does not necessarily have to be bound). Try it again: Type C-h k, wait for the prompt, then type in C-h k again. The help for the C-h k key binding is then displayed. Notice how the help text also indicates what other keys or menus the function (e.g., describe-key) is bound to. Wouldn't you like to see that in Microsoft Word???? I would. Actually, I'd like to see Microsoft Word die a fiery death, but that is diatribe for another day.
• C-x o -- Moves the cursor into the other window inside the current Emacs frame. If there are more than two windows, then the cursor will visit all of them in turn, eventually landing your cursor in the first window you started in.
• C-x 1 -- Makes the current buffers window take up the entire Emacs frame. I use this one quite constantly when I'm editing source code, where I want all the other clutter in the window to just go away (but without deleting any files or damaging any other buffers contents)!
• C-x 0 -- Makes the current buffers window disappear, leaving more real-estate for the other windows in the frame. The file that may or may not be associated with that buffer is not deleted or modified, nor is the buffer deleted, and you can see that buffer still exists by using C-x C-b.
• C-h i -- Opens up a new buffer that is in Info Mode. That mode has many of the usual key bindings changed to ones more appropriate for reading and navigating around manuals not unlike you would see in a web browser, but focused on using the keyboard (and to a lesser extent, the mouse). Use C-n and C-p to move up and down in that Info buffer. It is here that you should see the Emacs Manual along with a few other manuals that have been published as info files, such as the Elisp manual which you will need to read for doing heavy customization work. Use the TAB key to move the cursor to a link in the Info mode, and then hit Enter to view that manual. Familiarize yourself with the special key bindings used in Info mode (there is an Info manual for this purpose there, too).
• C-s -- Starts an incremental search. By incremental, I mean that each character you type will search for characters in the current buffer in succession (and those characters should form a consecutive chain of characters somewhere in the buffer). Type C-h k and then type C-s to find out what keys are to be used during the incremental search. After you find the spot in the buffer, hit Enter to terminate the incremental search. If you hit C-g, then it will return you to where you started the search. Note that if you want to match the end of a line, hit C-j while entering in other characters. Try to do that in vi!
• C-h C-b -- Pops up a new buffer that displays a list of other buffers in your Emacs session. Select that buffer with C-x o and then use C-n and C-p to move the cursor to one of the lines showing a buffer you would like to view, and then hit the Enter key. See What's productive and what is not below for my take on why I think this, and the C-h b binding, are important features.
• C-h b -- Prompts you for the name of the buffer to switch to. Use the Tab key repeatedly and then type the first letter of the buffer name you wish to visit, hitting Tab again as needed to complete the name. Once you have filled out the name completely, then hit the Enter key. The current Emacs window will switch its buffer over to that buffer you selected. This is similar to C-h C-b, but is to be used when you know part of the name of a buffer you want to visit (and is faster in that case).
• M-x -- Prompts you for an interactive Emacs command. Try it: Type M-x, wait for the prompt, then type describe-key, and then hit Enter. Then type the m key. What you should see is something like the self-insert-command function being described, but you could see something entirely different depending upon the mode of the buffer you were in when you first typed M-x.

To take advantage of the power Emacs gives you, you will eventually want to invest time learning how to customize your Emacs to your work flow. And you won't be able to learn all of Emacs in two weeks, nor should you try to, as there is just too much functionality there. Just learn new info as you find the need.

Emacs windows versus X windows versus buffers

Since Emacs can be used in a X terminal as well as a X window itself, the manual uses the word "window" to mean part of the main X window that houses a buffer. Emacs refers to the top level X window as a "frame". In Emacs, X windows contain a single Emacs frame, and that Emacs frame contains one or more windows that divide up the Emacs frame into non-overlapping sections. Each of those Emacs windows will house exactly one buffer, and that buffer may or may not be associated with a real file on the filesystem. You can and should switch the buffer displayed in a given Emacs window as you see fit. Contrast this with X Windows (and Microsoft Windows) overlapping windows approach. Emacs does it this way so that you don't fight the windowing system for control over the screen real-estate. You use key bindings such as C-x 0 and C-x 1 to manage them quickly and efficiently, with ruthless abandon, while leaving the top level Emacs frame alone. In fact, I maximize my Emacs window to cover the entire screen, and just use Alt-tab to switch to other top-level X windows such as Firefox when I have no other choice.

Emacs modes

Emacs buffers are a concept that allows for different behavior depending upon the editing or viewing context: One example of this is that you can view a directory listing and do file operations in that listing from within a buffer. Another example is editing C++ files using special key bindings that make editing C++ files more efficient than if you used a plain text editor (e.g., the C-M-u, C-M-n, and C-M-p bindings explained later). Each of those different editing "contexts" is called an Emacs mode. Buffers and files are different concepts in Emacs. The difference between a "buffer" and a "file" is that a buffer is a Emacs concept of a view that shows the contents of any arbitrary text or pictures. Some of those buffers may, or may not, be viewing real files on the filesystem. That is intensional because you can do various things in Emacs with special buffers that have key strokes bound in all sorts of wacky ways. That variation in key bindings from buffer to buffer really irritates the snot out of vi users making the transition Emacs. That annoyance abates when they receive Emacs Enlightenment, which is when they realize that they can rebind those keys to whatever they want and do all sorts of things that many folks believe Emacs shouldn't be doing at all. Emacs buffers have one or more modes associated with them, so that the keybindings for that mode can be different from other buffers that have different modes. Contrast this with vi which has only two modes: one for inserting text and a command mode (excluding ex commands of course which is similar to M-x command entry in Emacs). For example, the Info mode will have special bindings that allow you to view manuals quickly, but editing a C++ file has radically different needs, and therefore, different key bindings. Read the Emacs Manual for a more in-depth description of major versus minor modes. The minor modes mixing and matching different key binding behaviors to get exactly the behavior you desire.

Customizing Emacs behavior

Each of the keys that are likely to be useful to you are bound to functions that have either a C definition in the Emacs binary or are bound to functions defined in a dialect of Lisp called Emacs Lisp. 99.9999% of the time, you will want to alter the behavior of Emacs either by changing the binding over to some other Emacs Lisp function of your own making, or redefining an existing function. You might need to do one or the other depending upon the circumstances, but redefining existing functions should be a last resort since when you upgrade Emacs, as your redefined function will not get updated with any bug fixes. But, don't let that stop you from customizing the dickens out of your Emacs, as it is through that customization that you gain the power and productivity that other editors lack.

What's productive and what is not

Don't use the Vi Emulation mode. It will just frustrate your efforts to get over the learning curve. Most people drawn to Emacs are software developers or IT people that need to work with a lot of different files in different languages. You may find that navigating files and directories using file browsers such as Windows Explorer (in Microsoft Windows) or Nautilus (in GNOME desktop) can pollute your desktop with so many top-level windows, that you lose the forest for the trees, such that you end up spending a substantial amount of time hunting around for a particular window. In Emacs, you don't have to do that any longer: just use C-x C-b to get a list of buffers you have currently opened, and use your cursor to move to a given buffer, and hit Enter key to view that buffer in Emacs. What is not efficient is having to move your hands off of the main keyboard area to use the arrow keys, the page up keys, or the mouse. This may seem odd to hear this, but when you become more productive at the keyboard, you do not want your software to waste your time by forcing you to move your hands away from the main area, or force you to look down at the keyboard to find where the Home key resides. Did you learn the function keys on the first row of your keyboard in Touch Typing class? No? Why not? Because they aren't always in the same spot on all keyboards (and the same can be said for arrow and page up/down keys). Try not to use them to remain productive. You think I'm joking, right? Wrong. Yes, you can rebind the function keys in Emacs, and I did that for years before I discovered that I could remain even more productive without them. I found, in my case, that I would have to take my eyes off of the screen to find the F9 key, and man does that suck time away from doing real work when you have to do that operation 1500 times a day! And don't even get me started about the mouse (too late!). The mouse can be a major time waster when you are working with text or documents 98% of the time. The only thing a mouse should be used for is in CAD and drawing applications, not for selecting text areas of the screen during text editing and navigation operations. Force yourself to learn to use the Emacs key bindings effectively, and leave the mouse for the still-retarded apps. Still not convinced? Think about how many times you wished you could minimize window with a single keystroke, only to find out that you have to use the mouse, and then accidentally hit the [X] (kill window) icon at the top of the window, only to curse yourself for getting in a hurry. Yeah, that's right, you are in a hurry, which is what the keyboard is for. So, get a grip on that keyboard!

Navigating paren/brace/bracket-intensive languages in Emacs

The descriptions of the bindings below do not really belong in a basic tutorial, but they are so important to editing source code that I have to mention them: C-M-u -- This is useful in buffers that are visiting source code files for languages such as C and C++, Lisp, Perl, etc. that make heavy use of parentheses and curly braces. All it does is move up (think "u" for up) one level of parenthese or curly brace. Other bindings that allow you to navigate around nested levels of brace are C-M-n (next) and C-M-p (previous). I tend not to use the C-M-d (down) binding for some reason. I think there are bindings that do similar things for languages such as Python since there is a separate mode specifically for Python in Emacs.