Use GNU Emacs
The Plain Text Computing Environment

A book that tries to cover most of the enormous computing system that is GNU Emacs seems to inevitably end up about as big as Emacs itself. While I’ve tried to arrange the book to be readable straight through from beginning to end, I doubt many will be inclined to do so. So I’ve also tried to make it possible to skip directly to any topic of interest by heavily hyperlinking back to any prerequisite topics¹. For example, if you skip to the chapter on running your shell in Emacs, you’ll find the necessary links to fundamental topics you’ve skipped over (say, renaming Buffers, directory editing, or Incremental Search).

GNU Emacs has been around for 38 years, and because it debuted many concepts now taken for granted, it also has its own way of doing them, and even its own language for talking about them. So I would for sure read The Fundamental Emacs Concepts; Files, Buffers and Windows in Brief; Selecting Text; and Cutting, Copying, and Pasting; and at least glance at The Keyboard and Key Bindings.

The single most important thing is, while you’re reading, have Emacs up and running so you can try things out as you read about them. And be sure to try the built-in interactive learn-by-doing Emacs tutorial; right now is not too soon to start it.

My recommendation is to learn the basics of Emacs with as few customizations as possible. However, I do provide a minimal recommended initial Init File (configuration file) that you can download and install to improve your experience. It wouldn’t hurt to put this off for the first few chapters, but if you feel like bailing on Emacs before then, see if adding the book’s Init File changes your mind.

A number of Emacs technical terms are also common words. To minimize confusion, when I use the technical terms, I capitalize them. So if I say, “Killing the Frame or Window in no way kills the associated Buffer”, I’m talking about three Emacs data structures. But if I say, “In this frame of reference, a window of opportunity exists to buffer your data”, well, I don’t know what I’d be talking about, but it has nothing to do with the Emacs data structures.

Note that in the many tables where I summarize the Emacs keystrokes for a set of commands, I don’t follow this rule; instead, I try to capitalize words that might suggest a helpful mnemonic, as in this excerpt:

One of the most basic facts about Emacs is that every key you type potentially executes some Command. When I introduce a new keystroke I use this format: C-e (‍move-end-of-line‍), which means that the keystroke C-e invokes the Command named ‍move-end-of-line‍. See The Keyboard and Key Bindings for complete details.

I frequently mention various Unix commands and programs (often because Emacs provides an interface to them). I use the Unix Manual’s traditional notation for these in a fixed-pitch font, appending a parenthesized section number to the command name. Examples are ls(1), grep(1), sudo(8), etc.

This book describes GNU Emacs version 28.2, which is the latest official release as of 12 June 2023; many operating systems or their package managers will come with an older (possibly much older) version by default. While Emacs has excellent backward compatibility, meaning everything you learn about it will probably still work for literally decades, it also introduces new features and new ways of doing old things all the time. If you’re running an older Emacs than I am, you may occasionally find that a command or key binding that I mention doesn’t exist, or acts somewhat differently; but mostly, everything will work.

There also have been and still are other versions of “Emacs” besides GNU Emacs, which can lead to differences as well. The most notable these days is probably Aquamacs, a version specially for Mac OS X, which besides its Mac-specific changes is (at this writing) based on GNU Emacs version 25.3 from 2017—that’s three major revisions behind. You might ultimately prefer Aquamacs or another Emacs, but this book will be most useful to you if you start out with GNU Emacs; see Installing Emacs.

Additionally, some of my discussion will have a Unix focus, since that’s what I use every day. Emacs works beautifully on mostly-Unix operating systems (like Mac OS X and ChromeOS) and on completely non-Unix OS’s, like Microsoft Windows, but some of my examples will assume you’re running a true Unix, like GNU/Linux or one of the BSDs. But really, Emacs makes all operating systems virtually indistinguishable.

My emphasis in the book is on built-in features that ship with Emacs. I occasionally mention or recommend various third-party Packages (add-ons written and provided by people like you!) but I don’t go into much detail and there’s no way I can keep up with the huge third-party ecosystem.

In fact, some of the most important built-in Emacs subsystems are so big that I can only give at best a glancing overview: most notable are the calculator; Gnus (for email); Org Mode (for… well… practically everything); and Emacs Lisp programming. The good news is that each of these has its own built-in book-length document (Emacs Lisp has two!).

Don’t fear or neglect the extensive built-in Emacs Manual; you can start out reading it on the web but as you become familiar with Emacs I think you’ll prefer reading it natively.

The more time I spent writing this book, the more I had to double-check things that I felt certain I fully understood decades ago: things that, after all, I use every day! The result was two-fold:

1. I discovered that there’s a ton of new stuff I had no idea about—being an Emacs user means a lifetime of learning ahead of you (and what’s better than that?).
2. I also discovered that the manual is really one of the best software user manuals ever written.

So, RTFM: Read The Fine Manual.

I’m afraid this book is of two (or more) minds about its intended audience. When I wrote the first version in 1997, the audience was librarians who were using Unix systems for the first time. When I decided to expand the book during the pandemic, I didn’t want to change the audience to solely tech-savvy programmers, but I did want to include a lot of advanced stuff for tech types. The result is that those programmers will find lots of basics to skim over, and the non-programmers will find a certain amount of tech nerd stuff to skip.²

There are many fun and inspiring blog posts and videos of non-programming Emacs users—writers of fiction, managers of programmers, people who found a new way to manage their note-taking—and my fantasy is to find (or create!) some more, while perhaps convincing the programmers that Emacs is much more than just another IDE.

Emacs has it’s own extensive jargon of technical terms; here are some of the ones that might otherwise be puzzling.

I’ve also made up a few coinages of my own for the purposes of this book (labeled “KW” so you don’t embarrass yourself by using them).

alias

an additional, equivalent name of a function or Command

binding

the pairing of an event with a Command

buffer

the places where text is entered, edited, or displayed

button

a clickable region of text in a Buffer that invokes a Command

click

to activate a Button or a link in a menu or in a Buffer, with the mouse or by hitting Return when positioned there

Command

a function intended to be used interactively by the user, rather than used only by an Emacs Lisp programmer

current line

the line in a Buffer where Point (the cursor) is

cut

the modern term for what Emacs calls Kill

delete

to remove text from a Buffer with no way to get it back (compare Kill)

directory

a structure on disk that holds files and other (sub-) directories; what non-Unix users call a folder

EIPNIF

Everything Is Possible, Nothing Is Forbidden (KW); you can change any aspect of Emacs’s behavior, even if it’s a really bad idea

elisp

Emacs Lisp, the dialect of the Lisp programming language that implements Emacs

event

an action that represents input to Emacs, mainly keystrokes, or mouse-clicks or -drags

Frame

an OS-managed window; modern term: window

glob

to expand wildcard characters, typically in a wildcarded filename, or the special wildcard characters themselves (commonly * and ?)

grep

to search (after the Unix searching utility grep(1))

init file

your Emacs initialization file: what non-Emacs users call a config file

key binding

the binding of a keystroke to a Command

Kill

to remove text from a Buffer, saving it on the Kill Ring where it can be easily retrieved later; modern equivalent: cut

operating system

the software that runs all the other software on your computer (including your phones and tablets) and interfaces with your hardware, probably one of Android, Linux, Mac OS X, or Microsoft Windows (Emacs runs on all of these)

OS

operating system

paste

the modern term for what Emacs calls Yank

Point

the location in a Buffer where text would be inserted when you type

regexp

a regular expression

Region

contiguous text you’re about to Kill, copy, or operate upon; modern term: selection

regular expression

a powerful kind of wildcard, pervasively used in Unix and in Emacs for searching

RET

means to hit the Return or Enter key

selection

the modern term for what Emacs calls the Region

session

the period of time from when you start Emacs to when you exit it; may literally span months

subsystem

a collection of Commands and Modes that together facilitate a coherent activity (KW)

Unix

the operating system on which GNU Emacs was developed; comes in many flavors, of which Linux is perhaps the best known

Visit

to load a file into Emacs for editing

Window

a division of a Frame; modern term: pane

Yank

to insert previously Killed or copied text; modern term: paste

The Emacs manual also has a glossary, and the Emacs Wiki has both a glossary page and a jargon page.

GNU Emacs is a free, portable, extensible, internationalized, self-documenting text editor. That it is free means specifically that the source code is freely copyable and redistributable, so Emacs can never be discontinued and disappear. That it is portable means that it runs on many computers under many different operating systems, so that you can probably count on being able to use the same program no matter what computer you’re using. That it is extensible means that you can not only customize all aspects of its usage (from keystrokes through fonts, colors, mousage and menus), but that you, and the community, can modify and program Emacs, even while Emacs is running, to do entirely new things that its designers never thought of. That it is internationalized means that it has full Unicode³ support, including bidirectional text and many input methods for non-Latin scripts. That it is self-documenting means that every keystroke, menu item, and function can thoroughly explain itself and its usage, and that Emacs contains 395,759 lines of hypertext reference manuals and tutorial documentation about itself and its subsystems.

Because of all this, GNU Emacs is an extremely successful program (having been in continuous development for 38 years⁴), and does more for you than any other editor. It’s particularly good for programmers. No matter what programming language you use, Emacs probably provides a mode that makes it especially easy to edit code in that language, providing syntax highlighting, context sensitive indentation, and layout. It also allows you to compile your programs inside Emacs, with links from error messages to source code; debug your programs inside Emacs, with links to the source; interact directly with the language interpreter (REPL); jump across multiple files to the definition of a symbol in your source code; and interact with your version control system⁵.

Emacs also provides many built-in applications such as:

• mail readers (at least half a dozen)
• web browsers (at least two)
• a powerful file manager like Windows Explorer (File Explorer) or Apple’s macOS Finder
• interactive shells, logins (ssh, ftp, sudo), and terminal emulators
• a powerful and easy to use macro system to automate your tasks
• diffing and merging of files
• calendars, project planning, TODO lists, scheduling, and agendas
• a powerful infinite precision programmable calculator with symbolic algebra and data graphics
• image, PDF, DVI, ebook (EPUB), OpenDocument, Microsoft Office, and PostScript viewers, and inline images in plain text
• typesetting and publication of text or source code to HTML, PDF, and presentation slideshows (this document is an example)
• literate programming
• interactive notebooks: that is, documents that contain live code, data, equations, visualizations, and text
• client / server mode (connect to a running local Emacs from any terminal, or to a remote Emacs running on a different computer)
• multilingual spell checking, dictionaries, and thesauri (available in all of the above applications and subsystems, too)
• transparent editing of encrypted and compressed files, and of files inside containers (like tar and zip archives)
• remote file editing (any file or directory you want to edit can be transparently accessed via ssh, ftp and the like)
• spreadsheets (three)
• music players (at least half a dozen)
• chat / messaging systems (like IRC, Jabber, Slack)
• a window manager for X windows
• native Emacs games and interfaces to external games
• a Rogerian therapist (in case this is all a little overwhelming)

In addition, Emacs’s extensibility has resulted in a vibrant ecosystem; users share packages that provide new functionality, and it’s easy to browse a few thousand of these via the built-in package manager, and install the ones of interest. Many more Emacs packages are available on GitHub and in the Emacs Wiki.

The image above shows Emacs “in use”. It’s a little unrealistic in that I, at least, never want that many windows open simultaneously, but it’s a real screen shot. Going across the columns from left to right, we have email (a folder and a message) and an agenda from my project planner; OCaml source code with a compilation error message and a type-throwback window; a Google search in one of Emacs’s web browsers above a PDF; and finally, a directory in the file manager, a shell, and a paused game of Tetris.

At the very bottom of the screen, I’m in the middle of typing an Emacs command by its name (M-x list), and have hit TAB to get completion — the completions window has temporarily popped up and spans the width of the screen.

In the grey mode line along the bottom of the completions window (and replicated, albeit truncated, in slightly different form at the bottom of every other window) you can see that I have incoming email that I haven’t yet seen (red envelope icon) and an unseen chat message from someone named “Tex”.

First and foremost, Emacs is not a WYSIWYG word processor. This is because Emacs leverages plain text to get maximum flexibility and avoid lock-in to opaque file formats. But Emacs is also used to edit and typeset documents by people who use document preparation systems and markup languages like LaTeX, Markdown, and Emacs’s own Org markup language⁶.

Actually, this is about the only thing I can think of that GNU Emacs is not.

If you are running Unix, Emacs may already be installed. If not, it will certainly be easily installed via your package manager.

When I last used Mac OS X, Emacs came preinstalled, but was very out of date. You could install an up-to-date version via one of the Mac’s many third-party package managers (such as Homebrew), but I recommend David Caldwell’s Emacs For Mac OS X⁸; it’s always up-to-date, and, as Caldwell says, is “Pure Emacs! No Extras! No nonsense!”. I would discourage you from using Aquamacs, which attempts to make a more Mac-like Emacs but ends up rendering it painful to use (IMHO).

If you are running Microsoft Windows, I recommend the Free Software Foundation (FSF)’s Windows build, available from the download page⁹; note that on Windows, instead of running the emacs executable, you want to run the runemacs script instead; a Windows user will probably be most comfortable dragging it the task bar. You can also install Emacs in the Windows Subsystem for Linux (WSL); just follow the instructions above for whatever version of Linux you chose. See the Appendix for how to install Emacs on a Chromebook; you can even install Emacs on your Android phone.

For the cheapest possible complete Emacs computing environment, you can run Emacs on a $100 Raspberry Pi that comes with a keyboard, mouse, and cable to connect to your TV.

And, since Emacs is free software, you can of course download and compile your own copy from source.

Emacs can run in two different modes: a graphical version, which requires a window system like X11 (or the Mac or Windows native interface), and a “text-only” terminal version, like old-school Unix programs such as vi or vim. I say you should run the graphical version; in the terminal version (forced via the -nw (“no windows”) option if a window system is running), you won’t be able to display images or combine multiple fonts, and many useful key combinations will be impossible to type, requiring clunkier alternatives¹⁰. Mouse-button and -motion combinations will be severely limited.

Note that using the graphical version doesn’t imply working in a GUI style with heavy mouse action; I never use the mouse, and configure my Emacs so that the graphical version looks like Emacs in a terminal (right down to my beloved fixed-pitch font). However, because I’m running the graphical version, I get better font and character set support, can view images and PDFs, and make use of all the exotic keys on my keyboard. If what you like about an editor such as vim is the way its invocation is tightly bound to your shell and working directory, or its fast startup speed, running the graphical Emacs in client / server mode achieves exactly the same thing.

Unless you go out of your way to change this (e.g. with -nw), the graphical version is what you’ll get if you invoke Emacs from an X11, Mac, or Windows desktop launcher, or from a shell in a terminal under one of those desktops. This book everywhere assumes you’re running the graphical version.

To enter Emacs, you just say:

emacs

on the command line, or invoke it from your desktop via a launcher, menu, or icon¹¹. When it comes up, you won’t be editing any file. You can then use the file commands to read in files for editing. Alternatively, you can fire up Emacs with an initial file (or files) by saying:

emacs foo.py

Note that for many Emacs users, starting Emacs is something that’s done very rarely: I only do it when I’ve needed to reboot my computer. You don’t use Emacs the way you use vim, starting it in a shell to edit one file, then exiting to compile, then lather rinse repeat. Loading and unloading files, compiling, debugging, file management, version control, and everything else is done inside Emacs with special commands that provide very tight and seamless integration.

If you really prefer to work in a many-sessions, multi-terminal style after trying the native Emacs approach, the way to do it is via client / server mode: start up an Emacs server, and then repeatedly run emacsclient in your terminals as you navigate around, just the way you’d run vim.

You can exit Emacs from the menu via File / Quit, or type the two keys Control+x followed by Control+c (which we write as C-x C-c). If you’ve made any changes to a file, you’ll be asked if you want to save them.

Emacs has a reputation of being difficult to use, but in fact anybody can readily use Emacs out of the box with no instruction¹³ by using the menu bar and toolbar. Simply choose File / Open File from the menu; for common programming languages, you’ll see syntax highlighting automatically. Navigate conventionally with the scrollbar, mouse, and the Page Up, Page Down, and arrow keys. To insert text, just start typing (Emacs isn’t modal like vim (not by default, anyway¹⁴)); delete text with Delete or Backspace. Finally, choose File / Save and then File / Quit from the menu.

This ought to sound extremely familiar.

And pretty boring. You may not be impressed, but you’ll be able to get a lot of work done right away.

But if you want to use Emacs efficiently and give it a chance to change your life, you need to learn to control it the way it was originally designed: via the keyboard.

The enormous Emacs keyboard command set is indeed daunting. Fortunately, you can learn the keystrokes incrementally, using the menus for things you don’t yet know how to do. Eventually, you may stop using the menus entirely; I turned off the menu bar, tool bar and even the scroll bars years ago to save screen real estate and haven’t missed them.

Don’t. Yet. Emacs is all about customizing and making it act the way you want, but in my opinion, you should learn the basics in a stock, mostly uncustomized Emacs, so that if you have questions or problems and look up an answer, that answer will apply to you.

In recent years, there’s been something of a cottage industry in Emacs “starter kits” (such as Prelude, Doom Emacs, Emacs Starter Kit, Spacemacs, etc¹⁵): distributions that give you a heavily pre-customized, sexy-looking Emacs to fix what are perceived to be “old-fashioned defaults” and load and start up everything you could conceivably want. I would avoid these at first for the same reason¹⁶. In fact, some of these starter kits change so much about the experience that large parts of this book will appear to be completely inapplicable to you, so bear that in mind.

I hope browsing this book will convince you that there’s great stuff to come, and that therefore you’ll be able to resist immediately adding a million bits of other people’s configuration tweaks and third-party packages for just a little while, until you get up to speed with the basics.

However, there are a few places where I do recommend some customizations that I think make a significant improvement to the Emacs experience, even while you’re learning. These will pop up from time to time, and are all collected together in an appendix.

My own Emacs is so heavily customized from decades of use that I can barely function in a stock Emacs! I’m all in favor of customizing¹⁷, but don’t jump in too early.

In a recent thread on the help-gnu-emacs mailing list¹⁸, the question came up as to what was the size, in lines of code (LOC), of the typical long-time Emacs user’s Init File. There were about a dozen answers. The figure shows the result of this impromptu and unscientific poll¹⁹; there’s quite a range from the smallest (this book’s Init File) to the largest; the median size is 2,500 lines.

If you want to dive in immediately and start using Emacs as it ought to be used, now is a good time to run the built-in learn-by-doing Emacs tutorial. This is a simply a special text file that explains some basic Emacs commands and has you try them out, explaining how to get back to where you were and continue. It’s very effective and you don’t have to finish it all at once — it’ll remember where you left off for next time.

If you fire up Emacs without a filename and are looking at the splash screen, you’ll notice that your cursor is sitting right on a “clickable” button labeled “Emacs Tutorial” — just hit return or click the label with the mouse and the tutorial will start up.

If you aren’t looking at the splash screen, you can start (or continue) the tutorial at any time by typing C-h t (that’s Control+h followed by the letter t). If you type instead C-u C-h t Emacs will ask what national language to use for the tutorial; it’s available in twenty languages: Brazilian, Portuguese, Chinese, Czech, Dutch, English, Esperanto, French, German, Hebrew, Italian, Japanese, Korean, Polish, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish and Thai. The default is to use the language of your computing environment, if available.

Everything you do in Emacs involves the invocation of functions²⁰ and these functions take arguments and have help and documentation.

Most of the time you invoke these functions with simple keystrokes — even just typing a single letter into a file invokes a specific function, as do all the editing operations (like deleting a word), and all things like opening files or setting a reminder or sending an email. Most of these functions are associated with keystrokes in a malleable, context-sensitive hierarchical organization with an (at least aspirational) mnemonic scheme.

Emacs also contains variables exactly like those of any programming language, which store a huge variety of data. Most of them are used only by programmers, but a subset of them are Customizable Variables (a.k.a. User Options), which you’ll use to configure Emacs to your liking. These variables aren’t something that you just set up once in a configuration file: you’ll soon be comfortable setting and inspecting them on the fly as you’re using Emacs.

No one wants to memorize all the thousands of Emacs key bindings²¹, including those they might use only weekly or monthly. Less frequently used functions are invoked by name with a powerful and extensible completion system, unknown functions are discovered with the Apropos facility, the Help system tells you how to use them, and the Info hypertext documentation system provides even more complete discursive documentation (and there’s a clickable link from the help for any function to its source code, if you really want to know what’s going on).

The text of any file you’re editing is stored in a Buffer. But so is almost everything else: documentation, error messages, and the user interfaces (UIs) to the many Emacs subsystems (file managers, email, REPLs, etc). This means that to a great extent you can manipulate a UI using the same commands you use to manipulate the text you’re editing, which is very powerful and means you have less to learn.

The power of the Buffer is due to the fact that Emacs prioritizes plain text. Almost everything you see in Emacs is plain text. This doesn’t mean everything looks plain; the typical Emacs Buffer is colorized, uses a variety of fonts and possibly character sets, and may include “clickable”²² buttons, read-only sections, dynamically updating data, icons and full-size images, and more: but the Buffer still consists of plain text and the enhancements are applied on top of it.

Windows are the viewports into your Buffers. You can have an arbitrary number of open windows at any time, divided up horizontally and vertically, and Emacs acts like a tiling window manager to manage them for you.

Emacs has a very wide variety of search commands which do more than simply find the next occurrence of “foo” in your file. You can search within a Buffer, across multiple Buffers, across files that aren’t loaded into Emacs yet, and across the web. You can search back in time by searching version control history. You can search more than just files: since Emacs subsystems (like calendars, shells, and email) run in Buffers, you can search their user interfaces and outputs. You can search all the Emacs documentation, and you can search for things by their names as well as by what they contain. Searches can take you directly to a match or pop up a Buffer of all the matches (rather like a page of Google search results), from which you can jump to the actual locations. All these searches come in a flexible variety of modes (fixed text, lax spacing, case- and diacritic-folding, word search, regular expression, and more), and since you’re doing all this searching in Emacs rather than in a dozen distinct programs, they share the same options and syntax.

While common now, unlimited Undo with redo probably debuted in Emacs in the early 1980s. You can undo all changes (even back through file saves) and redo them (undo the undo) all the way forward again, in any combination (you can undo the redo of the undo of the undo). Undo is smart in that it groups togther tiny changes (e.g. consecutive single-character insertions) to make undoing less tedious, and commands that make big structured changes (like search-and-replace) arrange for undo to happen in sensible units. There’s an alternative Undo that works in a tree-structured manner. Most powerful is that you can mark off a specific subregion of the Buffer, and then undo only the changes made within that region (even if you’ve since made other changes elsewhere).

Every Buffer has a Major Mode that’s specialized for some particular sort of text. The specializations typically affect the visual display of the text, tweak general-purpose commands to better suit the text, and provide key bindings for new commands written specifically to work with that kind of text. The classic case is a Major Mode for editing the source code of a given programming language — for example, the mode specializations of python-mode turn Emacs into a Python IDE.

In addition to Major Modes, we also have Minor Modes. A Major Mode implements sweeping specializations — you wouldn’t want to edit HTML in python-mode — but Minor Modes are like mix-ins: each Minor Mode implements some sort of tweak to behavior or appearance that’s usually suitable to add to any number of Major Modes. While any Buffer has exactly one Major Mode, you might turn on a few dozen Minor Modes as well. Minor Modes can implement additional varieties of navigation, formatting, indentation, highlighting, templating, diagramming, spellcheck, footnotes, tables, outlining, text folding, hypertext linking, and much more.

My Emacs at the moment has 650 major and minor modes ready to be enabled.

One of the hallmarks of Emacs is that virtually every aspect of it can be customized. Not only can you customize fonts, colors, and keystrokes but you can customize them all differently in different parts of Emacs (one font set for Python, another for Haskell). Conversely, if you use Emacs for your email and someone mails you a snippet of Python, you see it, in the email, colorized according to your preferences. Emacs customization is sometimes thought of as unfathomable unless you’re a Lisp programmer, but for decades Emacs has had an interactive forms-based customization system (called Customize) that lets anybody easily tweak anything.

But if you are willing to learn a little Lisp (or a lot), you can also customize Emacs in the programming language that it’s implemented in, Emacs Lisp (a.k.a. Elisp); having used Emacs since before the Customize system existed, I still do all my customizations this way.²³ But with Elisp you can go well beyond mere customization: you can add completely new features to Emacs that never existed. This could range from three lines of code to add an idiosyncratic way of scrolling text (I’ve defined a keystroke to scroll by paragraphs) to building large software systems that would, in a non-Emacs universe, be standalone applications. The popular Magit front-end to the Git version control system comprises 30,000 lines of Elisp code. Gnus, one of several Emacs mail readers, comprises 117,485 lines! Emacs itself is about 79% Elisp (the rest being a C core that implements the Lisp interpreter).

Note that Emacs Lisp isn’t an ad hoc scripting language invented for use in just one editor. It’s a dialect of the famous programming language Lisp, which means it has a decades-old well-designed syntax and semantics. It’s a real programming language: in addition to the multiple books and articles written about Elisp, you can also learn from the hundreds of books and articles written about Lisp itself. And, what you learn about Elisp sets you on the way to becoming a real Lisp programmer.

But if you’re not interested in learning Lisp, you can still program your Emacs via the incredibly powerful macro system called Keyboard Macros. You simply start defining a macro, perform a sequence of editing actions (e.g., search for a keyword, capitalize it, delete the next two words, and add another word at the end of the line), then indicate you’re done. Now a keystroke runs the macro to repeat those actions. Once you’re convinced it’s working, you can tell Emacs to repeat the macro until it’s processed everything. Macros aren’t limited to operating on just one Buffer: you can use any Emacs commands in defining one, and so can switch Buffers mid-macro at will.

But Emacs goes well beyond the capabilities of most macro systems. Since invoking an external shell command is a basic capability of Emacs, you can do that in your macro and use the result. You can have many macros defined at once. You can edit your macro (rather than having to redefine it) if you discover it’s not quite right. You can save your macro with a name for use in future Emacs sessions. A macro can count (to do things like numbering). It can ask for confirmation of a step, or allow you to do a localized tweak at each invocation. All this without being a programmer.

Finally, GNU Emacs is free software. This doesn’t mean that you don’t have to pay for Emacs (though you don’t). It means that the project is built upon what the Free Software Foundation (FSF) calls the “four freedoms” — the freedom to (0) run the program, (1) study and change the program in source code form, (2) redistribute exact copies, and (3) distribute modified versions. The FSF achieves this via the frankly amazing invention of the Copyleft license. Without it, Emacs probably wouldn’t exist as the long-lived, continuously improving project that it is. And it assures that Emacs can never be taken away from you by any corporate entity.

I use the standard Emacs notation to describe keystrokes:

C-x

For any x, the keystroke Control+x.

M-x

For any x, the keystroke Meta+x (see below for more details on Meta keystrokes).

C-M-x

For any x, the keystroke Control+Meta+x (which is exactly the same as Meta+Control+x.).

S-x

For any x, the keystroke Shift+x

s-x

For any x, the keystroke Super+x²⁴

RET

The return key.

SPC

The space bar.

ESC

The escape key.

Control, Meta, and Super are modifier keys, i.e. they only take effect when held down simultaneously with another key, exactly like Shift. If you hold down Shift, Control, or Meta alone, and then simply release it, Emacs doesn’t even know you’ve done so: you must add a non-modifier key for the combination to register as a keystroke. You can combine as many modifier keys together as you have fingers for.

Your keyboard may have even more modifier keys. Emacs is aware of these other modifiers but doesn’t have any standard bindings that use them (you can use them for your own purposes though). In fact, because of arbitrary differences between the keyboards of different computer manufacturers²⁵, Emacs’s Meta modifier really stands for “your preferred non-Control modifier key”.

We don’t typically mention Shift as a modifier key, usually just writing X instead of S-x, and only use the S- notation occasionally for disambiguation or emphasis. The S- modifier can of course be combined with other modifiers (e.g. S-M-x, which is equivalent to M-X, or S-C-M-5, which is equivalent to C-M-%). Unless you choose to make a distinction with a custom binding, Emacs almost always equates a shifted letter in a keystroke with the lowercase version of the same keystroke: so for example both M-f and M-F (a.k.a. S-M-f) are equivalent: both invoke ‍forward-word‍. See Shift Selection for the only major exception.

There are 95 different basic printable characters²⁶, and they are all bound to self-insert-command so that they insert themselves as text when typed. For editing commands, Emacs uses all the control characters: C-a, C-b, etc. But this is only 32 characters, and Emacs has more than 32 editing commands.²⁷

To provide access to more key bindings, Emacs uses a Meta key²⁸. This gives us access to keystrokes such as M-a, M-b, etc.

Since Control and Meta are both shift-like modifier keys, what happens if you hold down both and then type a key? These combinations are valid keystrokes as well; they are notated C-M-a, etc. Because both Control and Meta are modifier keys, C-M-a must necessarily be the same keystroke as M-C-a. For consistency we always write the former.

Modern keyboards also offer a wealth of non-printing keys such as the home key, the four arrow keys, and the function keys (F1 and so on). Emacs also binds commands to many of these. The notation we use for these keys looks like <home> for the home key, <down> for the down arrow, <f1> for the first function key, and the like. Emacs can also distinguish the keys of a numeric keypad (whether NumLock is on or off.) These keys can all be combined with modifier keys to form keystrokes like C-M-<down>.

Here are the Emacs spellings of some of the most commonly used non-printing keys on your keyboard.

The Control and Meta keys plus the printing characters give us 256 possible keystrokes²⁹, or 160 editing commands after eliminating the self-inserting characters. But Emacs has many more than 160 commands! To handle this we also use prefix commands. A prefix command is a keystroke that, when typed, waits for another keystroke to be typed, making a pair (sequence) of keystrokes bound to one command. Each prefix command adds another 256 keystrokes that we can bind commands to. Prefix commands often group together commands that are somehow related.

The most important prefix commands are:

C-h

The help prefix, used for Help commands.

C-x

The extra prefix; this prefix is used mostly for commands that manipulate files, buffers and windows.

C-c

The context-specific prefix. Used for commands that are specific to particular Modes, so they are free to be used for different commands depending on context. This prefix also reserves a set of keystrokes specifically for the user to use for their own purposes. These are the most variable of Emacs commands.

These three prefixes give us another 768 keystrokes, for a total of 928. But Emacs has far more than 928 commands! To handle this, you can bind one of the subcommands of a prefix command to another prefix command, like C-x 4 for example, or C-x v, each such binding yielding potentially another 256 keystrokes. A number of these two-character prefixes exist, but they’re rather specialized, and don’t contain a full set of 256 commands (usually there are only a few, and the prefix is just used for a mnemonic grouping). There are even three character prefixes, but most people won’t admit to using them.

What if you start typing a prefix, like C-x, and then decide you didn’t mean it? Emacs will be sitting there, showing this in the Echo Area:

C-x-

waiting for you to finish. You can abort this partially completed prefix by typing C-g (‍keyboard-quit‍).³⁰

You can also interrupt a command that’s asking you a question, or for information (like a file name): if you type the command to open a file and it’s asking you for the filename, but you’ve changed your mind, C-g will abort it. It will also interrupt a running command that you want to now stop. Perhaps you’re editing a file and have initiated a search-and-replace operation, and after several replacements, you see it was not what you wanted: C-g will interrupt it in the middle (and, of course, you can then Undo what you’d already done).

By now we’ve entered a sort of rarefied atmosphere: even the most hardcore Emacs nerd doesn’t really use all these key bindings. Some Emacs commands are used very rarely, and, when you need one, it’s easier to invoke the command by typing its long name directly, using the Completion system to remind you of the precise name.

There’s one Emacs command that can be used to execute any other command by typing its long name: M-x (mnemonic: “eXecute” or “eXtended”). When you type M-x, Emacs prompts you, in the Echo Area³¹, for the name of any command (with Completion), even if that command is bound to one or more keys already, and then executes it.

The prompt looks like:

M-x

and the completion works rather like that of any Unix shell, by typing an initial part of the command and hitting TAB³². So you might type:

M-x backw

and hit TAB at that point; Emacs will partially complete this to:

M-x backward-

and if you then type:

M-x backward-sen

and hit another TAB, it will complete the entire command (because the prefix is now unambiguous):

M-x backward-sentence

Now you can hit return (RET) to execute the command or if that’s not what you meant, you can edit what you’ve typed (using any Emacs editing commands) and keep completing as you go; of course a C-g will abort the M-x.

If you hit TAB again at the point at which you’ve achieved a partial completion (at the point of backw or backward- or backward-sen above), Emacs will pop up a transient buffer showing all the possible completions (you may discover some surprising and interesting-sounding commands this way).

This can be a lot of commands! If you type M-x and immediately hit TAB, Emacs will pop up a buffer showing all the interactive commands that exist at the moment. In a stock Emacs, freshly started, this will be over 4,000 commands; in my current Emacs session, with many third-party packages loaded, I get about 8,000.

When you see something like “ M-a (‍backward-sentence‍)” in this book, it means that the keystroke M-a is bound (by default) to the command backward-sentence (in most Modes, or in the Mode I’m currently talking about), and so at any moment you can use M-x backward-sentence or M-a, as you prefer.

How does anyone remember these 928 commands? Simple: you don’t. Every Emacs user knows a different subset of commands. I’ve used Emacs for 44 years (starting with the original TECO Emacs), and I learn useful Emacs commands that are new to me all the time. Often I notice another Emacs user doing something and I have no idea how they’ve done it, so I ask and learn some Emacs command that I just never came across, or never developed as a habit, or once knew and forgot!

Some Emacs users just learn the most basic commands and are completely happy. Most users learn the basics and then some advanced commands that suit their needs. Some users are constantly learning new commands to speed their editing. A nerdy few progress to writing their own totally new Emacs commands.

Many Emacs commands take arguments, the way a procedure or function takes arguments in a programming language. Most commands prompt you for their arguments: e.g., a command to read in a file will prompt you for the filename.

There’s one kind of argument that’s so commonly accepted that there’s a special way to provide it: a numeric argument. Many commands will interpret a numeric argument as a request to repeat themselves that many times. For example, the C-d (‍delete-char‍) command, which normally deletes one character to the right of the cursor, will delete N characters if given a numeric argument of N. It works with M-x commands and self-inserting commands too: try giving a numeric argument to a printing character, like a hyphen.

To give a command a numeric argument of, say, 12, type C-u 12 before typing the command. If you type very slowly, you’ll see:

C-u 1 2-

in the Echo Area. Then type C-d and you’ll have given delete-char an argument of 12. You can type any number of digits after C-u. A leading hyphen (C-u - 1 2) makes a negative argument; a lone hyphen (C-u -) is the same as an argument of -1 (which makes many commands “go backwards” in some sense). If you begin typing a numeric argument and change your mind, you can of course type C-g to abort it.

Because a numeric argument is given before you type the command, it’s also called a prefix argument; see “Arguments” in the Emacs manual.

Since one often isn’t interested in precisely how many times a command is repeated, there’s a shorthand way to get numeric arguments of varying magnitudes. C-u by itself, without any subsequent digits, is equal to a numeric argument of 4. Another C-u multiplies that by 4 more, giving a numeric argument of 16. Another C-u multiplies that by 4 more, giving a numeric argument of 64, etc. So C-u C-u C-u C-d would delete the next 64 characters.

C-u can be used before any other command, and for this reason C-u is called the universal argument. But note that commands aren’t required to interpret numeric arguments as specifying repetitions. It depends on what’s appropriate: some commands ignore numeric arguments, some interpret them as Boolean (the presence of a numeric argument — any numeric argument — as opposed to its absence), etc. Read the documentation for a command before trying it.

Some commands that are especially confusing for novices are disabled by default. When a command is disabled, invoking it subjects you to a brief dialog, popping up a window displaying the documentation for the command, and giving you four choices; for example:

You have typed C-x n n, invoking disabled command narrow-to-region.
It is disabled because new users often find it confusing.
Here’s the first part of its description:

   Restrict editing in this buffer to the current region.
   The rest of the text becomes temporarily invisible and untouchable
   but is not deleted; if you save the buffer in a file, the invisible
   text is included in the file.  C-x n w makes all visible again.
   See also ‘save-restriction’.

Do you want to use this command anyway?

You can now type
y   to try it and enable it (no questions if you use it again).
n   to cancel--don’t try the command, and it remains disabled.
SPC to try the command just this once, but leave it disabled.
!   to try it, and enable all disabled commands for this session only.

If you invoked the command by accident, just hit n. If you’re sure you know what you’re doing, hit y. Otherwise, SPC is the way to go, until for any given command you’re comfortable enough with it to say y.

In this book, I make occasional recommendations to un-disable certain commands I consider very useful; you can see them all in my recommended Initial Init File.

I define a felicitous key binding to be one that can be easily repeated, possibly even auto-repeated by your keyboard. The most felicitous binding is a single keystroke, like C-f; you can repeat it easily by just holding down Control and tapping away af f. Even chorded single keystrokes like C-M-f are maximally felicitous.

Any prefix binding is less so. A two-character prefix binding that uses the same modifier key in each case, such as C-x C-t, is not too bad, as you can just keep the modifier held down and quickly tap x and t. But when the modifiers differ, we have maximum infelicity.

Consider the horrible horizontal scrolling key-binding C-x < (‍scroll-left‍),³³ which is effectively C-x S-,. Repeatedly invoking this command while observing the change in the visible part of the text in the Window is like playing a particularly complex arpeggiated piano part: hold down Control, hit x, lift finger from x and lift finger from Control, hold down Shift, hit <, lift finger from Shift and from <, and finally repeat.

Since any Emacs command can be bound to more than one keystroke, in some cases like this, I provide Init File snippets with additional more felicitous bindings, like my S-C-< for scroll-left, which can be easily tapped out or auto-repeated.

In most cases, the felicity of key bindings is a minor issue, but for commands that you tend to repeat, like scrolling commands, Window-switching commands, and dragging commands, more felicitous bindings can make a big difference.

As mentioned, I don’t use the mouse in Emacs at all (and barely at all in an external web browser, my only other GUI application), so I won’t be devoting much space to it, except to say that Emacs fully supports it.

The mouse is a much more complex user interface device than the keyboard. Consider the traditional hand-held mouse (ignoring laptop touchpads for the moment). The minimal mouse has one button, which, like a key on a keyboard, can be pressed (or clicked) to generate an event that can be bound to an Emacs command. Also like a key-press, this button-click can be modified by any of the keyboard modifier keys, such as Shift, Control, Meta, and the like.

But the complexity of a single mouse click goes way beyond this. We need to potentially distinguish between a button-press and a button-release, a simple in-place click versus a drag, motion without clicking, and double- and triple-clicks (or even more).

But that’s not all: many mice have more than one button: mice on Unix systems traditionally have three buttons, and two- and five-button mice are common. Unlike non-modifier keyboard keys, multiple mouse buttons can be chorded: that is, pressing or clicking two or more buttons simultaneously counts as a completely different button!³⁴ Many mice have a scroll wheel, which acts as another, more complex button, which may also tilt. Laptop touchpads add more complexity. And the keyboard modifier keys can be mixed into all of this.

Emacs defines an abstraction of all this complexity, defines a set of default global mouse bindings, and of course allows you to modify or add mouse bindings yourself.³⁵

All that said, I’ll just summarize the most basic default global mouse bindings; you can get complete details in the manual.

• clicking button 1 moves Point to the location of the click
• dragging with button 1 selects text
• clicking button 2 moves Point and then pastes the contents of the system clipboard³⁶
• clicking button 3 copies the text between Point and the clicked location to the kill ring

The most common things you do with files are load them and save them.

C-x C-f (‍find-file‍)

This is the main command used to read a file into a Buffer for editing and is what the menu item File / Open File does. It’s actually rather subtle. When you execute this command, it prompts you for the name of the file (with Completion). Then it checks to see if you’re already editing that file in some Buffer; if you are, it simply switches to that Buffer and doesn’t actually read in the file from disk again. If you’re not, a new Buffer is created, named for the file, and initialized with the contents of the file. To create a brand new file, just type a nonexistent file name; you’ll get an empty Buffer that will create a new file when saved³⁸. In any case, the current Window is switched to view this Buffer.

C-x C-s (‍save-buffer‍)

This is the main command used to save a file, or, more accurately, to write a copy of the current Buffer out to the disk, overwriting the Buffer’s file, and handling backup versions.

C-x s (‍save-some-buffers‍)

This command allows you to save all your Buffers that are visiting files and have modifications, querying you for each one and offering several options for each (save it, don’t save it, peek at it first then maybe save it, just save all of them without asking, etc).³⁹

See Files for more information.

The most common things you do with Buffers, which you can for now think of as opened files, are switch between them, list them (in case you’ve forgotten which ones you’ve opened), and occasionally clean them up. But to paraphrase Philidor, “The Buffers are the soul of Emacs” and in short order you’ll be doing a lot more with them.

C-x b (‍switch-to-buffer‍)

Prompts for a Buffer name (with completion) and switches the Buffer of the current Window to that Buffer. Doesn’t change your Window configuration (if you had three Windows before, you still have three afterwards). This command will also create a new empty Buffer if you type a new name; this new Buffer will not be visiting any file, no matter what you name it (until you save it, at which point it will be visiting the just-created file).

C-x C-b (‍list-buffers‍)

Pops up a new Window which lists all your Buffers, showing for each the name, state (modified or not), size in bytes, the Buffer’s major mode, and the file the Buffer is visiting (if any). This is an interactive Buffer, meaning that, within it, you’re in a special mode that allows you to manipulate Buffers: select them, delete them, save them, search a subset of them, etc.

C-x k (‍kill-buffer‍)

Prompts for a Buffer name (with completion) and removes the entire data structure for that Buffer from Emacs. If the Buffer is modified and is visiting a file, you’ll be given an opportunity to save it. Note that killing a Buffer in no way removes or deletes the associated file (nor does it delete the Window; that Window will simply start displaying some other Buffer). kill-buffer is happy to delete a modified non-file Buffer without any warning however, so don’t keep important notes in Buffers like this (such as the *scratch* Buffer). (Emacs has better ways of note-taking anyway.)

C-x C-q (‍read-only-mode‍)

Make a Buffer read-only (so that attempts to modify it are treated as errors), or make it read-write if it was read-only. If you open a file that you don’t have permission to modify, Emacs sets the Buffer to read-only, to prevent you from wasting your time editing it when you won’t be able to (directly) save it. This command lets you have your way with it.

See Buffers for more information.

Just like the windows on your desktop, the most common things you do with Emacs Windows are create them, delete them, resize them, switch between them (i.e., change the focus), and scroll around in them. Emacs manages its Windows in a tiling manner, like one of those tiling window managers that are all the rage these days.

See Windows for more information.

Point (“Point” in the Emacs manual) is the Emacs term for what we’ve been loosely calling your cursor up to now; the cursor always shows the position of Point in your Buffer. Point is where text is inserted when you type, and where most editing operations happen. When you “move” in a Buffer, you’re simply adjusting the location of Point.

Point is really just a number: the offset, in characters, from the beginning of the Buffer, of the character after Point. You typically don’t care about this number as such unless you’re writing Elisp, but if you want to know the value of Point, C-x = (‍what-cursor-position‍) will report it in the echo area (along with some other interesting information⁴²).

Point always identifies a location between two characters. By default, Emacs displays, in the current Window, a cursor at Point in the form of a solid box. The box seems to be on top of a character, but Point is before that character. (You could ask Emacs to instead display the cursor as a thin vertical line, which would make the position of point as between two characters easier to understand but perhaps harder to spot.)

Every Window has a distinct Point which is always visible in that Window. This means that if you visit a file and split the Window into two, you can have Point in a different position in each Window, so you can look at distant parts of the file at the same time.

The Mark (“Setting Mark” in the Emacs manual) is a sort of additional, invisible, Point. A Buffer has only one Mark⁴³, and every Buffer’s is distinct. However, unlike Point, there’s no Mark in a Buffer until you set one (explicitly or implicitly).

The main purpose of the Mark is to determine one end of the Region, Point being the other.

You set the Mark (at the same location as Point) with a special command, C-SPC (‍set-mark-command‍); C-@ is an old synonym. Then, as you move Point, the Mark stays where you set it and whatever is between the two forms the Region.

The Region is the text between Point and Mark. If the Mark exists in a Buffer, so does the Region (because Point always exists). The Region can be of any size: a few words, many paragraphs, the next 253 characters. If you set the Mark and don’t move Point, the Region is of size zero. (Yes, an empty Region is useful.) If you set the Mark at the end of the Buffer, and move Point to the beginning of the Buffer, then the Region encompasses the entire Buffer.

In fact, the Region is the same regardless of whether Point comes first in the Buffer or Mark does; it makes no difference, just do what’s convenient.

This scheme predates the commercial availability of the mouse, and provides a keyboard-driven equivalent of sweeping out text with the mouse. In fact, if you click mouse button 1 (usually the left button) at a position in the Buffer, and drag the mouse pointer in any direction, and then let go of the button, Emacs sets the Mark at the place where you clicked, and the Point at the place where you let go — another way to set the region.

When you explicitly set the Mark with C-SPC (or the mouse), the Mark is activated, and the Region is suddenly colored differently so you can visualize it (see Figure 4). If the color becomes distracting, a C-g will deactivate the Region, as will most commands that operate on the Region after they’re done with it (so the Active Region is typically transient: set it — color! — act on it — color gone).

But remember, the Region still exists (because there’s a Mark) even if inactive and invisible: you can still use it⁴⁴. If at any time you’re not sure of its extent, C-x C-x (‍exchange-point-and-mark‍) will reactivate the Region (and hence colorize it); it also swaps Point and Mark, which is handy if you want to fine-tune the extent of the Region with additional motion commands, or if you want to get to, or just peek at, the other end (the Region might be big enough that you can’t see both ends at the same time).

Once you’ve got a Region, you can do stuff to it. What kind of stuff? Delete it; copy it; duplicate it; capitalize or otherwise change the case of it; search-and-replace or undo within it; narrow your view of the Buffer to it; do a web search for it; treat it as a rectangle; write it out to a different file; colorize it; comment it out, count the words, characters, and lines within it; pipe it through a shell command. There are hundreds, nay, thousands, of Emacs commands that operate on the Region, and you can readily make your own.

In a typical GUI editor like Microsoft Word or Google Docs, you spend much of your time sweeping out or selecting text with the mouse and then activating a menu or toolbar item; the Emacs equivalent is to set the Region and then execute a command with a keystroke. In Emacs, you can likewise use the mouse and a menu, but you can also do everything with the keyboard, and in addition to setting the Region by setting the Mark and explicitly moving, you can set it implicitly via textual object commands, search commands, and more.

So now you know how to define the Region: let’s do stuff to it.

C-w (‍kill-region‍)

Kills the Region. (You can yank it back elsewhere.) Other editors call this operation cut. Mnemonic: wipe the region.

M-w (‍kill-ring-save‍)

Saves the Region without removing it from the Buffer (so you can yank a copy back elsewhere). Other editors call this operation copy. Mnemonic: a “bigger” wipe (which includes an immediate “paste”).

C-x C-i (‍indent-rigidly‍)

Rigidly indents (or dedents) the Region using the arrow keys; C-u 12 C-x C-i indents the region exactly 12 characters, without using the arrow keys.

C-x C-l (‍downcase-region‍)

Convert the entire Region to lowercase. This command is disabled by default.

C-x C-u (‍upcase-region‍)

Convert the entire Region to uppercase. This command is disabled by default.

M-q (‍fill-region‍)

Fills, i.e., justifies with a ragged right margin, all the paragraphs within the Region; with a prefix argument, right justify the paragraphs.

There are hundreds more commands that act on the Region, and the Region is fundamental to the way cutting and pasting is done in Emacs.

It’s time for some tough love. Emacs cut-and-paste goes significantly beyond that of most applications, but, I have to admit, at the cost of a significant learning curve. The advanced features are probably the most complicated part of beginner-level Emacs knowledge. The reason is just that it’s all very abstract and tenuous, and you have to picture invisible things in your head.

What are these advanced features?

1. Commands to precisely select (i.e. set the region around) a whole range of textual objects: words, symbols, lines, sentences, paragraphs, and more. We cover these in the next chapter. There are commands to directly select and kill (cut) these objects.
2. A history of previously killed and copied text. The Mac OS and Windows clipboards only hold one item—the last piece of text you killed or copied. Emacs remembers your 60 most recent items, and there’s no limit—you can increase it if you like.⁴⁶

Emacs calls its “clipboard” the Kill Ring, and it’s an invisible (albeit inspectable) data structure that you normally have to picture in your mind’s eye as you use and change it.

With the addition of one more command, new in version 28 of Emacs, your suite of cutting and pasting commands looks like this:

C-y yanks (“pastes”) your most recent kill (or copy), but you can get back any of your last 60 kills by instead using M-y. It presents all your kills using the Completion system: just choose the text you want to yank, as in Figure 5.

This function works best with an Incremental Narrowing Framework like Ivy or Selectrum (Ivy is shown in Figure 5).

Until you read Yanking Older Kills, you shouldn’t invoke this command immediately after C-y: it will have a different effect. If you need to use M-y right after a C-y, just precede it with C-g (‍keyboard-quit‍).

When you kill the Region with C-w, Emacs adds the killed text to a data structure called the Kill Ring, which holds the last several kills. This allows you to get older kills back. When you yank with C-y, the most recent kill from the Kill Ring is inserted into the Buffer at Point; it’s not removed or popped off the Kill Ring, so if you yank again, you get another copy.

The Kill Ring is really a linear list, and killing with C-w feels like pushing onto a stack; but the commands that deal with it actually treat it as a circular structure, so we call it a ring.

The Kill Ring is a global data structure, shared by all Buffers: this is so that you can use the Kill Ring to move text from one Buffer to another: kill some text in Buffer A, switch to Buffer B and yank it: you’ve moved the text.

What about copying text? Clearly, you can copy and paste by doing C-w to kill, immediately yank it back to where it was with C-y, and then move elsewhere and yank again (your text is still at the front because yanking doesn’t pop the Kill Ring). That’s C-w C-y (move somewhere) C-y.

M-w is a shortcut for C-w C-y, so we usually use that for copying: M-w (move somewhere) C-y.

Here’s how yanking older kills worked in olden times (before v28’s new M-y (‍yank-pop‍) command). Unless you’re a connoisseur of Emacs history (this all still works…), I suggest you skip ahead!

Suppose we kill the word “foo” in some Buffer. This pushes it onto the front of the Kill Ring (who knows what else is behind it):

The arrow points to what C-y will yank, by default the latest kill. Then we do some more work, and kill the word “bar” somewhere else. Now the Kill Ring looks like this:

Now we want to paste the “foo” somewhere⁴⁷. How do we get at it?

We yank with C-y and “bar” (what the arrow points to) is inserted. But now we immediately type M-y (‍yank-pop‍). When invoked immediately after C-y, it moves the yank-pointer back one step:

and simultaneously replaces the just-yanked “bar” at Point with “foo”. If we immediately type M-y again, it would move the yank-pointer back one more step, and replace “foo” with whatever is next oldest in the Kill Ring.

You don’t really need to picture the Kill Ring. When you want something from it, just type C-y and then if you think, “no, older” type M-y, and if you think, “no, older”, type another M-y and so on.

The only trick here is that you have to type M-y immediately after a C-y, or after a M-y: if you do anything in between — moving, typing, popping up the calendar — M-y will do the wonderful new thing of offering up older kills for Completion; if your Emacs is older then v28, it will complain with “Previous command was not a yank”.

If you actually type 60 M-y’s, you would then cycle around to the front of the Kill Ring again!

Suppose the Kill Ring looks like this:

Let’s look at the results of some yanks (each of these examples is an alternative to any of the others):

• C-y would yank “echo”
• instead, C-y M-y would yank “delta”
• or, C-y M-y M-y would yank “charlie”
• or, C-y M-y M-y C-y would yank “charliecharlie” (C-y always yanks from the pointer)

Note that C-y takes a numeric argument (positive or negative), so that C-u 3 C-y in our example is the same as C-y M-y M-y. M-y works the same way.

What if you type several M-y’s and decide you don’t want what you end up with? Usually you just undo them, but note that this undoes the changes to your Buffer, but doesn’t undo the motion of the yank pointer. If you do C-y M-y M-y, yielding “charlie”, you can undo, yielding “delta”. But your next C-y will yank “charlie” again, since that’s where you left the yank pointer.

When you’ve got your yanked text (whether acquired by one C-y or a chain of M-y’s, or the new Completion-based M-y), the Mark is set for you at the beginning of the restored kill, to make it easy for you to jump there (with C-x C-x (‍exchange-point-and-mark‍); see also the Mark Ring) — remember that you may have just yanked back a very large chunk of text, so the beginning could be a long way away.

I stole a function from the EmacsWiki that I call undo-yank (originally named yank-pop-forwards), that lets you reverse direction in the middle of a sequence of M-y’s, in case you overshoot; this actually moves the yank pointer, so you can think of it as an undo for yanks.

;; thanks to an anonymous EmacsWiki coder
(defun undo-yank (arg)
  "Undo the yank you just did.  Really, adjust just-yanked text
like \\[yank-pop] does, but in the opposite direction."
  (interactive "p")
  (yank-pop (- arg)))
(global-set-key (kbd "C-M-Y") 'undo-yank)

Ever feel that ’C-y M-y M-y M-y …’ is not a great way of trying to find that piece of text you know you killed a while back? — Colin Walters

Emacs’s abstract approach to the Kill Ring (an invisible data structure with an invisible yank-pointer), which may seem a mite austere, is very fast and efficient once you get used to it. But you might occasionally prefer a sort of WYSIWYG alternative, that lets you browse the Kill Ring interactively: see its entire contents and search it too. The new functionality of M-y command does this for you; an alternative is Colin Walters’ third party package browse-kill-ring.

So far, we’ve been talking about killing (or copying) the Region: as if you were always going to be sweeping out text, mouse-like (even if with the keyboard). But really, it’s much more common to work in terms of textual objects — in other words, kill a word or a line or a paragraph without bothering to sweep out its boundaries. We’ll discuss textual objects in detail in the next chapter.

Since the Kill Ring is a sequence of kills, you might think to use it to accumulate several separate chunks of text that you want to yank back elsewhere. Kill the first piece of text, move to the next and kill it; repeat several times and you’ve now got everything you want, in several chunks at the front of the Kill Ring.

But when it comes time to yank all these chunks back, you’ll have to do a bit of a dance with a combination of C-y’s and M-y’s in a somewhat surprising order (because the kills are accumulated on the Kill Ring backwards).

What you want to do instead is append to a single kill at the front of the Kill Ring, with C-M-w (‍append-next-kill‍). So you kill the first piece of text, move to the second, but now type C-M-w before killing it with C-w; this causes the second piece to be appended to the text of the front kill, instead of added as a new kill as usual. Think of C-M-w C-w as a single append to the kill command.

If the three pieces of text are “alpha”, “beta”, and “gamma”, the process looks like:

• move to “alpha”, set the Region, and C-w:

  alpha	…
  ↑

• move to “beta”, set the Region, and C-M-w C-w:

  alphabeta	…
  ↑

• move to “gamma”, set the Region, and C-M-w C-w:

  alphabetagamma	…
  ↑

Now you can move elsewhere, and with one C-y, you yank back “alphabetagamma”.

Obviously, C-M-w works the same with M-w, if you want to leave the original text in place.

C-M-w is a pretty low-level tool; Emacs has better ways of approaching the task of accumulating scattered chunks of text that don’t use the Kill Ring at all.

When you want to collect several chunks of text from various locations, the best way to do it is to append the chunks to a Buffer.

Move to the first piece of text you want to collect—let’s say the word “alpha”—and set the Region, but don’t bother to kill or copy; instead say M-x ‍append-to-buffer-with-newline‍. You’ll be prompted for a Buffer name which will collect all the pieces of text you’re gathering; just make up any name you like! If you’re collecting Greek letters, you could call the Buffer “greek” or “g”. Your text will be appended to your Buffer (which will be created as needed) with a newline added at the end.⁴⁸

Now find your “beta”. M-x ‍append-to-buffer-with-newline‍ again and use the same Buffer name. Repeat for “gamma” and as many other things you’re looking to collect.

When you’re done, go to the place you want to “yank” your collection, and say M-x insert-buffer: the entire contents of your accumulation Buffer is inserted at Point.

This scheme has several advantages over the Kill Ring for ambitious text rearrangement.

• You can do your collecting and appending over a span of hours (or even days).
• It allows you to use the Kill Ring as you like in between accumulations.
• You can freely use several different collection Buffers for different sorts of text, and intermix your accumulations.
• The accumulation Buffer is just a Buffer like any other, so you can switch to it at any point to fix it up, or save it to a file; you also aren’t required to use M-x insert-buffer to get your text; you can kill or copy the text you’ve accumulated to extract what you’ve collected in any order or combination.

See Mass Line Deletion for another solution, and “Accumulating Text” in the Emacs manual for more information.

The Kill Ring is a data structure to which only Emacs has access. But every time you kill or copy text to the Kill Ring — with any of the many commands that do so, not just C-w and M-w — Emacs also copies that text to the system clipboard. This is the data structure that all your other non-Emacs applications paste from (with the CUA keystroke Control+v, probably). So this gives you a simple way passing text to them.

It also works in the other direction: if the contents of the system clipboard are newer than the Kill Ring — because you did a cut or copy in a non-Emacs application — then C-y instead inserts the clipboard text — not the first item in the Kill Ring.

There are several configuration variables to control exactly how Emacs and the clipboard⁴⁹ interoperate; see “Clipboard” in the Emacs manual.

If you’re a long-time Windows user and the Control+x, Control+c and Control+v keystrokes are so thoroughly wired into your fingers that you just can’t get used to C-w, M-w, and C-y, don’t give up hope. Just say M-x ‍cua-mode‍ and Emacs will let you use the commands you’re used to. In order not to completely clobber the hundreds of key bindings on the C-x and C-c prefixes, the CUA bindings are only operative when the Region is active (colorized). There are several subtleties and extra features, so see “CUA Bindings” in the Emacs manual for the complete story.

If you like cua-mode, you can turn it on by default in your init file with this line of code:

(cua-mode +1)

If you execute any of the motion commands while also holding the Shift key, you can short-cut the selection process via Shift Selection. Consider M-f (‍forward-word‍). If you instead use S-M-f, the Mark is automatically set at Point, and then you move forward one word: so the word is automatically selected. S-M-f is essentially C-SPC M-f. In our example:

we can instead do:

The same thing is true for motion backwards, and for any of the other textual object motion commands. Just add the Shift.

And, if you type a shifted motion command, and immediately repeat it (while holding down the Shift key), the selection is enlarged until you finally issue a non-shifted-motion command. So if you say S-M-f S-M-f S-M-f you will have set the Region around three words.

You can mix different objects too: S-M-f S-C-n S-C-f is also legitimate.

A special case is transposing (or swapping) two objects: that is, put Point between two objects (say, sentences) and swap them — the left hand sentence is now the right hand sentence and vice versa. One single command replaces a more complicated pattern of killing, moving, and yanking.

For example, here in line 0 Point (|) is between “one” and “two”. If we transpose-words with M-t, we get the result in line 1:

0 one | two three four five
1 two one | three four five
2 two three one | four five

Note that Point has moved forward, or if you prefer, it remains after “one”. This means that another M-t will result in line 2. So several transpose commands in a row can be chained together. You might think of this as dragging “one” to the right.

Most of the transpose commands react to a numeric argument of N by transposing the object to the left of Point with the one N objects to the right. This means that an argument of 1 is the same as no argument (on line 0 above, the word “two” is one word away from the left-hand word “one”).

But if we say C-u 2 M-t, we get this result, because “three” is two words to the right of “one”:

0 one | two three four five
1 two three | one four five

Personally I think it’s easier to chain several transpose commands to achieve the equivalent effect, but your brain may work differently.

A negative argument transposes in the opposite direction (backwards, rather than forwards). In addition, a numeric argument of 0 (which would otherwise not do anything!) is interpreted specially: it swaps the object containing or after Mark with the object containing or after Point, no matter how far apart they are! This is a long-distance transposition, with no chaining or counting required. Here in line 0 ^ indicates Mark (in “one”), and | Point (in “eleven”); we say C-u 0 M-t:

0 ^one two three four five six seven eight nine ten ele|ven twelve thirteen
1 ele|ven two three four five six seven eight nine ten ^one twelve thirteen

(Frankly I’ve never internalized this and always just Kill, move, and Yank in this use case.)

The exact definition of what makes up a given textual object is often customizable and may vary slightly from mode to mode. This is useful because it means that you can use the same motion commands and yet have them automatically customized for different types of text.

Here’s the complete list of standard Emacs textual objects, with their backward- and forward-motion, marking, killing, and transposing key bindings:

N.B.: in these charts, M-x ... means that the obvious command exists but isn’t, by default, bound to a key — that is, M-x mark-end-of-sentence, M-x ‍transpose-sentences‍, and M-x ‍transpose-paragraphs‍.

Pages are separated by form feed characters (C-l — that’s L, not the digit 1), just as lines are separated by newline characters. This used to be a common concept back when Emacs was young; when printing, you had to manually indicate where a page break should occur, causing the printer to skip to the top of the next page (or “form”), and to do this you would insert a form feed character into your text.

Since form feeds count as whitespace in most programming and markup languages, pages are still a useful idea, and Emacs has several commands that do things in terms of them. You can insert a form feed into your file by typing C-q C-l (see Quoted Insert).

So while it’s rare now to use a form feed to actually force a new page when printing⁵², it’s handy to be able to separate a large file into “pages” which are really just bigger sections than paragraphs. A typical organization in a file of source code is to precede each section header comment with a form feed, and then you can navigate by these logical sections via C-x [ and C-x ].

Here’s what it looks like in a file of my Emacs Lisp source code (Elisp comments start with one or more semicolons, and a form feed character displays as ^L):

^L
;;; parsing and unparsing

That ^L is not two characters, as you can clearly see if you move your cursor across it one character at a time: it just looks like it.

C-x [ (‍backward-page‍)

Moves to the beginning of the current page.

C-x ] (‍forward-page‍)

Moves to the end of the current page.

C-x C-p (‍mark-page‍)

Sets the Region around the entire current page; unlike most marking commands, in addition to setting the Mark at the end of the object, this one also moves Point to the beginning.

Finally, it’s useful to be able to jump directly to the beginning or the end of the buffer without having to scroll.

M-< (‍beginning-of-buffer‍)

Moves to the beginning of the buffer.

M-> (‍end-of-buffer‍)

Moves to the end of the buffer.

Mnemonic: the beginning of the buffer is a location that’s less-than any other location, and vice versa.

C-x h (‍mark-whole-buffer‍)

Move Point to the beginning of the buffer and set Mark at the end of the buffer.

M-x mark-beginning-of-buffer

Set Mark at the beginning of the buffer, without moving Point,

M-x mark-end-of-buffer

Set Mark at the end of the buffer, without moving Point.

An /S-expression⁵³/ (“sexp” for short) is the name, in Lisp, for atoms (symbols, numbers, and quoted strings) and the balanced parentheses that enclose them, recursively. In Emacs, this useful notion is available everywhere; it’s especially useful for editing programming languages, but even in prose it’s very useful to be able to move over, copy, or kill a parenthesized phrase. The characters that Emacs recognizes as parens are usually regular parentheses (aka round brackets), square brackets, and braces (aka curly brackets), but it depends on the Major Mode (for some languages, angle brackets (i.e. < and >) may act as parens too).

But sexps are more than just balanced parens. A symbol (roughly, a word) that doesn’t contain any parens also counts as a sexp, as does a number. In most programming language modes, quoted strings are sexps (using either single or double quotes, depending on the syntax of the language). A sexp is any of those, or a parenthesized sequence of them, recursively.

These commands may seem confusing at first, but for editing most programming languages they’re fantastic. Not only do they move you around quickly and accurately, but they help spot syntax errors while you’re editing, because they’ll beep at you if your parens or quotes are unbalanced.

C-M-b (‍backward-sexp‍)

Moves backward over the next sexp. If your cursor is just to the right of an opening paren, C-M-b will beep, because there’s no sexp to the left to move over: you have to move up.

C-M-f (‍forward-sexp‍)

Moves forward over the next sexp. Same error if your cursor is just to the left of a closing paren.

Here’s an example of linear movement via sexps. The location of Point is shown by |, and we move forward with C-M-f each time. After three C-M-f’s Point is after “Emacs” in line 3, because each of the first three words count as symbols and thus are sexps. But the next C-M-f leaps over the entire parenthesized expression in line 4.

0. |In  1976,  Emacs  (in its original TECO form)  was invented.
1.  In| 1976,  Emacs  (in its original TECO form)  was invented.
2.  In  1976|, Emacs  (in its original TECO form)  was invented.
3.  In  1976,  Emacs| (in its original TECO form)  was invented.
4.  In  1976,  Emacs  (in its original TECO form)| was invented.

C-M-u (‍backward-up-list‍)

Move backward up one level of parens. In other words, move to the opening paren of the parens containing the cursor, skipping over balanced sexps.

C-M-d (‍down-list‍)

Move down one level of parens. In other words, move to the inside of the next opening paren, skipping over intervening sexps.

Let’s move up in nested parentheses with C-M-u. On line 0, Point is in front of the word “Lisp”. We type C-M-u and on line 1, Point is now in front of the nested parentheses. One more C-M-u and Point moves in front of the leftmost paren.

0. (in its original TECO form  (which preceded the |Lisp implementation))
1. (in its original TECO form |(which preceded the  Lisp implementation))
2. |(in its original TECO form (which preceded the  Lisp implementation))

Nested parentheticals may be poor prose style, but they’re extremely common in source code in almost any programming language.

Now let’s move down with C-M-d. On line 0, Point is on the return type of this C function definition; on line 1, after C-M-d, Point is inside the formal parameter list:

0. |void synctex_updater_free( synctex_updater_t updater) {
1.  void synctex_updater_free(|synctex_updater_t updater) {

C-M-@ (‍mark-sexp‍)

Set Mark at the end of this sexp.

C-M-k (‍kill-sexp‍)

Kills the sexp after Point.

Since function defintions are such an important unit of text in programming languages, whether they’re called defuns, subroutines, procedures, procs, or whatever, they also count as textual objects. Like the sexp commands, these commands work appropriately in most programming language modes. Emacs calls this generic notion of function or procedure defun, again after Lisp.

C-M-a (‍move-beginning-of-defun‍)

Move to the beginning of the current function definition.

C-M-e (‍end-of-defun‍)

Move to the end of the current function definition.

C-M-h (‍mark-defun‍)

Sets the Mark at the end of the current defun.

Note the mnemonic analogy with lines and sentences.

If you kill several times in a row, with any combination of kill commands, but without any non-kill commands in between, these kills are appended together in one entry on the Kill Ring — there’s no need to precede the kills with C-M-w (‍append-next-kill‍). For example you can kill the next six words as a unit with M-d M-d M-d M-d M-d M-d, move elsewhere and yank back all six (with their intervening whitespace) with one C-y. C-u 6 M-d would be equivalent. You can kill a block of lines with a sequence of several C-k’s, or you could kill the next sentence and the following two words with M-k C-u 2 M-d (note that the numeric argument C-u 2 doesn’t break up the sequence of kills, because C-u 2 is part of the following M-d command).

After setting the Region around one or more textual objects, whether by setting the Mark and moving, or Shift Selection, or by object-specific mark commands, you can fine-tune the Region by lengthening or shortening it at either end with any other motion commands — perhaps you selected a paragraph with M-h but you don’t want the blank line at the front of it, or selected a sentence and want to add the two words at the beginning of the following sentence. Just move Point in any manner. If you want to adjust the other end, where Mark is, use C-x C-x (‍exchange-point-and-mark‍): now Point is where the Mark was and you can adjust that end.

You can exploit your knowledge of the contents of your text by using Emacs’s many search capabilities to move around. If you want move to where you were discussing Ursula K. Le Guin, just search for her name.

We learned in Selecting Text that there’s only one Mark in any Buffer. This is strictly true, but there’s an additional data structure in each Buffer called the Mark Ring (see Info) that holds a history of previous Mark locations⁵⁴.

Whenever you set the Region, whether with C-SPC (‍set-mark-command‍) or a mouse selection, or implicitly with textual object mark commands (like M-h (‍mark-paragraph‍)), the Mark’s current location is pushed onto the Mark Ring. The Mark is also set for you automatically at places where you’ve done “significant” things, like changing text, moving a long way away in one big jump (there being many ways to do this), the spot where you issued a search command, and the like⁵⁵, and these locations also go onto the Mark Ring.

Thus a breadcrumb trail of Marks is left for you to find your way back, Theseus-like, to where you’ve been, and provides a quick way to get back to these previous locations. The way to jump back to the previous Mark location is to give C-SPC (‍set-mark-command‍) an argument, so C-u C-SPC. It also rotates the Mark Ring, so that a repeated, uninterrupted sequence of C-u C-SPC commands will take you back in time through your previous Mark locations. The Mark Ring is a circular structure, so when you hit the end, you’ll circle round to the most recent Mark location again. You’ll notice the analogies to the operation of the Kill Ring.

It’s a common idiom to set the Mark explicitly as a breadcrumb to jump back to, rather than as part of selecting some text. If you set the Mark, which activates the Region, and immediately set it again in the same spot, the Region is deactivated; this is nice for using the Mark to record your position — you’re not really setting the Region, so why be distracted by the color of the active region? So remember C-SPC C-SPC as the breadcrumb-dropping command.

Perhaps the most surprising way of moving is by Undoing; if you recently made a change to your text (possibly just by adding some more) and then moved elsewhere, it’s pretty common to want to go back to where you made that change, and the easiest way to get there is to just Undo it, because wherever you may be now, an Undo pops you right back to the last change in that Buffer. You can use this trick even if you don’t want to Undo your change — because you can instantly restore it by a Redo.

Obviously this trick gets much trickier if you want to move back to where you were, say, three changes ago: three Undos gets you to the right spot, but assuming you liked your changes, if you Redo them you’re now back where you came from! The third-party packages goto-last-change and goto-chg solve the problem by going to the Undo locations without actually Undoing!

Various Major Modes may implement special ways of moving. Perhaps the most obvious is moving by identifiers (names) in programming language modes: you can move from a use of a function or variable to the definition, for example, or move through all the uses of an identifier. This typically works across all the files in a defined project. Some languages have a bespoke way of handling this via the language server protocol (LSP)⁵⁶, but Emacs also supports various language-agnostic approaches, such as the Xref subsystem.

Sometimes, rather than moving pointedly to get to a precise location, you just want to scroll through your text to get an overview and stop at the spot that catches your fancy; scrolling is covered in the chapter on Windows.

Most of the textual-object motion commands can be thought of as moving relatively: when you move forward by one word (sentence, paragraph, …) you’re moving relative to the location of Point.

But occasionally it’s useful to move to an absolute position (though much less often than one might think). The most common type of absolute motion is to move to a specific line by its line number. For example, according to M-x ‍what-line‍, this line as I’m writing it is line 1,497. If I move elsewhere, I can come right back here by jumping to line 1,497!

Of course, since I’m editing, in a few minutes that line probably isn’t line 1,497 anymore, and I probably won’t remember that number for more than a few seconds, and anyway, if I wanted to come back here why don’t I just use the Mark Ring or search?

I think most people who use line numbers as motion targets have line numbers turned on.

Emacs doesn’t display line numbers by default, though it does show the current line number in the mode line, but you can toggle the traditional left-margin display of line numbers on and off with M-x linum-mode, or arrange for them to always be on in every Buffer⁵⁷. To me they just waste screen real estate.

But what if you’re compiling a program in your terminal and it reports a syntax error on line 563? Well, you should be compiling that program in Emacs with M-x ‍compile‍, and then you can jump to that error with a keystroke, with no need to type any line number; see Compiling Code.

However, it’s true that you do occasionally get a line number foisted upon you in an unpredictable manner — say, from a stack trace when a program blows up, or from some log file. When you do, M-g g (‍goto-line‍) will prompt you for the number and jump there.

Much more rarely, you’ll have a byte (character) offset from the beginning of some file; M-g c (‍goto-char‍) will take you there.

Finally, M-g TAB (‍move-to-column‍) is what you need for absolute positioning on the other axis: it moves to the given character offset from the left margin. There are lots of subtleties to this command — like, how do you count tab characters in the line, or multibyte (say, Unicode) characters? — but hopefully you’ll never need it; I’d never used it before I had to write this paragraph! See the documentation for details.

Emacs is famously malleable and customizable: you can make it work and look exactly the way you want, and this is mostly achieved through variables. Do you not like the red color of the squiggles under your spelling errors? That color⁶⁰ is specified in the variable flyspell-incorrect, so you can change it.

Do you wish Emacs wouldn’t beep at you when an error occurs? The visible-bell variable lets you change that.

Throughout this book, I make some recommendations for tweaks to some variables, and give examples of others that you might want to change.

A variable can hold any kind of Lisp value, and there are several types: truth values (corresponding to true / false or on / off: called Booleans by programmers), numbers, text (called strings by programmers), functions, and, perhaps most importantly, lists, which are sequences or collections of values of any types⁶¹. Also, and I don’t want to blow your mind here, but a variable (which is a symbol, you’ll recall) can also hold… a symbol.

Let’s look at some examples of real Emacs variables and the (typical) types of values they hold.

In Table 2, we see that visible-bell is on (because t is the Elisp Boolean true value) while delete-by-moving-to-trash is off (because nil is the Boolean false value).

kill-ring-max determines the size of the Kill Ring.

report-emacs-bug-address is the email address for Emacs bug reports such as those generated by ‍report-emacs-bug‍, and as such must be a string.

tool-bar-position specifies where the tool bar should be displayed, and must be one of the four symbols top, bottom, left, or right.⁶²

split-window-preferred-function is a variable that holds a function that is actually called to split a window; split-window-sensibly is a symbol that names a function suitable for this purpose. Variables that hold a function are typically set to the symbol that names the function.

Finally, image-types is a list—of symbols, in this case, but Elisp lists can hold any types or combination of types (including nested lists).

You can take a look at the current value of any Emacs variable at any time. The usual way is to use the Help facility via C-h v (‍describe-variable‍) or the more ecumenical C-h o (‍describe-symbol‍); see Help for a Variable for details.

As the name implies, you can also change the value that’s bound to a variable. There are three times at which you might do this:

1. when Emacs starts up, via your Init File or the Customize Facility;
2. explicitly and interactively, while you are using Emacs;
3. whenever you visit a given file.

For cases 1 and 2, it’s best to use Customize, because it provides documentation about how the variable works, guides you though the possibilities, prevents you from making common mistakes, and allows you to revert your changes or save them for future sessions. It’s equally good for making settings for your startup configuration, for setting a value just for this session, or just to try out a new value for a while. You’ll know you can use Customize when C-h v says, “You can customize this variable.”

Note, however, that Customize only works for User Options. If you want to change a variable that hasn’t been defined as such, you’ll have to learn a little about Elisp.

Variables can have different values in different buffers. For example, you might want to indent lines differently when you’re writing a Python program than when you’re writing prose. We call these buffer-local variables. They start out with a default value, but if you change the value of such a variable, the change only applies in the current buffer.⁶³

You can’t change the local value of a buffer-local variable with Customize; you either do it via Elisp in your Init File (if you want the change in every Emacs session; see Hooks below), or else you use M-x ‍set-variable‍ to do it just for now, in the current buffer.

To set a variable with set-variable, you need to know the type of value the variable expects; that means you need to read its documentation with C-h v. You also need to know enough about Elisp to understand the syntax of the different types. There’s a difference between the number \(256\) and a string containing the three digits \(2\), \(5\), and \(6\).

If you say M-x set-variable, Emacs will prompt you for the name of a variable. You might enter:⁶⁴

Set variable: report-emacs-bug-address

The next prompt would be:⁶⁵

Set report-emacs-bug-address globally to value:

According to the documentation, this value needs to be a string; if you were to enter:

Set report-emacs-bug-address globally to value: myself@example.com

you would get a type error:

user-error: Value ‘myself@example.com’ does not match type string of report-emacs-bug-address

Table 2 provides a cheat-sheet for entering values of the major data types in the correct syntax; see “Init Syntax” in the Emacs manual for details, and also for how to set variables in your Init File. But remember, prefer M-x customize-variable whenever possible.

The syntax of Booleans is very simple: the true value is spelled t and the false value, nil.⁶⁶ I could give you other examples of the true and of the false values, but it would require a little too much explanation.

Numbers are represented as a sequence of base 10 digits, like 256, possibly including a decimal point, as in 3.141593. There’s a special syntax to enter numbers in other bases.

Strings are enclosed in double-quotes; there are some tricks here, like how to include a double-quote in a string---""" is no good, because the enclosed (second) " terminates the string: you have to escape it with a backslash like this: "\"". There are also other “escapes” so that you can include control characters and such; see “String Type” in the Elisp manual.

Symbols look rather like strings without quotes (they don’t need quotes because they can’t contain spaces); you can just type their names. As discussed above, a function is typically represented by the symbol that names it (though for the Elisp programmer, there are other possibilities) and so uses the syntax of symbols.

Lists are simply zero or more space-separated instances of any types enclosed in parentheses. The empty list is (). There’s no problem nesting lists: this list contains two values, a string followed by a list of three numbers: ("foo" (1 2 3)).

This should be enough syntax for you to enter values at the set-variable prompt.

Emacs’s extensive online help is available via the help key, C-h ⁶⁷. C-h is a prefix key. Type C-h twice to get a window describing all the following commands and more (a SPC will scroll this window). Some of the most useful help commands are:

C-h a (‍apropos-command‍)

Prompts for keywords and then lists all the commands whose names match. If you’ve forgotten the name of the command that counts words, C-h a word count will reveal it.

C-h k (‍describe-key‍)

Prompts for a keystroke and describes the function bound to that key, if any. If you remember M-= but can’t recall what it is, use C-h k (it’s ‍count-words-region‍).

C-h w (‍where-is‍)

Prompts (with Completion) for the name of a function and tells you (in the Echo Area) what keystrokes will invoke it. If you cheekily type C-h w where-is, you’ll see: C-h w, <f1> w, <help> w.

C-h o (‍describe-symbol‍)

Prompts (with Completion) for the name of a function, a variable, or a face⁶⁸ and describes all the matches. If you remember count-words-region but not what it does, C-h o count-words-region will tell you. (C-h f will do the same but only for functions, and C-h v only for variables, if you want to narrow it down.)

C-h m (‍describe-mode‍)

Describes the current Major Mode and its particular key bindings.

C-h r (info-emacs-manual)

Enters the Info hypertext documentation reader at the Emacs manual, which contains many hundreds of pages of documentation.

C-h p (‍finder-by-keyword‍)

Runs an interactive subject-oriented browser of installable Emacs packages⁶⁹. These lists of packages are actually presented by the package manager itself, so you can directly install packages from here.

C-h t (‍help-with-tutorial‍)

Run the Emacs tutorial. Have you done this yet?

There are 39 more help commands on C-h, which C-h C-h will reveal.

Of the commands I list above, C-h k, C-h o, C-h f, C-h v, C-h m (and a few of the other 39) bring up a Help Buffer. This is something of a simplification, but there are three main varieties of the Help Buffer:

• help for commands and functions, whether acquired via a keystroke or via a command name
• help for variables
• help for Modes

Let’s see what these are like.

Most of the Help commands described above answer specific questions about known items: what is this key? what does this function do? what kind of values can I set this variable to? The Apropos facility is how you search for unknown functions and variables related to what you want to do.

We’ve been introduced to the Apropos facility via C-h a above. This is M-x ‍apropos-command‍ which searches for commands by name. Command is the technical term for an interactive function: that is, a function you can call via a key binding or with M-x. The reason for making this distinction is purely practical. Emacs has tens of thousands of functions, most of which would only ever be called by an Emacs Lisp programmer. Commands are functions that are likely to be useful to the non-programmer (or to the programmer when she’s acting like a non-programmer).

If you’re interested in seeing non-command functions as well, you can give C-h a an argument (e.g. C-u C-h a).

Even more broad-minded is just plain M-x ‍apropos‍, which includes all functions, variables, and faces.

If you want to limit your search to variables, you can use M-x ‍apropos-variable‍. But there are other Apropos commands to make finer distinctions among variables:

M-x ‍apropos-user-option‍

only considers user-customizable variables (sometimes called options)

M-x ‍apropos-local-variable‍

only considers buffer-local variables defined in the current buffer

All of the above commands are only searching by function or variable name, to avoid overwhelming you. But you can include in your search all the text of the function’s or variable’s documentation with C-h d (‍apropos-documentation‍). This is just like C-h a but instead of limiting its search to the names of commands, it includes all symbols (like variables) and also searches the full text of the documentation of these symbols. This is a much broader search, and for reasons of both speed and concision, it limits the search to the standard built-in Emacs commands. If you give C-h d an argument, i.e., C-u C-h d, it searches the documentation of literally all symbols in your running Emacs, including those from third-party packages you may have loaded.

Finally, you can also search the values of variables with M-x ‍apropos-value‍. This is a pretty big search. My Emacs at the moment has 15,121 defined variables, and some of them have pretty big values.

The Help key has several additional subcommands that provide access to more information. Some of these are shortcuts into the Emacs or Elisp manuals in Info, but some are standalone files.

C-h C-a

Information about Emacs (recreates the splash screen you saw when you started up Emacs).

C-h C-c

Emacs copying permission (displays the complete text of the GNU General Public License, which gives you your freedom to copy, modify, and redistribute Emacs and its source code).

C-h C-d

Instructions for debugging GNU Emacs. This is for real hard-core programmers hacking on Emacs to fix deep bugs.

C-h C-e

External packages and information about Emacs.

C-h C-f

Emacs FAQ (the Frequently Asked Questions list).

C-h C-m

How to order printed Emacs manuals.

C-h C-n

News of recent Emacs changes; see Updates and Bugs.

C-h C-o

Emacs ordering and distribution information. This used to provide postal addresses you could write to in order to get copies of Emacs mailed to you on giant 9-track magnetic tapes to load on your mainframe! Nowadays, it just contains a few URLs and notes how you can make donations to the Free Software Foundation.

C-h C-p

Info about known Emacs problems. This is a broad summary of the standout Emacs bugs; the real bug list is available on the Web in the Bug Tracker, which is also available in Emacs via the debbugs package; see Reporting Bugs.

C-h C-t

Emacs TODO list. If you’re a Lisp or C programmer and want to contribute to the development of Emacs, you can start here.

C-h C-w

Information on absence of warranty for GNU Emacs.

Info documents wouldn’t be hypertexts if they didn’t have hyperlinks. These are exactly like the links in a web page and look similar: colorized and underlined. You can navigate from link to link in a node with TAB (S-TAB goes in reverse) and then follow a link by “clicking” on it (either with RET or the mouse). Info links can take you to other places within a node, to other nodes in the document, and also to nodes in other Info documents.⁷⁶ Links to places in the same page are formatted like footnotes.

You can also follow any of the links in the current node (even if you can’t see some of them) without navigating to them with f (‍Info-follow-reference‍), which prompts you for the text of the link. You can use Completion to complete any of the links in the node; note that Menu links and Footnote links are excluded from the Completion, because they have their own shortcut commands.

Many Info nodes have menus, especially in the first node of a document and in each chapter. Menus are nothing more than a list of hyperlinks and work the same way; it’s just a convention for organizing an Info document. Menus typically list all the children of a given node: that is, a chapter menu will list all the sections in that chapter, and a section menu all its subsections.

You can use Completion to select a Menu item by typing m (‍Info-menu‍), analogous to the f command for cross references, and the digit keys will jump directly to the node of the corresponding menu item: e.g., 3 would jump to the node named in the 3rd menu item and so on.

Since an Info node is just a buffer, you can obviously search within it with the usual search commands like C-s (‍isearch-forward‍), M-x ‍occur‍, and the like. Incremental search commands like C-s will beep when you get to the end of the node, but if you force the search with one more C-s then instead of wrapping to the beginning of the buffer, they will skip ahead to the next hit in the next node of the document.

In addition to full text searching, most Info documents are actually manually indexed by their authors, and everybody knows that a good index, what with synonyms, related terms, and inversion, can offer accessibility that full text searching can’t. In addition, an index allows for the possibility of Completion on index terms!

An Info document can have one or more indexes—Emacs-related documents will often have separate indexes of Key Bindings, User Options, Commands, Variables, and Concepts (the Emacs manual has all of these).

The index pages of a document are always listed at the end of the top-level menu of the document (its table of contents), but from any node the i (‍Info-index‍) command prompts you for an index term, with Completion, from any of the document’s indexes. Since a given term can point to any number of nodes, it will take you to the first occurrence, and if there are more, you might see a message like this in the Echo Area:

Found ‘INDEXTERM’ in Concept Index.  (20 total; use ‘,’ for next)

and indeed, the comma key will step you through all the hits.

Alternatively, you can instead use I (‍Info-virtual-index‍), which presents the same hits as i but lists them all in a dynamically-generated Menu.

You can also search across all sixty-plus Info documents at once with M-x ‍info-apropos‍, the search-engine of Info commands. It works like other Apropos commands but targets the text of the indexes of all installed Info files, and generates a dynamic Menu page from the hits.

You can jump directly to the top of the current Info document, with its master Menu table of contents, with t (‍Info-top-node‍), and the d (‍Info-directory‍) command goes to the Menu at the root of the entire Info system, listing all installed Info documents (the same place that C-h i takes you to).

If you are writing a book-length document, especially a manual for software, and very especially a new manual for an Emacs subsystem or Mode, you might consider using Texinfo format.⁷⁷ You’ll get many output options—PDF, HTML, DocBook, EPUB, and of course Info, which can be read in Emacs and even by non-Emacs users via the info command-line reader that’s standard on most Unix systems. And Emacs is of course especially suited for authoring with its Texinfo Mode; see Emacs For Writers for more information.

Various brief messages appear in the Echo Area from time to time. This includes error messages (like, trying to save a file that you don’t have permission to write), and also informational messages. Some commands exist only to print informational messages, such as C-x l (‍count-lines-page‍), which tells you how many lines there are in your buffer⁷⁸:

Page has 5549 lines (2407 + 3143)

If you miss a message like this, or if you want to make a copy of the message, you can use C-h e (‍view-echo-area-messages‍). This pops up the *Messages* buffer, which you can switch to for copies of the N most recent⁷⁹ Echo Area messages. It’s just a buffer like any other, so you can copy and paste from it.

There’s a separate buffer for warnings. Warnings are obviously like errors, but less severe. While errors go to the Echo Area, and behind the scenes are copied to the *Messages* buffer, warnings instead go to a separate *Warnings* buffer, and when a warning is generated this buffer pops up and is very noticeable. It seems counterintuitive that warnings should be more in-your-face than errors; I think the reason is two-fold: 1. the special handling of warnings is a relatively new feature, dating from about Emacs version 22; and 2. an error terminates whatever function raised it — it beeps, and you’ll look at the Echo Area — whereas a function that generates a warning will continue with what it was doing, but wants you to know something that you might need to act upon. There’s no special command to pop up the *Warnings* buffer; if you’ve deleted the window that popped up, and you want to reexamine it, you can just switch to it by name with C-x b (‍switch-to-buffer‍) (which you can also do to get to *Messages*).

Occasionally as you’re working, you might suddenly notice that something unexpected has happened — perhaps a chunk of text has disappeared before your eyes, or you’re suddenly in a completely different location! What happened?

Almost certainly this means you accidentally hit some unintended combination of keystrokes, and since so many such combinations are bound to commands, this means you inadvertently told Emacs to do something.

If a change to your text occurred, you can just Undo it and continue on. While you can’t Undo a location change, you can use the Mark Ring or the Global Mark Ring to return to where you were. But you might want to know what keystrokes and command you invoked so that you can avoid hitting it in the future — or perhaps you’ve discovered a new useful command to use intentionally!

The C-h l (‍view-lossage‍) command⁸⁰ pops up a Help Buffer showing the last 300 keystrokes you’ve typed. The lines look like this:

M->                           ;; end-of-buffer
q                             ;; quit-window
C-x b                         ;; switch-to-buffer
c                             ;; self-insert-command
o                             ;; self-insert-command

showing you the keystroke and the command name. You can ask for help for any of the command names (with C-h f (‍describe-function‍)) which can help you figure out what happened.

In addition to the special treatment of RET, the Minibuffer’s Major Mode provides convenient history commands. You can instantly recall your previous input — command name, filename, Buffer name… — with M-p (‍previous-history-element‍); subsequent M-p’s will go further back, and you can switch directions and go forward again with M-n (‍next-history-element‍) — the up- and down-arrow keys are synonyms. (Rather than navigating the history, C-p and C-n navigate multi-line input as in any Buffer — multiple lines, while atypical, are completely supported in the Minibuffer).

You can also search backward in the history with C-r (‍isearch-backward‍) or C-M-r (‍isearch-backward-regexp‍). You could, say, quickly pull up the last Org Mode file you edited with C-x C-f C-r .org, even if you last typed that filename days ago.

Note that any individual command can have its own distinct history list. This is typically done to tamp down the Completion possibilities for any given command to those that are most likely to be useful. Since the Minibuffer is used for all prompted inputs, if it only had one history list, then you’d have to wade through Buffer names, command names, color names, variable names — you get the idea — no matter what you were about to enter.

Instead, all the file-visiting commands, like C-x C-f, share a single history list which only contains filenames; likewise for C-x b and Buffer names, M-x and command names, etc.

One of the lesser-known features of the Minibuffer⁸³ is that its history extends into the future: that is, Emacs can predict inputs that you haven’t typed yet! More prosaically, you could call these predictions, defaults. You access these defaults with M-n (‍next-history-element‍) — use it immediately after you’ve been prompted for input by some command and it’ll offer up suggestions: if you’re at the end of the history, the next history element is from the future!

For example, after C-x b (‍switch-to-buffer‍), M-n will offer up names of Buffers that you’ve recently visited (even if you haven’t ever explicitly input their names). C-x C-f will do something similar, but in addition, if, before you invoked C-x C-f, Point happened to be in the name of an existing file, it will offer up that filename. Sometimes the things M-n comes up with can seem telepathic. (The flip side is that sometimes it won’t have any guesses for you.)

The Minibuffer is the sole, unified way to get prompted input, and you can use any commands you like when you’re entering text there. So what happens if you type M-x ‍eww‍ to pull up a web page in the Emacs web browser. Eww is now using the Minibuffer to read a URL, prompting you with:

Enter URL or keywords:

Then you realize you don’t remember the precise URL you need, but you know it’s in a file. So you naturally type C-x C-f (‍find-file‍) so you can observe and copy that URL.

But no! Emacs will beep at you and refuse to execute C-x C-f, saying:

Command attempted to use minibuffer while in minibuffer

That is, you’re in the Minibuffer (entering a URL) but C-x C-f now needs to use the Minibuffer to read a filename!

This is not really a limitation of Emacs, which actually has no problem allowing you to invoke the Minibuffer recursively to any (reasonable) depth. However, this feature is disabled by default — because it’s been found to confuse Emacs newbies.

But this many pages into this book, you’re no longer a newbie! While my example may be somewhat contrived, recursive Minibuffers are very useful and you’ll probably want them several times in a day. I recommend turning them on with this snippet of code in your init file:

(setq enable-recursive-minibuffers t)

If you recursively invoke a Minibuffer and change your mind about it, just hit C-g (‍keyboard-quit‍) as usual; it will abort the most recent Minibuffer and you’ll be back in the previous one and can complete your input there as you like.

When you’re entering information in the Minibuffer, you may occasionally realize that you don’t actually know what you need to type, as in our URL example. You have to check something first.

The normal procedure is just to use C-g (‍keyboard-quit‍) to cancel the command that’s using the Minibuffer, do your investigation, and then reissue the command. How very modal of you.

But you can instead just temporarily switch out of the Minibuffer with any command that switches Windows. Normally that would be C-x o (‍other-window‍) but any Window-changing command, or clicking in another Window with the mouse, is fine.

Now you’re in one of your “normal” Windows, and the Echo Area, instead of being blank, as usual, still contains the Minibuffer prompt and whatever else was displayed there when you jumped out: the Minibuffer is frozen the way you left it, waiting for you to return and finish what you were doing. In a graphical mode Emacs, you’ll notice that the Minibuffer cursor has changed from a solid rectangle to a hollow one.

While you’re away, you can do anything you like: continue editing, play a game with M-x ‍tetris‍, copy some text you need for the Minibuffer: you can even, of course, use a command that uses the Minibuffer!⁸⁴ You can stay away as long as you like. When you’re ready to get back to where you left off, just navigate to the Minibuffer (again, C-x o or a mouse click is the most natural), and complete your action, perhaps yanking in some text you copied for the purpose. Hit RET to execute the patient, long-suffering command-in-progress, and you’ll be returned to wherever you were when you started this excursion — the Window layout and your Buffer position will be restored as they were, even if, during your excursion, you changed Windows around radically. This is the essence of non-modal editing!

Among people who use Emacs mostly as a text editor, the Minibuffer is probably most heavily used to input file names, followed by Buffer names. But as you use Emacs for more things, the use of the Minibuffer to enter command names with M-x (‍execute-extended-command‍) probably dominates. So Emacs provides special history support for these.

We know that if you type M-x you can retrieve previous commands from the history with M-p, C-r, and M-r, but some commands have multi-part inputs. Consider M-x ‍rgrep‍ (see Meet the Greps). It’s nice that the Minibuffer history helps you avoid typing all five characters of “rgrep” to run a new Rgrep, but what if you want to rerun a previous Rgrep exactly?

M-x ‍rgrep‍ prompts you for three things: a search term or regular expression, a file type wildcard pattern (e.g., *.org), and a base directory from which to start the search. You can use the history commands at each of these prompts, but that can be a little tedious if you just want to rerun the command exactly: M-x M-p RET M-p RET M-p RET M-p RET.

Instead, you can use C-x ESC ESC (‍repeat-complex-command‍). You get a Minibuffer prompt showing your previous M-x command, in its true Elisp form; it might look like this:

Redo: (rgrep "minibuffer" "*.org" "~/txt/" nil)

Even if you’re not an Elisp programmer (yet), this should be recognizable as your grep for the string “minibuffer” in Org Mode files contained (recursively) in ~/txt/; just hit RET to re-run it, with no need to reenter the three parameters. You can edit the command beforehand (perhaps to tweak the regexp, or the file type, or the base directory)⁸⁵.

You can use the Minibuffer history (M-p, C-r, M-r) as usual here to choose a different prior command. Note that the history includes any command that used the Minibuffer, even if you invoked it via a key binding, so you’ll find old friends like C-x C-f (‍find-file‍) and C-x b (‍switch-to-buffer‍) here as well.

You can view a Buffer of the N most recent⁸⁶ M-x commands with M-x ‍list-command-history‍. The commands are in their true Elisp form, as for C-x ESC ESC, one per line. In this Buffer you can re-run the command at Point by typing x ( command-history-repeat).

Since the default command history list is so short, and since I think RET in this Buffer should execute the command at Point, I recommend this snippet for your init file:

(with-eval-after-load 'chistory
  (setq list-command-history-max 120)
  (define-key command-history-map (kbd "<return>") 'command-history-repeat))

Note that alternative Completion frameworks, and Incremental Narrowing Frameworks in particular, may radically alter the nature of the Minibuffer, making it seem less like a normal buffer, and some of the things described in this chapter may not work precisely the same way.

Emacs has a number of ways of performing completion that I’ll call completion frameworks. The default framework is roughly the way completion has always worked since about 1985, but you definitely want to use a more modern framework of the type known as incremental narrowing. Even here, Emacs has more than one choice.

I’m going to recommend you start right off with Vertico⁸⁹, which you can install from the GNU ELPA Package Repository; see Figure 9.

You’ll need to add this to your Init File and restart your Emacs⁹⁰:

(setq completion-styles '(partial-completion substring flex))
(unless (package-installed-p 'vertico)
  (with-demoted-errors "%s"
    (unless package-archive-contents
      (package-refresh-contents))
    (package-install 'vertico)))
(with-demoted-errors "%s" (vertico-mode +1))

An incremental narrowing framework (INF) generally lets you complete a string (whether a M-x command name, file name, buffer name, or anything else) by typing a pattern consisting of clusters of adjacent letters separated by punctuation. So to complete the command ‍switch-to-buffer‍, you can type sw-to-bu which rapidly narrows the matches down from 20,525 possible commands to a mere 7.

The entire line of one of the matches will be highlighted; this is the match that will be used if you hit RET. If switch-to-buffer is not highlighted yet, you’ll need to either narrow it down further, by adding more letters, or, when the number of matches is small enough, just navigate to it with C-n or the down-arrow key.

If there are more than the default 10 matches, you can scroll through them until you spot the one you want, or edit your pattern (with the usual Minibuffer editing commands) to narrow it down further. The usual Minibuffer history commands work as well. See Table 3.

When your target is properly highlighted, you’re done. Hit RET to select it. If you’re completing a M-x command, the command will be executed. However, if you’re entering a filename for, say, ‍find-file‍ or a buffer name for ‍switch-to-buffer‍, you may be intentionally typing a nonexistent name, to create a new file or buffer, which therefore can’t possibly have a match! In this case, you use C-RET to select not the highlighted match, but the exact text you’ve typed, as is.

Vertico is designed to be enhanced and customized via a set of complementary packages. I also recommend installing Marginalia, which provides annotations in the Minibuffer adjacent to command names, file names, buffer names, and more.

(unless (package-installed-p 'marginalia)
  (with-demoted-errors "%s"
    (unless package-archive-contents
      (package-refresh-contents))
    (package-install 'marginalia)))
(with-demoted-errors "%s" (marginalia-mode +1))

Now M-x sw-to looks like Figure 10 and C-x C-f looks like Figure 11:

I think Vertico is one of the best INFs, but Emacs has a few other built-in INFs to choose from, and more in the Package Manager. The built-in INFs are Icomplete ( M-x ‍icomplete-mode‍), Ido ( M-x ido-mode) (“Incremental Do”: see the Ido manual) and Fido ( M-x ‍fido-mode‍). Unlike most modern INFs, their interface is horizontal. When you hit M-x, you’ll see something like this:

M-x {execute-extended-command | enable-theme | dired-at-point | …}

You navigate through the matches with the left- and right-arrow keys. (I’m showing an abbreviated version; you’ll typically see half-a-dozen candidates, possibly spread across at most two minibuffer lines.) Note that you don’t need to hit TAB to see these candidates: that’s a big part of what makes an INF more efficient. These will narrow as you type.

They all work together, and if you want to use them, you should probably turn all three of them on in your Init File:

(icomplete-mode 1)
(ido-mode 1)
(fido-mode 1)

Most modern INFs have chosen, like Vertico, to go for a vertical presentation of the candidates, using a multiple-line expanding Minibuffer; this gives more room for long command and file names, and in some frameworks, useful extra information like that provided by Marginalia.

The other vertical INF in the GNU package repository is Ivy; it has more built-in features, which are quite powerful, but due to its complexity, it may not interact as well with some Emacs subsystems. (Vertico aims for 100% compatibility and comes very close by being simple.)

In this chapter, we’ve discussed completion in the Minibuffer, but Emacs also does completion in normal buffers. It comes in two flavors: explicitly-activated completion at Point, and implicitly-activated completion via a popup menu.

For the former, when you’re half-finished typing a word, you hit M-/ (‍dabbrev-expand‍), and Emacs completes the word for you. This an amazing feature and an essential skill to pickup; see Completion at Point.

For the latter, you can arrange to have a (lightweight, non-GUI, plain-text) menu pop up as you’re typing, showing you possible completions, any of which you can select by quickly navigating to it with the arrow keys. This popup completion isn’t typically enabled for ordinary words in prose, but rather in buffers whose Major Mode usefully limits the candidates. In particular, in programming language modes, where library functions and symbols in the buffer are presented. See Pop-up Menu Completion.

• Free Software Foundation. 2020. Interactive Do. Cambridge, MA: Free Software Foundation. https://www.gnu.org/software/emacs/manual/ido.html. Read in Emacs with M-x info-display-manual RET ido RET.

• [Krehel, Oleh]. n.d. Ivy User Manual. https://oremacs.com/swiper/. Read in Emacs with M-x info-display-manual RET ivy RET.

Lines are the fundamental unit of organization for most (but not all) text. Text consists of a sequence of lines, and lines are separated by end-of-line characters.⁹⁵ We usually loosely call the end-of-line character a newline (but see International Character Set Support for the gnarly details). You can enter a newline, and thus begin a new line, by hitting the key Emacs calls RET or <return>, which on your keyboard might also be labeled ENTER.

The end of a line at the very end of a Buffer is somewhat ambiguous⁹⁶. Suppose we have a Buffer whose text consists of “foo”, a newline, and “bar”; that’s 7 characters, but how many lines is it? In your Buffer it looks like:

foo
bar

and to me, that’s unquestionably two lines. Emacs agrees. C-x l (‍count-lines-page‍) reports:

Page has 2 lines (0 + 2)

and — further confirmation — if we invoke M-x linum-mode, the buffer looks like:

1 foo
2 bar

But there’s no newline after “bar”! If we add one, the buffer looks the same, and C-x l and linum-mode both still report two lines. In other words, the number of lines is not necessarily exactly the same as the number of newline characters.

Unfortunately, this ambiguity is simply a fact of computing life. The good news is, 1. it doesn’t usually cause any problems, and 2. Emacs has extensive facilities for dealing with it; see Manipulating Plain Text for details.

When Emacs was fresh and new in the 1970s, people entering prose text would typically hit RET after typing 72 characters or so, and almost always before 80.⁹⁷ Paragraphs were typically separated by an empty or blank line (i.e., a line consisting solely of a newline, or possibly a sequence of whitespace characters followed by a newline), or by a line with leading indentation (i.e., a few spaces), or both: exactly how you’d type it on a typewriter. Emacs’s Text Mode (see “Text Mode” in the Emacs manual) is designed for this kind of prose text and has support for automatic wrapping, indenting, and filling of paragraphs.

But there’s no limit to the length of a text line, and in fact in the modern world, the current convention is that each line of typed text is in fact an entire paragraph, and paragraphs therefore no longer even need to be separated by blank lines (though they may be). This convention arose with GUI applications, whose windows weren’t limited to 80 column lines and whose widths could be resized at will: single-line paragraphs auto-fill as the screen is resized, but multi-line paragraphs do not. Emacs of course supports this convention but it’s not the default, primarily because Emacs was written by and for programmers, and both computer programs and computer data files are typically expressed as lines with explicit newlines, and the lines may have semantic significance.

For details on how long lines are displayed and what you can do to change it, see The Display of Lines.

There’s no law that says text can’t include non-printing characters, like, say, a C-a (which is ASCII 1 decimal). If a file contains only printing characters, it clearly deserves the label “text”; if it contains none, it clearly doesn’t and instead we call it binary data. But in between, the label is a judgment call. Regardless, Emacs needs to show you non-printing characters when they occur.

(I’m afraid this section has to be very nerdy; none of this will surprise a programmer, but the explanation of it all involves the distant history of computing, computing Standards (gulp), and a variety of number bases. Feel free to skip ahead!)

When one of the ASCII control characters—those in the range decimal 0–31⁹⁸—occurs in a Buffer, Emacs displays it specially, using the traditional programmer’s notation for control characters: a circumflex followed by an uppercase letter (or punctuation mark in six cases), for example ^A, which is the same character that Emacs refers to as C-a. Table 4 shows these in the “Control” column.

Thus, in your Buffer, a single control character displays as a pair of characters. This is ambiguous: is that ^A one character, ASCII decimal 1 aka SOH, or is it the two printing characters, ^ followed by A? There are two ways tell:

1. by movement: your cursor will skip over a control character with a single C-f (‍forward-char‍), where it would take two C-f’s to move over the pair of printing characters;
2. by color: the control characters are colored differently than the printing characters; if your Buffer text is black-on-white, the control characters will be red e.g. ^A; if your Buffer text is white-on-black⁹⁹, the control characters will be cyan e.g. ^A.

There are other characters, which are tricky to classify as printing or non-printing, that aren’t part of the original ASCII character set: they would occupy the slots from 128–255 decimal in an expanded table. If these characters appear in a Buffer (one using the binary Coding System), they are represented as a backslash followed by a three-digit number e.g. \304.¹⁰⁰ Again, your cursor will move over such a character in one step, and they’re colored the same as the control characters.

If you’re curious and want to see some of these non-printing characters in a Buffer, you can just visit a native-code executable file on your computer.¹⁰¹ But what if you need to insert one? Obviously you can’t insert a ^A by typing C-a—that will just move your cursor to the beginning of the line!

The basic command for this is C-q (‍quoted-insert‍). Inserting a control character is easy: to insert a ^A, just type C-q C-a. You can also needlessly quote printing characters—say, C-q A—which just inserts the printing character normally.

What if you want to insert “international”, non-Latin, characters from Unicode, or you want to type fancy glyphs like Æ, or ¶? See International Character Set Support for details.

To switch Buffers means, specifically, to change which Buffer is displayed in a given Window. The basic command to do this is C-x b (‍switch-to-buffer‍); it displays a different Buffer in the current Window, prompting for the new Buffer by name, using Completion. You can also use one of these variant versions:

C-x 4 b (‍switch-to-buffer-other-window‍)

Switch to a different Buffer not in this Window, but in the “other” Window.¹⁰³

C-x 5 b (‍switch-to-buffer-other-frame‍)

Switch to a different Buffer not in this Frame, but in another Frame; if the Buffer is already displayed in a Window in another Frame, switch to that Frame and Window; if not, a brand new Frame is created and the Buffer is displayed in the Window in that Frame.

You can also switch quickly to Buffers you’ve recently used without specifying their names. Emacs maintains its list of Buffers in a ring in recency order.

C-x <C-left> (‍previous-buffer‍)

switch to the previous Buffer you were in (in this Frame); repeating this command goes further back in the Buffer-recency timeline

C-x <C-right> (‍next-buffer‍)

the same, but go forward in timeline order.

(You can also use the less felicitous bindings C-x <left> and C-x <right>.)

The User Option switch-to-prev-buffer-skip allows you to customize which Buffers these two commands consider to be candidates.

The Global Mark Ring provides another way of switching Buffers: C-x C-SPC (‍pop-global-mark‍) will jump to previous Mark locations in other Buffers.

Outside of Emacs, Tabs (not to be confused with the ASCII TAB character nor with tab stops) are a pervasive graphical user interface design element for navigating between multiple “objects” in an application: whether web pages, word processor documents, desktop windows, or whatever. The objects being the subject matter of the application, they would correspond to Buffers in Emacs. Yet Emacs hasn’t had Tabs until quite recently¹⁰⁴: Completion and the Buffer Menus have sufficed for Emacs users for decades.

But now you can turn on the Tab Line. The Tab Line is a per-Window construct: a special sticky line of tabs at the top of your Window, each tab shows the name of a Buffer that has been displayed in this particular Window.¹⁰⁵ There’s also a +-sign at the right that, when clicked, pops up a classified GUI menu that allows you to switch to any other Buffer, thus adding another tab to the bar.

This is obviously a feature for mouse users, but if you’re a keyboard-only person like me, I suppose you might still want the Tab Line for its visuals. Note that the Buffers shown in the Tab Line are the same ones you can navigate through with C-x <C-left> (‍previous-buffer‍) and C-x <C-right> (‍next-buffer‍).

You can turn the Tab Line on for any Window with M-x tab-line-mode. If you want this for all your Windows, say M-x ‍global-tab-line-mode‍; you can make this your default by adding this to your Init File:

(global-tab-line-mode 1)

The Package Manager is full of third-party packages for selecting Buffers; pretty much any approach any other program or operating system has used for something similar can be found as an Emacs package: from a very visual Mac Os Exposé-like switcher, to my favorite, the very abstract buffer-stack.

Buffers are typically created for you, implicitly, by any number of commands: the file visiting commands, of course, but also by many of the thousands of other commands: the Help commands create *Help* Buffers, for example, and any of the Emacs “applications” like the File Manager (Dired) or the Web Browser (Eww) create Buffers to present their user interfaces. Buffers are used for almost everything in Emacs, and you won’t even be aware of most of them; I have 175 in my Emacs as I write this.

You can also just create a new Buffer anytime you want. The command for this is good old C-x b (‍switch-to-buffer‍); typically, this command is used to display a different, existing, Buffer in the current Window, as described in the previous section. But when ‍switch-to-buffer‍ prompts you for the Buffer name, if you enter a new, non-existent, one, it instead creates a brand new, empty, Buffer. This Buffer will be in fundamental-mode unless your chosen name looks like a filename with an extension (say, foo.org), in which case the Major Mode will be determined as described in How a Mode Happens to Your File. Regardless, there will be no file associated with this new Buffer.

When you exit, Emacs will offer to save modified Buffers that are visiting files, so that you don’t lose your work. But non-file Buffers don’t get this treatment, no matter how much work you may have done in them!¹⁰⁶ You can always use C-x C-w (‍write-file‍) to associate a file with such a Buffer after the fact.

It may be tempting to create new non-file Buffers or use the *scratch* Buffer just to take some transient notes, but such notes have a way of surreptitiously becoming important, and you will lose them if you exit without saving them somewhere. Emacs has better ways for you to take notes.

This inspires me to mention the fact that every Buffer has a name. There are no anonymous Buffers. Not only must every Buffer have a name, but that name must also be unique. When there are natural name conflicts, Emacs will usually disambiguate the newer Buffer name for you. Buffers that aren’t visiting a file typically get numeric suffixes, like *shell*<2> and *shell*<3>, but for files things are more interesting.

The name of a Buffer that’s visiting a file is typically the basename of that file; for example, if you visit /etc/passwd, the Buffer will be named passwd. Since there could be any number of files named passwd in various directories, in order for you to be able to visit more than one of them, Emacs must uniquify the Buffer name. You can choose from a variety of uniquification algorithms. Using the default algorithm, if you visit /tmp/passwd, having already visited /etc/passwd, the new Buffer will be named passwd</tmp>. See “Uniquify” in the Emacs manual for details.

You can rename Buffers at will with C-x x r (‍rename-buffer‍). Since some applications manage their Buffers by name, renaming them might break the app! But many, probably most, Buffers are perfectly safe to rename. While uncommon, you can rename any file-visiting Buffer; the Buffer name won’t affect the filename. It’s quite common to rename the Buffers of commands that re-use the same name. Although ‍help-mode‍ has commands to navigate back and forth through your history of Help invocations, you might want to rename a given *Help* Buffer to keep it around and easily accessible.

M-x ‍shell‍ is the opposite: when you run it, if that Buffer already exists, it simply switches to it (kind of like C-x C-f (‍find-file‍); if you want a second shell, you can first rename the existing Shell Buffer to whatever you like.¹⁰⁷ M-x ‍rename-uniquely‍ will automatically rename any Buffer for you, using a numeric suffix.

In addition to a name, every Buffer has a default directory. This is analogous to the working directory of a process in Unix. The default directory of a file-visiting Buffer is the directory where the file was located. If you’re in a shell in a terminal, and you give a filename to some command via a relative path, that filename is interpreted relative to the shell’s current working directory: Emacs works the same way. If a command prompts you for a filename, the prompt will be preset to contain the Buffer’s default directory; you can delete or edit it to name a file in some other directory, of course, but if you completely delete any directory and just enter a relative path, it will be taken as relative to the default directory.

If you create a non-file Buffer, its default directory will generally be inherited from the Buffer you were in when you created it. But any Emacs command that creates a Buffer is free to set its default directory to whatever is appropriate.

The default directory is just a buffer-local variable named default-directory. You can check what it is with M-x ‍pwd‍, which prints the value of this variable in the Echo Area,¹⁰⁸ and you can change a Buffer’s default directory with M-x ‍cd‍, which sets the variable to whatever directory you specify. Note that changing the default directory of a file-visiting Buffer does not change the directory of the file you’re editing—not even if you re-save the Buffer. It only affects prompt defaults and the resolution of relative pathnames you give to commands while you’re in that Buffer. To change the directory of a file you’re editing, use M-x ‍rename-file‍ or C-x C-w (which is equivalent to making a new copy of the file).

File-visiting Buffers can be reverted with M-x ‍revert-buffer‍ or C-x x g (‍revert-buffer-quick‍) to make the text in the Buffer match the text in its file. There are two major reasons for doing this: either to throw away all the unsaved modifications you’ve made without undergoing a tedious sequence of Undos (and restore the Buffer’s text to what’s in the file), or because the file has been changed behind Emacs’s back by some other process and you want the Buffer to reflect this. See Files: Reverting Buffers, Auto-Reverting (Watching Files), and Files Modified Behind Emacs’s Back for more information.

Many non-file Buffers implementing Emacs applications can also be reverted; the exact meaning of “revert” in these Buffers depends on the application. For example, C-x C-b (‍list-buffers‍) pops up a Buffer containing a list of all your Buffers (see Buffer Menus), but if a new Buffer is created later, the list won’t (for good reasons, IMHO¹⁰⁹) be automatically updated to show it; reverting the Buffer will do so. In Major Modes descended from Special Mode, the key g is often bound to ‍revert-buffer‍, but check with C-h m (‍describe-mode‍) first.

There are many ways to delete or, as we say in Emacs, kill Buffers, but why would you want to? There are two main reasons:

• Each Buffer takes up in memory at least as much space as the file takes up on disk; when you kill a Buffer, you free up that space and Emacs has that much more to work with.¹¹⁰
• Lots of old Buffers means clutter; more Buffers to ignore in Buffer listings, more to ignore when doing Buffer-name completion, more Buffers to search through if you ask Emacs to do so. If you run Emacs as a long-running process in Server Mode (as I recommend), you might accumulate many Buffers over the space of weeks or even months!¹¹¹

We’ve already seen the basic command for killing a single Buffer, by name and with completion: C-x k (‍kill-buffer‍); C-x 4 0 (‍kill-buffer-and-window‍) kills the current Buffer and also deletes the Window that was displaying it; it’s especially useful when popping up hits from a Grep command. There are also several commands to clean up unneeded Buffers:

M-x ‍kill-some-buffers‍

asks whether or not to kill each Buffer in your Emacs; it makes it clear whether or not the Buffer is modified. This command is way too tedious unless you have hardly any Buffers, and if you have a lot, a sort of highway hypnosis can set in that might result in you killing a Buffer you didn’t want to.

M-x ‍kill-matching-buffers‍

This command prompts for a Regular Expression and only asks about the Buffers whose names match it, so this might be a little bit better.

M-x ‍clean-buffer-list‍

is a totally automatic way to clean up a lot of Buffers, with no prompting and no questions asked. It will of course never kill a modified Buffer, but it will instantly get rid of Buffers that you haven’t looked at in a while (by default, 3 days). It’s highly customizable, so you can define certain Buffers that it should never clean up; examine M-x customize-group RET midnight RET. See also Midnight Mode.

I think the best thoughtful (i.e. not totally automatic) way of cleaning up Buffers is via one of the Buffer Menu commands below, which give you a Dired-like interface to the task.

C-x <C-left> (‍previous-buffer‍) and C-x <C-right> (‍next-buffer‍), along with C-x b (‍switch-to-buffer‍) (coupled with a good Completion framework) will form the vanguard of your Buffer navigation. But sometimes you’ll need a way to get an overview of all your Buffers, and some tools to manage them. This is what the Buffer Menus provide. A Buffer Menu is to Buffers what Dired is to files.

There are three main choices: ‍list-buffers‍, ‍bs-show‍, and ‍ibuffer‍.

The most basic command is C-x C-b (‍list-buffers‍); it pops up a *Buffer List* Buffer that lists all the Buffers in your emacs, giving, along with their names, their sizes, Major Modes, and visited file name (if any):

CRM Buffer         Size  Mode              File
.%  passwd          1699 Conf[Colon]      /etc/passwd
 %  *Calendar*       531 Calendar
 %  *Help*           554 Help
    *scratch*        145 Lisp Interaction
 %* *Messages*       305 Messages

The cryptic CRM Column shows the current Buffer (indicated by a period in the C column), a % under R if the Buffer is read-only, and a * under M if the Buffer is modified.

This Buffer is in ‍buffer-menu-mode‍, and if you switch into it, a number of Buffer-management commands are available. Just move to anywhere within a Buffer’s line and the special commands will operate on that Buffer. Some operate immediately, but some only mark the Buffers and perform the operation when indicated. See table 5.

‍bs-show‍ is very similar to ‍list-buffers‍; it has a very similar command set¹¹², but is more customizable and, in its default configuration, is a bit more colorful. I’d recommend it over list-buffers just for that reason; you can bind it to C-x C-b with:

(global-set-key (kbd "C-x C-b") 'bs-show)

The Buffer Menu that I use is ‍ibuffer‍. It’s even more colorful than bs-show, but it has the largest command set and is more like Dired than the other two.¹¹³ It has a more extensive set of marking commands, a much larger, stackable, set of commands to filter the Buffer Menu (e.g., by Major Mode, by visited directory name, by size), and a much larger set of sorting commands. It has so many commands that I won’t attempt to summarize them here; say C-h f ibuffer-mode.

I recommend it, and I bind it to C-x C-b with:

(global-set-key (kbd "C-x C-b") 'ibuffer)

Note that neither list-buffers nor bs-show will list hidden Buffers (those starting with a space). ibuffer can do this, however.

Many commands that perform repetitive operations (like Query Replace) will limit their operation to the active region. Some (like Keyboard Macros) do not, but these recalcitrant commands can be convinced to do so by narrowing the Buffer to the Region (whether active or not). C-x n n (‍narrow-to-region‍) hides the parts of the Buffer outside the region, making them almost completely inaccessible. After narrowing, you can run any command on the entire Buffer without worrying that it will affect the hidden parts. Narrowing can also be useful just to focus your attention on a part of your text, say a particular paragraph, or a gnarly function, with no distractions.

Once you’ve narrowed, it’s as if the rest of the Buffer is gone. The Buffer size indicator in the Mode Line will report the size of the narrowed portion as if it’s the entire Buffer, and any displayed line numbers will be reset from 1. If you save a narrowed file-visiting Buffer, you will always save the entire Buffer, including the invisible parts—don’t worry that you might lose data by saving only the narrowed part to the file!

The Mode Line will include the word “Narrow” in the parenthesized list of Minor Modes (even though narrowing isn’t, strictly speaking, a Minor Mode). There are a few other giveaways. The value of Point, which you’ll recall is the offset, in characters, from the beginning of the Buffer, remains relative to the entire unnarrowed Buffer. One command that reveals the value of Point is C-x = (‍what-cursor-position‍). Suppose you narrow your 500K Buffer to one paragraph in the middle of the text; what-cursor-position will show that Point is something like 254,120 rather than 1. Go ahead and try it!

But wait, first I’d better tell you how to restore your Buffer after narrowing it! C-x n w (‍widen‍) does the job. Point remains where it was, and all the hidden parts blossom forth again.

If someone new to Emacs accidentally narrows a Buffer, the usual assumption is that, somehow, much text has mysteriously been lost, and the reaction is dismay. For this reason, C-x n n (‍narrow-to-region‍) is disabled by default. But it’s a very useful command, and I recommend you enable it after you’ve tried it a couple of times.

When you visit a file, Emacs chooses a Major Mode for you automatically, typically based on a file extension. Files ending in .org will automatically be in org-mode; files ending in .py will automatically be in python-mode.

But Major Mode selection is really more complex. Emacs has a decision tree that proceeds from the file contents, through the file name, to your chosen overall default. Here’s the complete sequence.

You can always set the Major Mode of a Buffer explicitly, either because the usual process came up with fundamental-mode, or chose the wrong Mode (perhaps due to an unusual or nonexistent file extension), or just because you prefer an alternative Mode at the moment.

Conventionally, Major Modes exist as commands named according to the pattern major-mode-name-mode, so you can switch to Org Mode by invoking M-x ‍org-mode‍ or to Emacs Lisp Mode with M-x ‍emacs-lisp-mode‍. After switching, there might be a visual change as the new Mode’s syntax colorization takes effect; for example, after switching to fundamental-mode, any colorization will disappear, since fundamental-mode doesn’t do any syntax highlighting (this is one of the most common manual Mode changes, because since fundamental-mode does nothing visually to the characters in the file, you can be sure you’re seeing the precise contents).

To restore Emacs’s choice of Mode, you could reinvoke the Mode’s function by name, but the simplest way is to say M-x ‍normal-mode‍. normal-mode is not a Major Mode, but rather just a function that instructs Emacs to go through the entire Major Mode-choosing process again.

If you want to know what’s up with the Major Mode Emacs has chosen, just say C-h m (‍describe-mode‍). The *Help* Buffer will first list all the enabled Minor Modes (because Major Modes often turn on a set of Minor Modes); these are hyperlinked to complete descriptions later in the Buffer. Then the documentation for the Major Mode will be presented (for some Modes, this is quite extensive), and then typically a complete list of Major Mode-specific key bindings will be given (there might only be a couple; for some Modes, like ‍org-mode‍, there might be several hundred!). Finally the documentation and key bindings for all the Minor Modes will be given. This can be a lot of documentation; for me, the Org Mode *Help* Buffer is over 900 lines long!

It’s very common to want to customize the way a Major Mode¹¹⁷ works, and well-written Major Modes (the majority of them!) provide many ways to do so. You might want to change the default indentation level or the color of comments or string literals in a programming language Mode. You might want to change some of its key bindings to ones that are more mnemonic or easier to type. You might want to disable an annoying command that you find yourself accidentally invoking (I do a lot of this!).

The simplest type of customization is to modify the value of a user option, i.e. an Emacs variable that’s explicitly intended to be used to tweak a Mode’s behavior. The easiest way to do this is to go to a Buffer that has the Major Mode you’re wanting to tweak and invoke M-x customize-mode; this gathers all of the Mode’s user options together and you can use the Customize facility to change them. You can also just set these options in your Init File via Elisp, e.g.:

(setq python-indent-offset 2)

see User Options. How do you find out what user options exist to be customized? Browsing the customize-mode Buffer is a good way; you can also use M-x ‍apropos-user-option‍ with a query like python indent, and don’t forget to read the Info manual for Modes which have one.

Customize doesn’t give you a way to change key bindings, so you’ll need to hack your Init File to do that! See Modifying Key Bindings for instructions.

Finally, you may want to customize a Mode in a manner that never occurred to the programmer who wrote the Mode, and so there’s no handy user variable to tweak. A common desire is to turn on several specific Minor Modes whenever you’re in a given Major Mode: for example, spell checking. But that’s just one of any number of possible Minor Modes. The programmer of the Foo Major Mode shouldn’t try to provide user options like foo-enable-spellcheck because even though spell checking is a common desire, there’s more than one way the user might want to do it, and more to the point, there is an unlimited number of extant and not-yet-written potential Minor Modes of interest. And you may want to enable a behavior that’s not even a formal Minor Mode¹¹⁸.

Fortunately, Emacs has a general purpose mechanism to solve this problem; it’s pervasive and part of what makes Emacs so malleable: Hooks. Hooks exist to provide a way for an action of some kind to also perform some other arbitrary actions at your behest. Every Major and Minor Mode FOO-mode respects a variable FOO-mode-hook which is intended to contain a list of functions. Each function in this list is executed, in order, after the Mode is done initializing the Buffer. You simply add functions to this list; the functions can do whatever you want.

So, if you want spell checking in Org Mode, and you prefer ‍flyspell-mode‍ to ispell-minor-mode, you can add this line to your Init File:

(add-hook 'org-mode-hook 'flyspell-mode)

If you don’t generally want line numbers turned on, but you do want them in python-mode, add this line:

(add-hook 'python-mode-hook 'linum-mode)

As the name implies, the ‍add-hook‍ function adds an additional function to a hook variable, at the front of the list. add-hook is clever and only adds the function if it isn’t already present (that way it doesn’t run twice).

flyspell-mode and linum-mode are both Minor Modes, and Minor Modes are designed to be easy to add to hooks. But you can add arbitrary functions as long as they make sense. Want to give yourself a little encouragement whenever you open an Elisp Buffer?

(add-hook 'emacs-lisp-mode-hook
  (lambda () (message "Don't fear the parentheses!")))

More complex Modes will define more than just the default after-Mode-initialization hook, and will run these hooks when certain actions occur. org-mode, for example, an especially complex Major Mode, has 80 hooks.

Hooks are not really just for Modes. There are many defined for Emacs actions that occur “globally” — hooks for when Emacs starts up and when it exits, for example — and individual functions defined outside of any major Mode can have their own hooks so that you can customize their behavior.

Almost all Major Modes are derived from some preexisting Mode that’s in some way similar. This way, the new Mode inherits behavior from the parent (which may have inherited behavior from its parent, and so on). The new Mode inherits the parent’s keybindings, syntax table, abbreviations, and Major Mode hook, and can then change anything it’s inherited, or not. Note that the new Mode’s hook will run after all the inherited Mode hooks. So if someone invents a new variant of the Lisp programming language, say “Neolisp”, a new Emacs neolisp-mode might well be derived from lisp-mode.

There are five Major Modes that are commonly used as parent Modes: ‍text-mode‍, for a new Mode that deals with something similar to natural-language prose; prog-mode, for new programming language Modes; special-mode, for Modes that let you view data more than they let you edit it (this includes most applications); tabulated-list-mode, for Modes that present a view of data in sortable columns (and which is itself derived from special-mode); and finally, fundamental-mode, the most minimal Mode of all. Note that prog-mode, special-mode, and tabulated-list-mode exist only to be derived from, whereas text-mode and fundamental-mode are themselves often used as Major Modes.

Here are a few basic Major Modes that can be useful when Emacs doesn’t have a better idea for your text.

As of version 28.2, Emacs ships with Major Modes for at least Ada, Assembly Language, AWK, C, C++, Common Lisp, Emacs Lisp, Fortran, Icon, Java, Javascript, M4, Makefiles, Metafont, Modula2, Object Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Scheme, Shell (Bourne-, C-shell-, and rc-derived flavors), Simula, SQL, Tcl, Verilog, and VHDL.

In such a Mode, Emacs does all the sorts of things you expect of an integrated development environment (IDE): syntax highlighting to colorize and fontify the different syntactic elements of the code, specialize textual objects for the language (so Emacs’s symbols match the languages identifiers, and its functions match the languages function definitions), balance parentheses, complete identifiers, enable commands to insert and delete comments, indent and dedent the lines appropriately, show documentation of built-in functions, jump from function and identifier uses to their definitions, expand source code templates, send function definitions to the language interpreter (REPL), interact with a debugger, compile code, and jump from compiler error messages to the locations in question.

Some of the common features of IDE’s are handled by independent, orthogonal Minor Modes. On-the-fly syntax and style checking (linting) is often handled by Flycheck¹¹⁹ or for languages that use the Language Server Protocol, Eglot or lsp-mode. Spellcheck in comments is handled by ‍flyspell-prog-mode‍. Project navigation is the domain of Projects or the much fancier Projectile. Version control has its own chapter, as do build tools, searching, and debugging.

Many Major Modes, descended from special-mode, exist to implement applications. There are innumerable examples: Dired the file manager; the Grep family; Eww, the web browser; Gnus, the mail user agent; VC, the version control system. The more elaborate applications may really be a complex of several Major Modes; the Gnus “application” consists of 16 Modes. See Part III: NEVER LEAVE EMACS: APPLICATIONS for details on many of these.

Minor Modes work like mix-ins: enable as many as you like. Emacs turns on a dozen by default to implement things like the automatic handling of compressed or encrypted files, and I typically have a couple dozen other Minor Modes enabled too. At the moment, there are at least 155 more Minor Modes available in the Package Manager, and even more on Github and the like.

Minor Modes come in two flavors, global and Buffer Local, and some come in both. When you turn on a Buffer Local Minor Mode, it’s only enabled in the current Buffer; if you want it on in another Buffer too, you need to turn it on there separately. This is why we often add Minor Modes to a Major Mode’s startup hook: so that they’re automatically turned on in all Buffers in that Major Mode. But Minor Modes that are likely to be generally useful in any Major Mode often come in a global flavor; when you turn on a global Minor Mode, it’ll be on in every Buffer that’s created. We’ve seen how you turn on line-numbers in a Buffer with M-x linum-mode; but there’s also M-x global-linum-mode. It’s up to the programmer who implements a Minor Mode to decide whether to provide a global command, a Buffer Local command, or both.

Some Minor Modes will be listed in the parentheses of the Mode Line, after the Major Mode. Right now, my Mode Line shows:

(Org Ind Fly PgLn NoMouse! Fill)

org-mode is the Major Mode and all the rest are Minor Modes. Minor Modes may shorten their Mode Line indicator¹²⁰ dramatically (“Ind” above is org-indent-mode), and some choose to provide no indicator at all (global ones tend to use no indicator). Minor Modes are used so heavily nowadays they can take up a lot of Mode Line space. Each of these indicators provides various actions for mouse clicks; see the Mode Line chapter.

We’ve seen how to add Minor Modes to hooks, but you can also turn them on and off manually. Any Minor Mode command, like M-x ‍flyspell-mode‍, will toggle that Mode: if it’s currently off, it’ll be turned on, and vice versa. (This is different from Major Mode commands, which only turn the Mode on; since there’s always one and only one Major Mode in a Buffer, you can’t simply turn it off: all you can do is turn on (and thus replace it with) a different one.) Global Minor Modes work the same way, affecting all Buffers. The only practical way to turn on Buffer Local Minor Modes in your Init File is via hooks, but you can directly turn global Modes on in your Init File like, for example:

(global-linum-mode)

Since it’s impossible to have a Frame with no Windows, there’s no command to create a Window out of thin air. If you want a new Window, you have to pick an existing Window; switch to it, if it’s not the selected Window; and split it. We’ve already discussed this in Basic Commands to Manipulate Windows. The fundamental commands are C-x 2 (‍split-window-below‍) and C-x 3 (‍split-window-right‍).

There are two basic commands for deleting Windows: C-x 0 (‍delete-window‍) and C-x 1 (‍delete-other-windows‍): in other words, you either delete this, the selected, Window, keeping all the rest, or you delete all the other Windows, keeping only this one.