Overview

This is my GNU Emacs quick reference. GNU Emacs may be the most capable text editor on this planet. Also, after many years of development, it's editing environment is very finely tuned for high productivity. It comes with world-class documentation, and as an added bonus, it shares many of the same key combinations with Bash. If you're looking for a tutorial to help you get started right from the very beginning, see the links section at the bottom of this page.

Key combos in Emacs using letters (like C-a) use only lowercase -- that is, they don't use the Shift key on letters to get a different command. The Shift key is only for reaching non-alphabetic characters like % and :.

Also, recall that with Emacs, all keys you hit are commands. The command associated with printing characters is self-insert-command and just prints the character on the screen. Some commands are C-some_key, some M-some_key, and some are prefix commands (ex. C-c, C-x, and C-h). You hit them, then hit another key after them to get effect of the command.

Emacs usually does Tab-completion for you, which is quite handy when typing the full name of a command (say, after hitting M-x), or when navigating around your directories to open files.

Installation

On Debian, install with aptitude install emacs. You probably also want to grab emacs-goodies-el, which contains all sorts of useful stuff (like boxquote and table).

To get a more recent version, and one that uses GTK+, you can instead do:

aptitude install emacs-snapshot-gtk emacs-goodies-el

As of Feb 2008, if you want emacs to use antialiased fonts, follow the Pretty Emacs instructions.

Configuration

As an alternative to adding the following to your ~/.emacs file, you may use GNU Emacs's built-in customize facility (see "Setting variables" below).

I like to add the following to my ~/.emacs file:

;; So you can drop .el files into your ~/elisp directory.
(setq load-path (cons "~/elisp/" load-path))

;; You may or may not want this one -- it stops Emacs from
;; leaving foo~ files all over the place.
(setq-default make-backup-files nil)

;; See below if your version of Emacs doesn't yet support
;; antialiased fonts.
(set-default-font "DejaVu Sans Mono-8")

;; Use only spaces (no tabs at all).
(setq-default indent-tabs-mode nil)

;; Visually highlight regions when you select them.
;;(setq-default transient-mark-mode t) <--- handled by customize

;; Enable syntax highlighting. XXX
;;(setq-default global-font-lock-mode t) <--- handled elsewhere

;; To stop the window from popping down a half screen when you get to the bottom.
;(setq-default scroll-conservatively 9999)

;; Show column numbers.
(setq-default column-number-mode t)

;; Make a nice quote box around some text.
;(require 'boxquote) <--- Maybe req'd if installed manually.

;; Scrolling the window up/down by one line.
;;
;; To scroll the down, you can do ``C-u 1 C-v``. Then, to repeat it, first
;; ``C-x z``, and then just tap the ``z`` key to do it some more. Same goes for
;; scroll up (``C-u 1 M-v``).
;;
;; To set up keys to map to ``C-u 1 C-v`` and ``C-u 1 M-v``, let's use:
(global-set-key "\M-n" '"\C-u1\C-v")
(global-set-key "\M-p" '"\C-u1\M-v")

;; Note, you can also use ``C-u C-v`` and ``C-u M-v`` to scroll by 4 lines.
;; See also: scroll-preserve-screen-position

;; This one's so handy it should have its own alias:
(defalias 'qrr 'query-replace-regexp)
;; Then just use ``M-x qrr`` when you want it.

;; Useful for when you have to repeat a macro many times.
;; Though, as of Emacs 22, just use ``C-x e e e ...`` for this.
;(global-set-key [f5] 'call-last-kbd-macro)

;; If you want to remove the X11 UI stuff.
;(if (fboundp 'scroll-bar-mode) (scroll-bar-mode -1))
(if (fboundp 'tool-bar-mode) (tool-bar-mode -1))
;(if (fboundp 'menu-bar-mode) (menu-bar-mode -1))

;; Display full pathname if appropriate.
(add-hook 'find-file-hooks
          '(lambda ()
             (setq mode-line-buffer-identification 'buffer-file-truename)))

;; Set the color scheme.
(require 'color-theme)
;(color-theme-initialize) ;; Might be req'd if you manually install.
(color-theme-bharadwaj)

;; Use cperl-mode instead of the default perl-mode.
(defalias 'perl-mode 'cperl-mode)

;; From Damian's PBP. --------------
(custom-set-variables
 '(cperl-close-paren-offset -4)
 '(cperl-continued-statment-offset 4)
 '(cperl-indent-level 4)
 '(cperl-indent-parens-as-block t)
 '(cperl-tab-always-indent t))
;; ---------------------------------

;; To eliminate that trailing space indicator.
(setq cperl-invalid-face nil)

;; See if you like this:
(setq cperl-hairy t)

;; And maybe even this, just to try it out:
;(setq cperl-auto-newline t)

(require 'pod-mode)

(set-default-font "DejaVu Sans Mono-8")

(set-default-font "-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1")

emacs.font:6x13

emacs.font: -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1

General usage tips

You can use the Edit cut/copy/paste menu items for copying and pasting between Emacs and other desktop apps. Actually, C-y will paste into your buffer just fine -- it's copy that you need so you can paste into your other desktop apps (since M-w only works inside of Emacs).

Using modules

To use modules (aka "libraries", aka "modes") you find around town, just drop them into your ~/elisp directory, restart emacs, and load the module using M-x load-library RET module_name, where module_name is the name of the .el file without the .el.

If you want the module loaded each time you start up Emacs, add the following to your ~/.emacs:

(require 'module_name)

Command line options

Emacs commands

The major control key prefixes you'll see are:

• C-x -- this often has to do with managing files, windows, and buffers
• C-c -- mostly used with commands specific to a major mode
• C-h -- getting into the help system
• C-u -- usually either changes the subsequent command in some way, or else used with a number C-u <n> for the next command to execute n times. With no n, C-u just means do it 4 times. C-u C-u means 16, and so on.
• M-x -- running a command (mode) by name. M-x is followed by a long name. Use M-p and M-n to scroll through previously-run commands.

The C-<digit>, M-<digit>, and C-M-<digit> prefixes are all shortcuts for C-u <digit>.

Note, when you hit ENTER ("RET"), you don't automatically get the cursor indented on the next line. For that, use C-j.

Sometimes there's more than 1 key combination for a given command. In the tables that follow, if more than one key command is listed, use the first one -- lesser-used ones equivalents are listed after it, in parentheses.

If a given command takes an argument, you'll be prompted for it in the minibuffer. Hitting RET terminates the argument.

Setting variables

You can set a variable in a number of ways. Say you want to set indent-tabs mode to nil:

1. In your .emacs file, put (setq-default indent-tabs-mode nil)
2. For the current buffer you're editing: M-x set-variable RET indent-tabs-mode RET nil RET or M-: (setq indent-tabs-mode nil)
3. Using the Emacs "in-situ GUI": M-x customize, then navigate to indent-tabs-mode, or else just go straight to it: M-x customize-variable RET indent-tabs-mode RET

When folks talk about "customizing" a variable, they're usually talking about using that built-in point-and-click interface. Clicking "save for future sessions" means write it to your ~/.emacs file.

Note that setq works only for the current buffer. setq-default sets a given variable for all buffers.

Backups and auto-save

There's three ways Emacs helps you recover a file when you need to:

1. auto-save -- Emacs does an auto-save every 300 keystrokes. If you befoul your buffer and need it back the way it was the last time Emacs did an auto-save, use M-x revert-buffer.
2. Emacs can also give you back your file the way it was the last time you saved it. Again, it's M-x revert-buffer (you'll be prompted if there's also a recent auto-save available).
3. The backup~ file. Unless told otherwise, Emacs will automatically make a backup of every file you open, when you open it, naming it with the ~ suffix. If you really foul things up, you can go back to this version manually: mv yourfile~ yourfile.

Of course, you should usually be using version control software (like Bazaar, for example) for more coarse-grained file recovery.

More help on help

You need to learn to use the help system to effectively use Emacs. Here's my executive summary on using built-in help. First, the two biggies:

C-h k

describe-key. Prompts for a keystroke, then shows you the docs for the command to which that keystroke is bound.

C-h f

Then give the name of a function to get help on it.

Also:

C-h b

describe-bindings. Shows you all the current key bindings.

C-h c

describe-key-briefly. Prompts for a keystroke, then tells you what command that keystroke is bound to.

C-h v

Then give the name of a variable to get help on it.

C-h m

describe-mode. Tells you about the current major mode you're "in". You're gonna love this one. :) (Same as M-x describe-mode)

C-h a

apropos-command. Prompts you for a keyword, then opens a 2nd window showing all commands with that word in it.

C-h p

finder-by-keyword. For browsing Emacs packages on this system.

C-h t

Takes you to the built-in Emacs tutorial.

C-h i

info. Takes you to the built-in info (just like typing info on the command line).

C-h C-h

Gives you a list of all the things you can type after C-h.

To get help with what keys may follow a given prefix, type the prefix followed by C-h. This is how C-h C-h works. :)

To get any specially-marked "commentary" text from a library, use the finder-commentary command. For example: M-x finder-commentary RET htmlize RET.

I've put together some notes on using the info tool.

To see a listing of the last gaggle of Emacs commands you previously typed, use M-x view-lossage.

Keyboard macros

To record a keyboard macro, follow these steps:

1. Start recording the macro: C-x (
2. Execute some editing commands.
3. End recording of the macro: C-x )

To execute the keyboard macro, hit C-x e (which runs the last one you recorded). Keep hitting e to get the macro to run successively. To tell it to just run over and over until it fails, use M-0 C-x e.

Random background notes

Note that,

• the "meta" (M) key on most keyboards is the Alt key (ALT)
• the return key (RET) is equivalent to C-m (C-j is newline-and-indent)
• the escape key (ESC) is equivalent to C-[
• M-some_key (ALT-some_key) is equivalent to ESC some_key (and so, C-M-some_key == ESC C-some_key). You may need to know and use this if you're telnetted|ssh'd to another machine and ALT doesn't work for some weird reason.
• You can run any command using its full name like so: M-x long-command-name

GNU Emacs accepts as input 8-bit ascii. The symbols on your keyboard only really cover 7-bit ascii. Using the ALT modifier actually sets that higher bit for you, getting you those last upper 128 ascii characters.

Some good tips

Some tips condensed down from Stevey's Effective Emacs:

• For navigating any more than 5 lines or so, use C-s and C-r.
• For a quick temp scratch buffer: C-x b aoeu

Also,

• For editing typical unixy conf files, try M-x shell-script-mode.

Features I may not need after all

Q. Does Emacs have H, M, and L like Vim? Otherwise I've got to hop paragraph-by-paragraph.

A. M-r is like Vim's M, but it turns out it's even better to just use C-s & C-r (and M-{ & M-}) to zip around.

I suppose if you really wanted to, you could try using [C-u *n*] {M-a|M-e}, and [C-u *n*] {C-v|M-v}.

Q. Can I make RET actually do what C-j does?

A. You might consider just getting used to using C-j -- it's actually not so bad to have both RET and C-j. Also, it's probably the mode's responsibility for remapping C-j to RET, if that's what you want. If you really want RET to always do a newline-and-indent, add this to your ~/.emacs:

(global-set-key "\r" 'newline-and-indent)

or, for just, say, Python, the following should work: (add-hook 'python-mode-hook (lambda () (local-set-key (kbd "RET") 'newline-and-indent))).

Still need to figure out how to do these

• Editing files remotely over ssh. Using dired over ssh. How do I gracefully exit the connection?

  See Tramp (where you'll use stuff like C-x C-f /myname@remotehost:/remote/path/to/file.rst). Read about it: info tramp.

• Unloading a minor mode?

  You usually just run the command again to toggle it.

Learning Lisp

If you really want to master Emacs, you might consider learning Emacs Lisp (aka "elisp").

The manual is Programming in Emacs Lisp. Links to that and also the Emacs Lisp Reference Manual are listed on the Emacs website.

Before either of those though, you might want to read the tips near the end of shiny and new emacs 22. Quoting that article:

• "It's kinda like XML."
• "Writing elisp code is very much like scripting your actions in the editor." ... "It's like you've got a little worker-bee version of yourself, doing automatically what you could have done by hand (albeit much more slowly) using editor commands."

Of course, if you're interested in Lisp, you might also have a look at Common Lisp and Scheme. The book you want to read is "Structure and Interpretation of Computer Programs" by Abelson and Sussman.

links

• http://www.gnu.org/software/emacs/emacs.html -- The official GNU Emacs site.
• http://www.gnu.org/software/emacs/tour/
• http://www.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html -- excellent tutorial. Most of my page here was orginally put together while reading this tutorial.
• http://www.emacswiki.org/cgi-bin/wiki/SiteMap
• http://dsl.org/cookbook/cookbook_14.html#SEC190 -- The Emacs section of The Linux Cookbook.
• http://www.io.com/~jimm/emacs_tips.html -- Jim Menard's emacs tips (among other tidbits, a good note on using bookmarks).
• http://marc.abramowitz.info/archives/2006/04/10/emacs-22-reference-card/
• Zile is a tiny Emacs clone written in C.