An Introduction to Spacemacs

A few months ago, I decided to try Spacemacs—a super-curated yet configurable version of Emacs. In this introduction to Spacemacs, I’ll share my experience and go over some of the basic knowledge needed to get off the ground if you want to give it a try.

Before switching, I had never used Emacs—though I had been a moderate Vim user (sometimes using Vim itself, but mostly using Vim emulation or keybindings in other editors).

The learning curve for Spacemacs was not too steep. It defaults to Vim keybindings, which you can disable if you’re not a Vim user. If you’ve used Evil mode with Emacs, you’ll notice that this is what Spacemacs uses.

What’s It All About?

Unlike vanilla Emacs, Spacemacs comes pre-configured with a variety of packages and a well-defined usage model. Operations in Spacemacs are centered around the space key (hence the name). Pressing that key brings up a handy shortcut menu that displays a list of shortcut keys and descriptions.

The options on this menu look kind of strange at first, but you’ll get used to them quickly. Pressing one of these shortcuts will either perform an action or take you to another menu with more specific options. The shortcuts are based on mnemonics, which makes them easy to remember. For example, w for window, b for buffer, f for file, p for the project-specific menu, etc. There are also nice shortcuts to switch between your open windows.

Configuration

Like Emacs, Spacemacs prides itself on being super-configurable. Most options are stored in a .spacemacs file, which can be opened inside of Spacemacs via SPC f e d. This is how you’ll see Spacemacs commands written–SPC f e d means press the space key, then f, then e, then d. You’ll notice that each keystroke opens a new menu until you get to the last command, d, which opens the .spacemacs file.

At the top of the .spacemacs file, you’ll see a dotspacemacs-configuration-layers section. Spacemacs layers are essentially plugins. If you’re coming from an Emacs background, you’ve probably used MELPA packages. Spacemacs layers are often just wrappers around MELPA packages.

Many layers are available out of the box, but they need to be enabled to be used. To enable a layer, you simply add it to the configuration layers list in the .spacemacs file. I have yet to find a programming language that doesn’t have a Spacemacs layer available out of the box (that just needs to be enabled). This is what my layers list currently looks like:

After adding a layer, you’ll need to reload your config file. You can do this via SPC f e R.

In addition to installing layers, you can define user-specific settings in the user-config function in the .spacemacs file.

Basic Operations

In order to use Spacemacs, you’ll need to be familiar with some basic operations: how to manage your windows/buffers, how to manage files, how to search, etc. These operations should be enough to get you off the ground and try Spacemacs without feeling too lost.

Window management

The windowing system is relatively simple. When you launch Spacemacs, one window is open. You can split your window vertically or horizontally as many times as you would like.

SPC w / splits a window vertically.
SPC w - splits a window horizontally.

After you have a window configuration, you can navigate between windows via SPC N where N is the window number (usually 1 – 9). The window number can be found on the bottom left of the window.

Buffer management

Spacemacs buffers work similarly to those of other editors. You can open files in buffers, and then choose a window to display a buffer. You can view a list of open buffers via SPC b b. From there, you can select a buffer to view. Just because you aren’t viewing a buffer in a window doesn’t mean it’s not open.

To open a file in a buffer, you can browse to it via SPC f f and open it. If you navigate to a directory or file that doesn’t exist, Spacemacs will offer to create it for you.

Projects

Most development takes place within the context of a project. Spacemacs uses an Emacs package called Projectile to automatically detect when you are working inside of a project, and it allows you to search for files or text within the context of that project. Projectile usually uses source control hooks to determine if you are in a project (e.g., a .git directory).

When working within a project, you can toggle a file explorer view of the project on and off via SPC p t.

Find file in project
You can perform a fuzzy find search for files in the project via SPC p f. Notice the mnemonic nature of these shortcuts-p for project, f for find-file.

Search project for text
You can also search for arbitrary text in the project via SPC /. Spacemacs defaults to using ag to search, though like everything else in Spacemacs, you can change this if you’d like.

Community

Spacemacs has an active community. There is a chat on Gitter where you can ask questions or discuss features. There is also a Spacemacs subreddit that is reasonably active.

It took me a little while to get used to Spacemacs, but I slowly fell in love with the usage model. It feels tremendously productive to work in. There are endless packages to install and use. If you’re looking for a good configurable text editor I suggest you give it a try.