Spacemacs Review and Introduction for Vim Users

Published in

usevim

8 min readMar 7, 2017

Spacemacs is an Emacs distribution that feels like Vim when editing, but doesn’t attempt to completely emulate Vim. It’s modal, so it has Normal mode, Insert mode, and loads of the editing, movement, and search commands that we use in Vim every day. It doesn’t just combine the strengths of Emacs and Vim but also adds its own unique take on the text editing experience. The most obvious example is the mnemonics-based command menus that are triggered simply when pressing space. The menu-based interface is extremely intuitive and quick, and it looks cool too.

Spacemacs mnemonics: SPC-p-f for project find file

Before going into more detail, I want to provide some context about what Spacemacs is and how to start using it. It took me a while to install and get it working well for my projects, so I wanted to provide a guide to help interested Vim users try it out. I don’t use Emacs very often, so I actually found getting started with Spacemacs difficult, despite the great documentation.

Installing Spacemacs for Vim users

Installing Spacemacs doesn’t just involve downloading the project and running Emacs. The basic steps are: download the Emacs configuration folder, install a GUI version of Emacs, install the preferred font, and open Emacs.

Here are the exact steps that I performed.

Download the Spacemacs zip file from http://spacemacs.org/
Decompress and move the folder to ~/.emacs.d
Install Emacs. On my Mac I used Homebrew to do this, I haven’t yet set it up on Windows so I’m not sure what the best approach is there.
brew tap d12frosted/emacs-plus brew install emacs-plus brew linkapps emacs-plus
Download the Source Code Pro fonts. I installed all of the TTF fonts on macOS with Font Book.
Open Emacs. On macOS that means opening the Homebrew linkapps version from the /Applications folder rather than the built-in Emacs. I had issues with Spacemacs finding programs like ag, so I’ve been running it by typing open /Applications/Emacs.app in the terminal.
The first time you open Emacs with the Spacemacs config, it’ll generate a ~/.spacemacs file. You should use this file to configure Spacemacs, but be careful where you try to put settings: the code comments will help orient you.

You should be ready to start editing files in Spacemacs now.

Welcome to your new Spacemacs installation

Now you’ve got Spacemacs running and it hopefully starts without any errors, what next? Here are a few things to keep in mind before you start trying to edit any files for real.

You can use Vim movement commands and some of Vim’s window management shortcuts. You should be able to navigate with hjkl, and even split windows with ctrl-w and ctrl-v. It doesn’t support tabs in the same way. You can also issue commands using : and search with /.
Several Emacs packages are bundled that cover Vim emulation, project management, completion, themes, and keywords. I found it useful to learn about Helm and Projectile to get the most out of Spacemacs.
Combinations of packages form “layers”. Examples of layers are completion and Vim emulation.
Lazy installation and loading are used for certain features. For example, when I opened a Markdown file to write notes for this article it installed some packages for Markdown and spell checking.

Here’s an example of the completion layer in JavaScript.

Now let’s dig into the Spacemacs configuration file so we can start doing real work!

Actually using Spacemacs for work

You’ll need to edit ~/.spacemacs to get things set up for your coding style. Here’s an example: my team uses two spaces for JavaScript files, but the default is four spaces. You can open the config file with :e ~/.spacemacs or just SPC f e d. That’s right: hold off the temptation to open the config file manually, and just type SPC f e d to open it right away! To be honest I edited it in regular Vim for a while until I discovered SPC f e d.

If you type /user-config and then press n a few times to get to the right block, you’ll see a place where you can put your own settings. It should look like this:

(defun dotspacemacs/user-config ()
 "Configuration function for user code. This function is called at the very end of Spacemacs initialization after layers configuration. This is the place where most of your configurations should be done. Unless it is explicitly specified that a variable should be set before a package is loaded, you should place your code here."
 )

Settings can be added after the comment. I added js2-basic-offset and js-indent-level.

(defun dotspacemacs/user-config ()
  "Configuration function for user code.
This function is called at the very end of Spacemacs initialization after layers configuration.
This is the place where most of your configurations should be done. Unless it is explicitly specified that a variable should be set before a package is loaded, you should place your code here."
   (setq-default js2-basic-offset 2)
   (setq-default js-indent-level 2)
  )

Notice that when you’re editing this file you can use most of the usual Vim commands. For example, I selected js2-basic-offset to copy and paste into this article by typing /js2 and then vt (vt space) to make a visual selection from the start of the value to the space. Then I used +"y to yank it into the system register and paste into this blog post. I also had to use gv at some point to reselect the text.

Project management

Spacemacs uses Projectile, which looks for files like .git to determine if you’re in a project, or a subfolder of a project. The edge-case I hit was working on a project that uses a monorepo: a single Git folder stores lots of projects that are distributed to consumers using a package manager. Fortunately Spacemacs was able to quickly search every file in this repo: that includes fuzzy file finding and code search, so the monorepo wasn’t really an issue for me.

If you’re in a similar situation, you can add.projectile files to each sub-project and then add .projectile to your global gitignore file. This will stop .projectile files from popping up in your Git remotes.

To make Projectile “see” a project, just open a file within it. It’ll recurse up the directory tree to look for an indicator of the root of the project. Once you’ve done that, press SPC f t (files neotree-toggle) to open the file tree browser. I haven’t yet figured out how to resize the file drawer, which actually made opening some files with long names awkward. I’m not really a project drawer fan anyway, so I keep it closed and use SPC p f (projectile find) to quickly find and open files in a project.

Another handy way to open files is by searching. Spacemacs will use a list of text file search utilities in order, so in my case it uses ag because I’ve installed that with Homebrew. You can press SPC s p to search in the project (search project).

The search results appear extremely quickly and it feels like it isn’t blocking, so it’s very snappy and useful for jumping around a project.

Terminal

I live inside tmux with Vim in a split pane, and I use separate windows with splits for things like running tests, managing Git, and running servers. I tried to recreate that workflow entirely within Spacemacs, because it comes with terminal emulator support.

To open a terminal, type SPC '. Press ESC to get back to Normal mode if you want to move outside of the terminal, and i to start typing in the terminal again. You can use the mouse to click outside the terminal if you prefer. The terminal open command accepts a numerical argument which lets you open several terminals. For example. 2 SPC ' would let you go to the second terminal.

Because of the way I use terminals during development, I found the Spacemacs support too flakey: I kept getting messed up character positioning, or I’d type a load of nonsense because I wasn’t sure if I was in Normal or Insert mode. It feels more like the way Visual Studio Code provides a terminal for convenience. It’s good for quickly trying expressions in a REPL or doing a git status, but it’s not at the tmux or iTerm 2 level. Although part of the reason I use the terminal that way is because my current workflow is based around the terminal and CLI Vim, so if I used Spacemacs full time I’d probably adjust and move away from relying on the terminal so much.

Conclusion

Can you use Spacemacs without any Emacs knowledge? Just about! It might be a little confusing during setup, but once you’re up and running it’s OK. Using Spacemacs without any Vim knowledge would be more challenging.

The file and project management features are full-featured and fast, I felt comfortable using them almost right away.

I used Spacemacs for two weeks at work as my main editor. The Vim layer was great for my normal Vim editing and movement commands, so I was happy with that side of things. The file and project management features are full-featured and fast, I felt comfortable using them almost right away. It suits my project-drawer-less search-heavy way of working, and I really liked the auto-completion in the languages that I use. The SPC menu is very friendly and doesn’t take too long to learn. Because it’s inside a GUI version of Emacs there’s more space for a menu like that, and I kind of wish I had it in Vim (I’m aware there are Vim scripts for this).

If you’re a Vim user you could switch to Spacemacs without too much adjustment. The main problem for me is I found it hard to understand the initial setup. The Spacemacs site really needs a focused no-nonsense installation guide that assumes you’ve never used Emacs before.

There’s also an element of confusion whenever you step outside of your Vim comfort zone into Emacs territory. It reminds me of writing Clojure without a good understanding of Java. You can do it, but it can really slow you down when you get lost.