getting started with Spacemacs
20 Jun 2015
Are you a vi/vim user who’s been hearing about how wonderful/useful/fast Spacemacs can be? Here is an evolving list of pointers for folks beginning to use this crazy new blend of editors…
(First: have you read the
VIMUSERS doc? You should. Go do that, then come back and start reading this.)
Heads up: Spacemacs takes over
~/.emacs.d, don’t mess with it. Your editor configuration file is now
SPC f e d to edit your config, and once it’s saved
SPC f e R to reload it and begin using it.
The space bar is now your leader key. It’s also sorta like the colon
: to start an ex command from Normal mode… it’s where pretty much all the functionality is accessible.
The Spacemacs repository’s
DOCUMENTATION.org file is much more comprehensive than the
README. Here it is at the time of writing; look for a more recent one… Ian McCowan’s post about creating Spacemacs is a valuable intro as well, but beware that some of the key combos may have changed since it was written.
Buffers don’t correspond to files…
The Meta key is still Escape?
(setq mac-option-modifier 'meta) or use the OSX package which puts it under the Option key.
At the time of writing, the recommended port for OS X has full mouse support, including scrolling — which is pixel-based, not character-based. Seeing that when I didn’t expect it was shocking enough that I felt the need to warn you.
Learning how to learn is the first step to learning…
SPC h d f (i.e. “help describe function”) will bring up another fuzzy-searchable list of functions, and when you select one it’ll pop open a buffer describing it and any keybindings for it.
SPC h d v (i.e. “help describe variable”) brings up a similar list for variables.
SPC h d and wait, a buffer appears with suggested completions.
SPC h d k (i.e. “help describe key”) prompts for another command sequence, and will pop up a buffer describing whatever it maps to. Try it on itself: type
SPC h d k, and I see a prompt
Describe key (or click or menu item): (I’m using the OS X GUI version; yours may be different) and then if I type
SPC h d k again, the buffer opens explaining a little about the command
SPC ? brings up a fuzzy-searchable list of functions, which you can run by hitting Enter.
I do a lot of work in a dedicated shell as well as my editor. To open a shell:
SPC : is like hitting
: to get into vim’s Ex command line, but includes a fuzzy-searcher for the command (
M-x in normal Emacs). Then type “shell” or “ansi-term” or “eshell” depending on what you want. “ansi-term” will ask you what shell you want to run, so that’s how I get into zsh.
finding files, changing directories
SPC f f to bring up a [buffer? window?] which finds directories or files (not fuzzy-searching though; see below for that). It begins in the current working directory, but
BS (that’s the backspace key, aka “regular delete”, the one which goes left) in there will go up a directory. Change the selected entry with the arrow keys.
Create new files with
SPC f f as well: type out a path that doesn’t exist and hit enter, it’ll ask if you want to create an empty file there.
SPC p f to fuzzy-search for files in the current project. In result list,
RET opens the file,
C-c o opens it in a new window (split).
NeoTree is a NerdTree-like plugin;
SPC f t opens the sidebar in the directory of the file you’re currently editing, and
SPC p t opens into the current project’s root directory.
hjkl to move around,
K to move up directories,
RET opens a file like you’d expect, vertical pipe
| to open a file in a new vertical split, and hyphen
- for a horizontal split.
Splits are called “windows”.
SPC w / to create a split/window to the right;
SPC w - to create a split/window to the bottom. Navigating between windows can be done with
SPC w <direction> or
C-w <direction>, where direction is one of
hjkl (and that
C-w means to hold down control and then push
Once, something I did ended up removing all my splits, as if I had ran
:only. Turns out restoring my splits is just a
SPC w u away (thanks winner mode).
I’ve been using vim-bbye to be able to kill a buffer (aka close a file) without losing the split that the buffer’s in; in Spacemacs use
SPC b d (“buffer delete”) to
kill-this-buffer. Closing a window can be done with
:q like a good little vim emulation, or
SPC w c (“window close”).
…is called line truncation.
SPC t l to toggle line truncation.
All whitespace in the current window can be made visible or invisible with the
SPC t w combo. Toggle for everything with
SPC t C-w (that’s space, then the letter
t, then hold down control and press the letter
Haven’t really gotten that far yet… turns out everything’s already got a space-based shortcut, which I’ve been able to put up with…
I’m now very accustomed to having both
kj in quick succession change to Normal node from Insert mode, but Emacs doesn’t do the “wait and see if this will be a combo” thing that vim does. However Spacemacs includes the evil-escape package, so I just needed to add
(setq-default evil-escape-key-sequence "jk") to the
For more customizable combos than just exiting insert mode, there’s a plugin called “keychord.el” which I haven’t yet looked at.
git, via Magit
Magit is an Emacs interface to Git. It sounds like it doesn’t hide any of the complexity of Git, so if you’re not already comfortable with it on the command line, Magit probably isn’t going to be helpful…
- See a diff of the current file with
SPC g d.
- Look at the overall project status with
SPC g s, then:
- open/close diffs of files in there with
swill stage a file (or hunk) and
cto bring up the commit menu (you can do interactive-type stuff here)
?to show you what else you can do (pulling, pushing, tagging, reverting, bisecting, oh my)
- Once you’ve settled on a commit message, actually commit by hitting
C-c C-c(yes that’s control-and-lowercase-c, twice in a row; is there a smoother way to do that?)
- open/close diffs of files in there with
Close these Magit windows with a bare press of
Evil-surround is like the venerable tpope’s vim-surround. The bindings are the same; e.g. inside something in parens,
cs([ will change the parens to square brackets with a space for padding,
cs(] will change them to square brackets without the space.
thanks where thanks is due
Some more people who, knowingly or unknowingly, have helped me out learning all this: tuhdo, svarlet (in the elixir-lang Slack)