Migrating from Vim

Spacemacs uses some different terminology than vim, which can cause confusion for new users. This section attempts to clear up any confusion.

Spacemacs uses SPC as its <Leader> key. This document will use SPC to refer to the <Leader> key. All key bindings are mnemonic and are organized under the <Leader> key. For example, the key bindings for language-specific commands are always under the SPC m prefix. A full list of conventions used in Spacemacs is here. Note that all key bindings can be changed.

Spacemacs uses which-key to show available key bindings after a delay:

Emacs commands can be run using SPC SPC. This will pop up a buffer using Helm which can be used to run any Emacs command. You can also run many ex commands using :, just like in vim.

Note: You can run Emacs interactive commands using :, but you cannot run ex commands using SPC SPC.

All file commands in Spacemacs are available under the SPC f prefix.

Emacs has an extensive help system. All key bindings under the SPC h d prefix allow convenient access to the help system. The most important of these keybindings are SPC h d f, SPC h d k, and SPC h d v. There is also the SPC <f1> key binding which allows you to search for documentation.

Whenever, you see weird behavior or want to know what something does, these functions are the first thing you should refer to.

There are a few ways to explore the functionality of Spacemacs. One is to read the source code on GitHub. You can begin to feel your way around Emacs Lisp and how Spacemacs works this way. You can also use the following key bindings to explore:

One thing that might catch you off guard is the difference in regex syntax between Vim and Emacs. In Emacs, even when you search under evil-mode with the / key, you'll be using the Emacs flavor of regular expression, instead of the Vim one.

Some idiosyncrasies of Elisp regex:

• You need to additionally escape some symbols such as:

  backslash \

  \\

  alternation |

  \|

  grouping ( and )

  \( and \)

  counting { and }

  \{ and \}

• \s begins a syntax class. Whitespaces are denoted as \s- instead of \s.
• Use [0-9] or [:digit:] instead of \d to denote digits.

For more details, refer to The EmacsWiki, this SO question and this tool which converts PCRE regex to Emacs regex.

When you first start spacemacs, you will be prompted to choose an editing style. If you are reading this, you likely want to choose the vim style. A .spacemacs file will be created with the appropriate style selected. Most trivial configuration will go in this file.

There are four top-level functions in the file: dotspacemacs/layers, dotspacemacs/init, dotspacemacs/user-init and dotspacemacs/user-config. The dotspacemacs/layers function exist only to enable and disable layers and packages. The dotspacemacs/init function is run before anything else during startup and contains Spacemacs settings. You will never need to touch this function except to change default Spacemacs settings. The dotspacemacs/user-init function is also run before anything else and contains user specific configuration. The dotspacemacs/user-config function is the one you will use the most. This is where you define any user configuration.

This section introduces a few emacs lisp functions that are needed to configure Spacemacs. For a more detailed look at the language, see this link. If you really want to learn everything there is about emacs lisp, use the info page found at SPC h i elisp RET.

As said in the terms section, layers provide an easy way to add features. Activating a layer is done in the .spacemacs file. In the file search for the dotspacemacs-configuration-layers variable. By default, it should look like this:

(defun dotspacemacs/layers ()
  (setq-default
   ;; ...
   dotspacemacs-configuration-layers '(;; auto-completion
                                       ;; better-defaults
                                       emacs-lisp
                                       ;; (git :variables
                                       ;;      git-gutter-use-fringe t)
                                       ;; markdown
                                       ;; org
                                       ;; syntax-checking
                                       )))

You can uncomment these suggested layers by deleting the semi-colons for a nice out-of-the-box experience. To add a layer, add its name to the list and restart Emacs or press SPC f e R. To view all layers and their documentation use SPC h SPC.

To group configuration or when configuration doesn't fit well in your .spacemacs file, you can create a configuration layer. Spacemacs provides a builtin command to generate the layer boilerplate: SPC SPC configuration-layer/create-layer RET. This generates a folder that looks like this:

[layer-name]
  |__ [local]*
  | |__ [example-mode-1]
  | |     ...
  | |__ [example-mode-n]
  |__ config.el*
  |__ funcs.el*
  |__ keybindings.el*
  |__ packages.el

[] = directory
* = not created by the command

The packages.el file contains a list of packages that you can install in the variable <layer-name>-packages. Any package that is available on the MELPA repository can be added to the list. A list can also exclude packages using the :excluded t property. Each package requires a function to initialize it. The function must be named with this pattern: <layer-name>/init-<package-name>. This function contains configuration for the package. There are also pre/post-init functions to execute code before or after a package loads. It would look like this:

(setq layer-name-packages '(example-package
                            ;; This layer uninstalls example-package-2
                            ;; by setting the :excluded property to true (t)
                            (example-package-2 :excluded t)))

(defun layer-name/post-init-package ()
  ;; Add configuration to a package in another layer here
  )

(defun layer-name/init-example-package ()
  ;; Configuration for example-package goes here
  )

Note: Only one layer can have a init function for a package. If you want to override the configuration of a package in another layer, use a <layer-name>/pre-init function in addition to use-package hooks.

If a package is not available on MELPA, you must use a local package or a package recipe. For more details see anatomy of a layer.

Make sure you add your layer to your .spacemacs file and restart to activate it.

A detailed description of the loading process and how layers work can be found in the configuration layers documentation.

Sometimes creating a layer is a bit overkill. Maybe you just want one package and don't want to maintain a whole layer. Spacemacs provides a variable in the dotspacemacs/layers function in .spacemacs called dotspacemacs-additional-packages. Just add a package name to the list and it will be installed when you restart. Loading the package is covered in the next section.

Ever wonder how Spacemacs can load over a 100 packages in just a few seconds? Such low loading times must require some kind of unreadable black magic that no one can understand. Thanks to use-package, this is not true. It is a package that allows easy lazy-loading and configuration of packages. Here are the basics to using it:

;; Basic form of use-package declaration. The :defer t tells use-package to
;; try to lazy load the package.
(use-package package-name
  :defer t)
;; The :init section is run before the package loads. The :config section is
;; run after the package loads
(use-package package-name
  :defer t
  :init
  ;; Change some variables
  (setq variable1 t variable2 nil)
  ;; Define a function
  (defun foo ()
    (message "%s" "Hello, World!"))
  :config
  ;; Calling a function that is defined when the package loads
  (function-defined-when-package-loads))

This is just a very basic overview of use-package. There are many other ways to control how a package loads using it that aren't covered here.

Spacemacs provides a variable in the dotspacemacs/init function in .spacemacs called dotspacemacs-excluded-packages. Just add a package name to the list and it will be uninstalled when you restart.

This section is for things many will want to change. All of these settings go in the dotspacemacs/user-config function in your .spacemacs unless otherwise noted.