Why emacs is worth the bother

Emacs has a few unusual properties which work together really well, making for a super powerful, flexible system that's easier to bend to your will in sophisticated ways than almost anything else around. That might sound like a lot of work, but most day-to-day emacs usage isn't reinventing the world; when you want to do something custom, though, the power is right at your fingertips. Literally.

What are those properties? Well:

1. Emacs is configured with a full-fledged, high-level programming language, with functions, control flow, etc. Emacs lisp is a dynamic functional language; the syntax is out of the ordinary, but under the hood, it's a little like old-school javascript with an emphasis on linked lists, strings, and text buffers. Except for macros, which are powerful like magic, only less… magical.

2. Literally everything you can do in emacs, including really basic stuff like "move the cursor forwards 15 characters" and "insert the text function fo() { return "haha this was not named foo" }" can be scripted with emacs lisp. Here:

   (forward-char 15)
   (insert "function fo() { return \"haha this was not named foo\" }")
   

3. Literally every user interaction follows the same model: you hit a key (or equivalent, like clicking the mouse), which triggers some lisp function.

4. You can look up, at any time you want, the name of the function bound to any key; the full documentation for any function (with a hyperlink to its source code, so you can dig as deep as you want); and the value of any variable. Just type C-h and then one of k, f, or v (guess which is which). (There are lots more help options under that C-h prefix, too.)

5. Literally any keystroke and combination can be bound to any function you want.

I know I used "literally" a lot in there, but lots of programs make sweeping "[verb] any [noun]!"-type claims that are only mostly true.

Anyway, once you internalize the logic of this system, you have superpowers! Did something weird just happen? Type C-h k, then hit the same keystroke again to find out what function is responsible. Want to change what that keystroke does? You can, on the fly. You always open the same file, so you want a shortcut? That's like a 30-second customization, once you're used to emacs. Want to do something fancy, but you don't know what the right function is named? Just search for all the available function names with C-h f, and if one sounds right, select it to check its documentation. Faster than google, and always, by definition, up-to-date with your specific emacs instance.

Emacs has a lot of janky and/or bullshit characteristics, due to its long history, survivor bias, and occasionally just due to the intransigence of the maintainers (if any emacs maintainers read this, a sincere thank you for all you do and all you have done! Now please, for the love of humans, approve some PRs to make the default UI more beginner-friendly and update its looks). No emacs user is beholden to those neckbeards, though: if you don't like it, you can change it. Or if you're not feeling like all that work, you can usually find someone else who already changed it the way you want and put that shit on github.

seriously, before you get started: remap caps lock to control

Caps lock is useless. Control is constantly used in emacs. As a bonus, lots of standard emacs shortcuts for text navigation (C-a to jump to start of line; C-e to jump to end of line; C-k to delete from the cursor to the end of text or the next newline, whichever comes first; C-t to "transpose" two characters when you make a tyop; C-n and C-p to go down/up one line) work in the shell and in almost all OSX text fields. If control is where caps lock was, all this is right on home row, super easy and ergonomic to use. If not, you sort of end up making weird claw hands all the time.

okay, with that out of the way: quick start

Lots of people will tell you that stock emacs sucks. That is because stock emacs kind of sucks. We can do better than that.

Install a version of emacs that isn't awful

If you're on a mac, there is an emacs pre-installed, but it's like 10 years out of date and only works in the terminal. It's good for one thing:

# haha, good luck figuring out how to close emacs
emacs -q --no-splash -f tetris

Tetris? Remember, you can rebind any keystroke to run your own code, and emacs will do any song and dance you're clever/patient enough to write. Web browsers were originally just for viewing documents, too.

For your non-tetris needs, you'll want to do one of these

## good, but ought to be better
brew install emacs

## much better, unless connecting to your running emacs from the terminal is important to you
## (and if it is, you probably don't need introductory notes?)
brew tap railwaycat/emacsmacport
brew install emacs-mac

Why is the normal emacs not the best choice for mac? Because the Free Software Foundation people are assholes about everything but linux. Sorry, "GNU/linux". So some guy forked emacs so he could add e.g. native OSX smooth scrolling and shit.

Install a starter kit

These have gotten popular these days. Basically, these are community-maintained configurations on top of emacs. They add in useful third-party libraries (in some cases, so useful they have become de facto standards), update the styling so emacs looks like it's from the present, instead of the mid-90s, and usually offer a bunch of variables you can tweak to easily toggle features and stuff. They're generally intended to be a more powerful and beautiful "batteries included" starting point for people. To install a starter kit, just clone the project repository to ~/.emacs.d; when you next start emacs, it will automatically load that code.

If you like piña coladas, and getting stuck in a vim session

My favorite is doom emacs. It's quite possibly the most popular, with excellent documentation and community. Doom is written by and for people who like vim's command language (which is an insanely good fit for emacs' keybinding model, actually), but you don't need to use it in a vimmy way. Most people do, because it's insanely good like that, but you do you. Doom has a wonderful system of mnemonic commands that you access via a universal prefix key (inspired by spacemacs, which is also quite good), which is the space bar if you use vim keybindings and something else if you don't. Even if you choose not to use vim bindings at all, I'd recommend doom: the out-of-the-box experience is miles better than stock emacs, it's well-organized and documented, and Henrik's hand-rolled, nix-inspired package management system absolutely shines if you ever want to keep things in sync between a personal and work computer.

If you want something more traditionally emacsy, because you don't give a fuck about vim

A venerable starter kit that's a bit more mainline emacs is Prelude. I haven't used it, so I can't comment on it much, but I've heard very good things, and its primary maintainer is pretty legit.

If you want to be FANCY

A new one is Centaur. Centaur is very pretty and into normal modern UI stuff like file trees with icons and tabs and stuff.

Oh yeah, emacs doesn't really even have decent tab support? At the time of writing, in the year of our lord 2019, it's only a first-class UI feature in the cutting edge versions and hasn't even made it to a stable release. Centaur tabs are clever, but a hack. I dunno, y'all, nothing's perfect.

Cool, you have a modern version of emacs, and now it looks adequate. Let's get oriented.

A quick tour of essential emacs keybindings

You can remap any key in any mode, but the defaults are around until and unless you change them, so they're worth knowing. I'm assuming you didn't install spacemacs in vim mode; if you did, a few parts of this won't generally apply.

By convention, emacs documents keystrokes (in all of its documentation and when reporting what keys a function is bound to) a certain way. I've already used it above. Here's a more complicated keybinding:

C-x c

This means "hold control and type x; then type c". You never hit control except in combination with other keys, so the "c" character is unambiguous in both spots there. In keybinding notation, dashes mean "hit these two keys together" and spaces mean "after typing key X, release the keys and then type key Y".

Two modifier keys are king in emacs: control, which is the control key, and meta, which is the alt key. It's weird, but emacs literally predates the alt key being standard. Meta is M-[something] in keybinding notation.

If you're a hipster like me, you might switch things up so that the mac command key is meta instead of alt. Emacs is what you make it.

First command to learn: M-x lets you run commands by name

A decent starter configuration will give you a nice fuzzy search interface when you hit M-x. Start typing, and when the command you want comes up in the results, you can use the arrow keys and enter to execute that command. Don't remember the keybinding for some functionality? Hit M-x and start typing its name. Since keyboard space is finite, some commands can only be run like this. For example, M-x snake starts a game of snake, and M-x doctor starts a psychotherapy session with everyone's favorite 1960s chatbot ELIZA.

First commands to learn: what to do when you panic

C-x C-c closes the program. It's good to know, especially if you run it in a terminal.

Within a session, if emacs freezes, or starts acting weird, or you mistype and find yourself halfway into the wrong key sequence, start spamming C-g to cancel out of whatever the current thing is. The downside to letting people run their own code is that sometimes they write dumb code and have stuff like infinite loops. In cases like this, C-g is your friend. You can also spam the escape key: on the rare occasion C-g doesn't work, three escapes usually will.

There's a method to the madness

Really quick commands you will do while you type code/prose/emails/whatever are bound to control [something] or meta [something], so you can just bust them out quickly. Commands that are common but that you're less likely to use in quick succession, like saving, managing your windows, quitting emacs, etc, are under the C-x prefix (the "x" is for "execute command": Emacs tries to make stuff mnemonic). Commands that are less common than that (or when you remember the name but not the keybinding), you can type M-x and find them by name. The similarity of the two "execute command" keybindings, C-x and M-x, is not a coincidence. Mnemonic, remember?

That's a decent intro to the standardish sort-of-hierarchy for what different modifier keys mean with the same key. C-f goes forwards one character; M-f goes forwards one word; C-M-f goes forward one semantic unit (paired quotes or braces, a code block, or whatever: different language modes can define what a semantic unit is, and emacs has some more-or-less sensible global defaults). When "same thing, but with a wider scope" doesn't make sense, sometimes control and meta do opposite versions of the same thing. I don't want to bog you down with examples, though: you can get by for a while using arrow keys, the mouse, and a small handful of memorized commands.

The file menu is a nice way to find commands at first, too, though you'll probably leave it behind as you internalize a more keyboard-driven workflow.

what is a mode, even

Modes are how emacs lets you apply or remove related configurations and keybindings en masse. Functions that manipulate ruby code only make sense if you're editing a ruby file; so those keybindings only apply when ruby-mode is active. ruby-mode is a major mode.

Every buffer has one (1) major mode. This says what kind of thing that buffer is. Is it a file of some programming language? Each programming language has its own major mode (sometimes you even have a couple options, because open source). Is the buffer an interactive feature, like a game of tetris or a git dashboard? Is it some elisp function's documentation? That's the major mode. You can use M-x to change the major mode (they're just functions, under the hood), and interact with the buffer contents in a different way, but you almost never have to.

You can only have one major mode per buffer, but you can have as many minor modes as you want. Minor modes tend to wrap a few related functions and settings into some feature, so you can easily toggle the feature by (de)activating the minor mode. Autocomplete is a minor mode. Spell-check is a minor mode. rainbow-mode is a minor mode, and makes writing CSS so much nicer. A nyan cat status bar to tell you how far into a buffer you are? Minor mode. Most features are implemented as minor modes.

[one of] the killer app[s]: org-mode

org-mode is sort of like markdown on steroids. You can rearrange the order and level of headings interactively on the fly; edit code snippets as if they were actual files, with full language support; edit tables like a spreadsheet; export your notes to pdf, html, LaTeX, github-flavored markdown (although github parses .org files just like it does .md ones), or a reveal.js slideshow; and so, so much more. I wrote this page as some quick-and-dirty notes in org-mode (seriously: if you replace index.html with index.org, you can see the raw source). org-mode started out life as a third-party package for emacs, but it is so good and became so popular that it's included with emacs now.

The basics (slightly different markdown with magic table formatting and built-in todo list support!) are simple to learn and legitimately powerful on their own; but its feature set is so deep, you can spend years learning it and still not know everything. Even if you never use emacs for anything else, org-mode is worth it.

Honest-to-god: take 30ish minutes of your life (you don't need to watch the Q and A for pete's sake) and watch this presentation that Carsten Dominik, the German astronomer who authored org-mode, gave at google: