Overview

This is my GNU Emacs quick reference. If you find any errors or out-of-date info, please let me know!

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.

You can run Emacs either as a windowed (desktop) application or within your terminal window (see instructions below). When you run emacs from your terminal on your desktop, its the windowed app that starts up.

When you run the Emacs app, the window contains (in Emacs terminology):

• the frame. This is the name Emacs uses for the main app window
• windows. Inside the frame, the editing area can be divided into multiple “windows”.
• mode line. Each window has its own informational “mode line” at the bottom of its window.
• mini buffer. This is the bar at the bottom that you’re taken to when you hit, for example, M-x. It shows you what editing commands you’re running in Emacs.

Key sequences in Emacs involving 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 :.

In Emacs, all keys you hit result in commands being executed. The command associated with regular printing characters is self-insert-command and just inserts the character into the active buffer. 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.

A pattern that Emacs tends to follow is that complementary commands have 2 different keys – one to do the command and another to do the opposite. Another pattern is that M-<some_key> often gets you a souped-up version of C-<some_key>. For example, C-f moves the cursor forward one character, and M-f moves you forward one word. (An exception is the somewhat odd C-v to page down and M-v to page up.)

Emacs usually does Tab-completion for you (in the mini-buffer), 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-based distros:

sudo apt-get install emacs

(You may also want to check out emacs-goodies-el.)

Configuration

When you first start up GNU Emacs, you can go to the menu and make some customizations right there. I suggest making sure the following menu items have checkmarks next to them:

• Options → Highlight Active Region
• Options → Highlight Matching Parenthese
• Options → Use Directory Names in Buffer Names

Then do “Options → Set Default Font…” and choose your favorite (Inconsolata is lovely (to install it: apt install fonts-inconsolata)).

Finally, do “Options → Save Options” and Emacs will save any changes to your ~/.emacs file.

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

;; So you can drop .el files into your ~/.emacs.d directory.
(add-to-list 'load-path "~/.emacs.d")

(require 'package)
;; We'll be installing packages from this Emacs package repo.
(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/"))
(package-initialize)

(setq-default inhibit-startup-screen t)

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

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

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

;; Scrolling the window up/down by one line.
;;
;; To scroll the down, you could do `C-u 1 C-v`.
;; And to scroll up: `C-u 1 M-v`.
;;
;; Set keyboard shortcuts for those:
(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. (Where did I find this
;; one? Maybe Yegge's Emacs drunken blog post?)

;; If you want to remove some UI stuff, uncomment:
;(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 in mode-line.
(add-hook 'find-file-hooks
          '(lambda ()
             (setq mode-line-buffer-identification 'buffer-file-truename)))

;; Set the color theme.
(load-theme 'zenburn t)

Using Emacs in the terminal

In your ~/.bashrc, add:

alias ec='emacsclient -nw'

Then, once the main Emacs app has been started, from any terminal you can run ec some-file.txt to edit in your terminal. Exit with “C-x C-c” or “C-x #”.

Copy/Paste

Using the Emacs desktop app, you can copy/paste to and from Emacs.

• To copy/paste from Emacs: select your region, hit M-w to copy, then move to the other gui app and ctrl-v to paste.

• To copy/paste to Emacs: select what you want in the other GUI app, hit ctrl-c to copy, then move to Emacs and hit C-y to paste.

Installing Emacs Packages

To install a package from the Melpa Emacs package archive, visit https://melpa.org/ and find the package you want. (Note, they have some help docs.)

Then, within Emacs, do:

M-x package-refresh-contents RET
M-x package-install RET whatev-package RET

You can also do M-x package-list-packages to see what’s available, and install from that list instead of having to type in the package name yourself. While in that buffer:

• d to mark a package for deletion
• U to mark all installed packages to be upgraded to most recent versions
• x to execute the above selections

M-x package-autoremove to remove any orphaned dependencies.

See https://www.emacswiki.org/emacs/InstallingPackages for more info.

Using Other Modules

Note: you’ll more commonly install modules from melpa.org using the package commands shown above, and the manual setup shown below will not usually be necessary.

To use modules you find while tooling around the internet, you can drop them into your ~/.emacs.d directory 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 automatically loaded each time you start up Emacs, add the following to your ~/.emacs:

(require 'module-name)

To toggle minor modes on and off, activate them again: M-x the-minor-mode.

Some particularly helpful modules and commands

Tramp

Lets you edit remote files:

C-x C-f /ssh:username@host.org:foo.txt

Hex Mode

Use M-x hexl-find-file to open and edit files in hex mode.

For more about hexl-mode, see https://www.emacswiki.org/emacs/HexlMode.

Emacs commands

The major prefix key sequences that 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

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. In the mini-buffer, 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, in some modes, when you hit Enter (“RET”), if you don’t automatically get the cursor indented on the next line, use C-j.

Sometimes there’s more than one key sequence for a given command. In the tables that follow, if more than one key sequence is listed, use the first one — less-often-used equivalents are listed after it, in parentheses.

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

General

Note, sometimes though, the C-u prefix does something special instead. Ex., C-u C-l, or C-u M-|. The other funny prefix I’ve seen is M-0, as in M-0 C-k.

You don’t need to manually reload or refresh a buffer (say, after the file’s been modified by some other program). Just go to that buffer, and the moment you try to change it, Emacs will tell you about the file being modified and ask you what to do.

(For repeating a command, maybe also look into C-x M-: (repeat-complex-command). Haven’t looked into that one yet.)

Cursor navigation

M-m moves the point to the first non-whitespace character on the line.

At first, it can be very tempting to use the arrow keys instead of C-{f|b|p|n}, the HOME and END keys instead of C-a and C-e, the PgUp and PgDn keys instead of C-v and M-v, and the DELETE key instead of C-d. It would seem to be wise to resist this temptation. This is because, once you get fast with the Emacs key sequences, you’re still fast even if you switch to, say, using a laptop where the arrow (and other) keys are smaller or harder to reach. Also you may be using Emacs on a remote machine over ssh, and the arrow/Home/PgUp/PgDn keys might not even work.

By the way, in the GNU Emacs docs, “DelBack” means the Backspace key. I don’t think the docs refer to the keyboard’s Delete key (since you’d just use C-d for that anyway).

Delete, insert, and cut/copy/paste

Note: “kill” (or “wipe out”) means cut. “Yank”, strangely enough, means paste (as in, “yank the text out of the kill ring and into the buffer”).

When going back through the kill ring (M-y), if you go back too far and want to move through the ring in the reverse direction, do: C-u -1 M-y (Ugh!)

Searching

In the mini-buffer, use M-p and M-n to recall previously-searched-for terms.

During an interactive search & replace:

• y – replace and find next
• n – find again
• ! – just go ahead and replace all
• . – replace and stop searching
• ^ – go back to previous match

To continue your search to the next search result, just keep hitting the same command you started the search with (ex. C-s). To end the search, hit RET. Use C-g to abort the whole search and go back to where you started.

See also: M-x re-search-forward, M-x re-search-backward.

Regexen

Regarding regexes, to match {, }, |, (, ), <, or > you just type them as-is. If you want their special meaning, you need to escape them:

• \{ and \} for explicitly specifying number of occurences
• \| for “or”
• \( and \) for grouping
• \< and \> for word boundaries (or just use \b)

Note that Emacs regexen allow the non-greedy matches *?, +?, and ??. Use \w for matching a “word character”.

Your replace term may contain the following special sequences:

• \n – where is a number (starting at 1, ex. \1, not \$1) representing the n’th parenthesized group in the match.
• \& – original text that was found
• \# – number of replacements done so far
• \? – prompts you during the search/replace for what to replace with

Misc programming features

Edit: When using the GUI version of Emacs, you can click (with mouse-button 1) on where it says “(DOS)” or “(MAC)” in the mode line to change the buffer’s line-endings.

a – Regarding tagfiles, Emacs will automatically load ./tags when you first use the M-. command. It may prompt you for the location of the tags file. Emacs can only have one tag file loaded at a time.

b – Regarding syntax highlighting, to switch to, say, XML, do M-x sgml-mode.

c – Regarding converting line-endings from DOS/Windows or Mac to just standard newlines, recall that DOS files have an extra \r in them before the \n, and Mac files have an \r instead of an \n. See http://www.emacswiki.org/cgi-bin/wiki/EndOfLine for more info.

Misc text processing & selecting text

For selecting text (see next table),

• “mark” == where you put a mark,
• “point” == current cursor location, and
• “region” == area between mark and point.

Note: you may see the term “justify” (or reflow, or reformat), which is the same as fill.

C-x C-x is useful for popping back to where you just were after any movement or operation that moves the point and sets the mark to your previous location.

You may make rectangular selections as well. Sort of. Just set your mark and point as usual, and then use C-x r k to cut (“kill”), and C-x r y to paste (“yank”). With transient-mark-mode on, you’ll see a regular (not rectangular) selection between mark and point, but the special commands just given will operate on the rectangular region between mark and point.

To convert existing tabs to spaces for a given region: M-x untabify.

Bookmarks

• To set a bookmark: C-x r m then make up a name for the bookmark.

• To return to it: C-x r b and give the name, or take the default, which is the last bookmark you used.

Multiple buffers

To quickly create a buffer for some scratch writing: C-x b aoeu

Split windows

If you have more than 2 windows, just keep hitting C-x o to cycle through them.

Misc

Regarding picture-mode, for something much simpler, you can just enter insert mode with M-x overwrite-mode, or usually just hit the Insert key.

Note, GNU Emacs has its own built-in file system browser. To use it, use C-x d or M-x dired.

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 Git, 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.

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.

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.”

Links

• http://www.gnu.org/software/emacs/emacs.html – The official GNU Emacs site.
• http://www.gnu.org/software/emacs/tour/index.html
• https://www2.lib.uchicago.edu/keith/tcl-course/emacs-tutorial.html – excellent tutorial. Much of my page here was orginally put together while reading this tutorial.
• https://www.emacswiki.org/emacs/SiteMap
• http://dsl.org/cookbook/cookbook_14.html#SEC190 – The Emacs section of The Linux Cookbook.
• GNU Zile is a tiny Emacs clone written in C.

About this Document

Written in Pandoc’s Markdown, and then processed by Pandoc.