Some hints for the new or prospective Emacs user.
Emacs is enormously complex — but not complicated. There aren’t a lot of moving parts to learn about, but they interact in fantastically rich and complex ways, and it can be hard to know where to start.
I wish I’d had a ‘here are the standard components of a good Emacs setup’ guide when I started. There are distribution packages that handle such setup for you — Doom, Spacemacs, et al. — but if you actually want to be an expert Emacs user, you’re far better off getting comfortable with vanilla Emacs and then (if ever) switching to a prepackaged distro once you know what you want. The value of Emacs is lost when you hide its inner workings behind such ‘sugar.’
Emacs might be the most impressive single piece of software ever written for personal computing (not counting operating systems etc.). With great power comes great responsibility; here are some tips for absolute beginners, to help you claim them both.
My imagined reader is an interested non-programmer wondering about this weird and supposedly powerful tool. Experienced programmers should rely on other guides to get started, though newbies might learn something.
Learn about M-x
Start Emacs, then type Meta-x — on a Mac this should be Option-x, on Windows Alt-x. The cursor will move to a one-line text area (the ‘minibuffer’) at the bottom of the screen. This is a place to talk directly to Emacs. It awaits your input.
Type kill-emacs, hit Return, and congratulate yourself on a job well done.
Meta-X, abbreviated M-x, is the standard ‘invoke a command’ key combination. After invoking M-x, you type the name of a function — a small piece of computer code defined within Emacs — and hit Return. Emacs tries to run the code.
There’s a lot of functions available. Emacs exposes its guts to the user; that’s the source of its astounding power, the feeling of weird freedom it grants.
But don’t type M-x kill-emacs anymore — C-x C-c will do from now on.
Learn about C-g
Type M-x kill again, but don’t hit Return — we’ve changed our mind, we want to live!
Hit Ctrl-g (abbreviated C-g).
Nice work, you just canceled a command, or more precisely you just executed the keyboard-quit command.
C-g is bound, by default, to the universal ‘cancel and escape’ command in Emacs. Get used to it. (I’ve got that command remapped to the actual Escape key, for reasons.)
Swap Caps Lock and Control
Caps Lock is nigh useless and Emacs will wear out your Ctrl key real fast. Figure out how to swap them on your computer/keyboard, and enjoy knock-on benefits from consigning Caps Lock to the bin where it belongs. Better yet, sell your car and buy a ZSA Moonlander keyboard instead, then set up homerow modifiers. I’m not joking — the ergonomic benefits are huge, beyond even the major ergonomic upgrade from moving to a split/tented configuration. (No one with normal hands/arms should ever use a ‘normal’ keyboard again.)
Learn about online help
Hit C-h, then k. (In emacs documentation this is written ‘C-h k,’ get used to that nomenclature.) You’re now in help mode, specifically executing the describe-key function, and you are prompted to type a key command. Type M-x and look what pops up: the name of the function ‘bound’ to M-x, and a description of that function.
Now hit C-g, or hit Escape three times (these are basically equivalent). The popup help area is dismissed.
Emacs has extraordinarily rich help of this kind: describe-function and describe-face (as in ‘typeface’) and describe-bindings, but also an excellent built-in tutorial and a famous batch of very long manuals whose first editions date back several decades.
Knowing how to get help with and from Emacs will make the experience much much smoother.
Learn about your init files (like .emacs)
You’ll spend a lot of time tweaking your ‘init files’ later — e.g. your .emacs file in your home folder. What you need to know right now is this: they’re not just preference files. Your init files are themselves computer programs, executed line by line every time Emacs launches, written in a language called Emacs Lisp or elisp. To configure Emacs, you’ll write code — arbitrary code — and this is one of the most badass things about Emacs. Normal settings/preferences files specify adverbs, and the software sticks to its standard verbs; your init files let you provide the verbs directly.
See, Emacs is an umbrella for running other pieces of software. It’s like a word processor, but it’s even more like the operating system a word processor runs on.
There are good tutorials online and loads of sample init files to browse, as well as the excellent Emacs Manual.
Learn about buffers, windows, and frames
In Emacs, ‘everything is a buffer.’
Sorta.
- What you call a ‘window,’ Emacs calls a ‘frame.’
- What you’d call a ‘pane’ or equivalent — half of a split screen, say — Emacs calls a ‘window.’
- And a buffer is an area containing text, sometimes — but not always — connected to a file, i.e. ‘visiting’ a file.
When you start up Emacs and get kicked to the *scratch* buffer, you see *scratch*, the minibuffer, and the modeline (which isn’t a buffer, actually; rather it’s a feature of the window it’s in).
When you open the calendar (M-x calendar), up comes a read-only calendar-mode buffer. In calendar-mode — a ‘major mode’ — pressing ‘o’ brings up a prompt to enter a new calendar year, i.e. ‘o’ is bound to a calendar-specific function in that major mode. (Hitting ‘q’ exits the calendar program…but doesn’t kill the buffer, per se. Don’t worry about it.)
Each buffer has a current major-mode, and any number of minor-modes (including global ones which apply to all buffers). Understanding how these work and interact is essential to navigating Emacs, and a huge help when it comes to learning commands and keystrokes.
Learn about modes
Way beyond the scope of this document, but you need to be able to answer a few questions:
- What major-mode is currently active?
- What minor-modes is currently active?
- What’re the keymaps for these modes?
- How do I change these things?
- How and when do modes get invoked?
Thinking of a ‘mode’ as a ‘syntax’ will get you a lot of the way there, but not all the way.
Print a movement cheatsheet
I like this one. Getting around Emacs buffers can be weird, and the commands you’re probably used to probably don’t work ‘right.’ Learn the Emacs commands, even if they seem weird or stupid. Weird doesn’t matter if you’re fast and accurate. You should put in the time to master moving quickly around the buffer.
Learn how to execute elisp code anywhere
In the *scratch* buffer that opens when you launch Emacs, type (+ 2 3) and, with the cursor just after the closing parenthesis, type C-x C-e. Check out the minibuffer: it should say ‘5’ and you just executed a bit of Lisp code, which should be easy to decipher even if you’ve never seen it before.
Remember how your init files are computer programs? And now you’ve just run a very short program in the middle of a random textfile. Understand: Emacs gives you access to its own guts, all the time, no matter what you’re doing at the time.
You’ve never had this degree of control over a piece of software before, this level of introspection available. You interact with the program by altering it… If you’re thinking it through, that should be a head trip, the kind that’s good for you.
…
OK, so much for the ultra-simple stuff. Now for the ‘…but how do I make Emacs more normal?’-type advice.
Select a package manager
Emacs loads extensions or ‘packages’ on launch. You download a package (M-x package-install, then specify name), and load it up. Doing this manually is a pain in the ass — and it makes your setup/config much less portable, since you can sit down at a new computer with the same init files and not have the packages you need to make them work.
Use the use-package or straight.el package-management tools. I use and recommend the former.
Get a narrowing-completion framework
Now we go into the weeds just a little bit.
Every Emacs user relies on a tool like Ido (interactive-do), Ivy, Avy, Helm, et al.: programs that let you narrow a list of choices, select quickly and smoothly, and do smart things with your selection. For instance, you wanna be able to type M-x packinst and have Emacs figure out that you mean package-install — this is ‘fuzzy finding’ and the vanilla alternative is terrible. When you run find-file (C-x C-f, i.e. ‘open’), factory-fresh Emacs behaves like the command line, where you’re expected to type exactly what you mean and get only tab-completion to save trouble. But look up Ivy and Helm online and see what else is possible.
Same with searching in a buffer. Emacs’s built-in incremental search function is good — try C-s * in a buffer full of text — but a jump-to-match tool like *avy is insanely good. Once you’ve tried it, you won’t want to go back to the mundane world.
Get in-buffer completion
Distinct from list-completion is a tool like Company (‘complete anything’), which autosuggests and does code completion. When I’m typing in my personal wiki, if I pause mid-word for a fraction of a second, company’ll pop up an ‘are you trying to link to this file?’ suggestion; I hit return to get a properly formatted link right there, boom. You need a tool in this class, which leapfrogs the whole pack of ‘minimalist text editors’ which so fascinate dabblers and dilettantes. (If you’re after that hipster typing experience, pick a classy font and turn on writeroom-mode or darkroom-mode or olivetti-mode.)
Pick a nice theme
Stock Emacs doesn’t look like anything, unless ‘old’ is a look. But it’s got loads of themes available, some (e.g. Zenburn, Monokai, Gruvbox) really very nice. There are even packages to enable live theme previews. Add commands to your init file to download and enable the theme you like, then…
Sync your init files
Dropbox, Github, Syncthing, whatever. (Github might be best because no overhead: anywhere you have a command line and an Internet connection, you have your files.) Pick a service, sync your init files between machines, and carry your Emacs everywhere you go. You don’t realize how empowering this is until you do it, then you can’t not do it.
Learn about keymaps
There is a logic to Emacs key commands, and there is an implicit keystroke ‘composition’ happening behind the scenes — learn about mode-specific keymaps and the subtle mnemonics will start to reveal themselves. When I’m in markdown-mode, say, C-c C-s is a prefix to nearly 30 markup commands, e.g. C-c C-s b for boldface. The logic is sane: C-c for user/mode commands, C-s for insssert(!), b for bold. On an ergonomic keyboard this is quick and, crucially, discoverable.
And you should install which-key ASAP, to prompt you when you’re not sure of a command.
Emacs’s commands lack the tight focus of vim’s bespoke fingertip-interface, but so does everything; vim is a hyperoptimized, narrowly focused tool, Emacs is a cosmos. Yet once you get that there’s an implicit modality to Emacs’s keyboard UI, you can start tailoring individual shortcuts to your preferences without having to worry about colliding with some other definition. And of course, C-h k is your friend.
Tighten the modeline
Use diminish/delight to remove unwanted minor-modes from your modeline, grab a useful theme (I use spaceline), and get the program working (and looking) exactly the way you want it.
Get markdown-mode or whatever
The target audience for this article probably writes in Markdown a fair amount. Jason Blevins’s markdown-mode is really good; set it up to auto-engage when you open a .md/.mdown file, get comfy with the shortcuts, and you’re just about ready for md-roam (q.v. ‘org-mode’ below)…
Consider evil-mode
One of Emacs’s dirty open secrets is that its keybindings are borderline insane. Even something as simple as ‘C-g to cancel’ — seriously, not just Escape? You have to engage your stupid pinky finger hundreds of extra times a day? (Assuming Ctrl is in its usual place, that is…)
I use Escape in place of C-g, but that doesn’t help with ugliness like ‘M-} to go down a paragraph.’ And I use a frankly expensive Moonlander keyboard that gives me homerow modifiers — but I only have so many fingers and don’t love stretching for chords all the time.
Consider evil-mode, which is not just the best but the best possible vim emulator in the business: a full-on modal editor with all of vim’s famously terse, ergonomic, and composable key commands, atop Emacs’s fantastic extensibility and power (and using elisp for extensions, instead of the widely disliked vimscript). Imagine floating on vim’s interface, and being able to dive into Emacs whenever you like.
If you can get comfortable with modal editing (where hitting Escape pops you out of typing mode into navigation/command mode, freeing up your basic single-stroke alphanumeric keys for stuff other than typing), then evil-mode is one of the hidden killer apps for Emacs — a ‘better vim’ built in to the editor that’s supposed to be vim’s, I dunno, nemesis or something.
Notice some minor tools
Try M-x calendar and M-x calculator. Pretty nifty, eh? And each is just a buffer, meaning all the ways of manipulating a text buffer’s contents are available to you inside these ‘minor’ tools.
Consider org-mode
Holy shit, org-mode.
Along with evil-mode, org-mode is Emacs’s secret weapon — but where evil-mode is there to bridge the vim/Emacs gap to make Emacs a better pure text editor, org-mode is a whole ecosystem of unique software tools. And org-mode is not just Emacs-native but basically Emacs-only. At its heart, it’s a task-manager, outliner, and personal productivity tool; it does things like automatically gather to-do items from every file in a project into an agenda, that kind of thing. It is, and yes I know this sounds crazy, easily the best tool of its kind — get your setup Just Right and it’s the last productivity software you’ll ever need. And it’s deeply integrated into Emacs, down to the bones. Capture a to-do item from inside any buffer. Insert a link to an org outline item (node) into any file, along with dynamic to-do status tracking. Track overall project status in futureproof portable plaintext using tools that automate all the clerical work. Export to a million formats. (People write entire scholarly books in org-mode w/bibtex on the backend and spit out gorgeous LaTeX with a keystroke.)
I use an org extension called org-roam (which began as a Roam Research emulator) to maintain a slowly growing ‘zettelkasten’ or ‘personal knowledge management’ setup. It’s great — but org alone is insanely powerful.1 Indeed, if you’re on the fence about whether to try Emacs at all, org might be what pushes you over to this side. (It’s one of the biggest Emacs/vim differentiators, certainly.)
(Mac users: there are tools to connect org-mode to programs like Drafts, to move you toward ‘ubiquitous capture.’)
Check out magit
Magit is the best frontend for git. There’s just no serious competition in GUI-land or at the command line. You think I’m being hyperbolic, but for God’s sake go have a look.
Check out GNU hyperbole
This one you’ll have to see for yourself: an all-purpose ‘turn textual features into buttons’ machine. You don’t need this software — I don’t use it — but it’s one of the most outlandish achievements in the Emacs sphere, just a terribly impressive and useful piece of software. It’ll change how you think about text editors, which is sort of the point of this whole exercise.
Quality of life
From here you can start making quality-of-life improvements of varying scope:
- dogears to supplement Emacs’s persistent bookmarks with quick per-session bookmarks
- marginalia or equivalent (e.g. ivy-rich) to display useful information during interactions w/Emacs
- org-roam or deft for managing libraries of notes
- flyspell (with aspell behind it) for strong spellchecking, and flyspell-correct for the right interface for your completion framework
- avy, because it’s a different paradigm from the ‘standard’ helm/ivy approach and it’ll help wean you off those pesky non-ergonomic arrow keys, which are killing you
- crux, though you’ll soon end up replacing all its handy constituent functions with features of other packages
- dirvish for a way better file-nav experience, and either dirvish-side or neotree or equivalent for a folder-hierarchy sidebar
- all-the-icons for all the icons
- org-bullets and org-ql and oh there’s so damned much you can do with org-mode
- yasnippet, which brings snippets over from textmate/sublimetext and makes them way more powerful (you can execute elisp code in a yasnippet)
- projectile, obviously, for usefully restricting search to a project and integrating nicely with loads of other tools
- visual-regexp-steroids, if you want realtime previews of regular expression substitutions plus freedom from Emacs’s indescribably irritating regex syntax (all those escaped parentheses!)
Put simply: your first days with Emacs will be interesting but difficult. But one day you’ll find yourself doing something that’s simply impossible with literally any other text editor ever written, and something down deep will awaken — it’s not a text editor, it’s a Lisp runtime that edits text — and you’ll spend the next however many years dealing with, and figuring out for yourself how to take advantage of, that knowledge.
- I’m switching away from org-roam for non-org reasons, beyond the scope of this article. ↩
wax banks 