Quick start

Table of ContentsClose

1. Configuration layers
2. Dotfile (.spacemacs)
3. Dotdirectory (~/.spacemacs.d)
4. Learning Spacemacs
5. How-To's

1 Configuration layers

Spacemacs divides its configuration into self-contained units called configuration layers. These layers are stacked on top of each other to achieve a custom configuration.

By default Spacemacs uses a dotfile called ~/.spacemacs to control which layers to load. Within this file you can also configure certain features.

A configuration layer is a directory containing at least a packages.el file which defines and configures packages to be downloaded from Emacs package repositories using the package.el built-in feature of Emacs.

If you already have your own Emacs configuration you can move it to your own layer.

The following command creates a layer in the private directory:

SPC : configuration-layer/create-layer RET

Any configuration layers you create must be explicitly loaded in ~/.spacemacs.

Note: For your privacy, the contents of the private directory are not under source control. See the section on private configuration management in the documentation.

2 Dotfile (.spacemacs)

As mentioned .spacemacs controls which configuration layers to load and is also a means to customizing Spacemacs.

The following command will create a .spacemacs file in your home directory:

SPC : dotspacemacs/install RET

To open the installed dotfile:

SPC f e d

To load some configuration layers using the variable dotspacemacs-configuration-layers:

;; List of configuration layers to load.
dotspacemacs-configuration-layers '(auto-completion smex)

Some configuration layers support configuration variables to expose granular control over layer-specific features, git layer being one such example. Variables can be directly set within dotspacemacs-configuration-layers like so:

;; List of configuration layers to load.
dotspacemacs-configuration-layers '(auto-completion
                                    (git :variables
                                         git-magit-status-fullscreen t)
                                    smex)

At anytime you can apply the changes made to the dotfile or layers without restarting Spacemacs by pressing SPC f e R.

The dotfile template contain further information about how to customize Spacemacs. See the dotfile configuration section of the documentation for more details.

3 Dotdirectory (~/.spacemacs.d)

Like Emacs, Spacemacs initialization can also be contained in an init.el file in a special directory ~/.spacemacs.d. The contents of the dotfile should be then copied in the init.el file.

The Emacs dotfile or dotdirectory is not replaced but rather complemented by the Spacemacs dotfile or dotdirectory. During startup, Emacs still uses ~/.emacs.d/init.el (or ~/.emacs) for its initialization, and variable user-emacs-directory will still point to ~/.emacs.d/, even if ~/.spacemacs.d or ~/.spacemacs are present. Only now ~/.emacs.d/init.el is provided by Spacemacs (e.g. after cloning the Spacemacs git repo into an empty ~/.emacs.d/), and your own personnal configurations go into ~/.spacemacs.d/init.el (or ~/.spacemacs).

Have a look into the FAQ for an easy workaround to maintain (your former) vanilla Emacs and (your new) Spacemacs configurations side-by-side without the need to rename and backup ~/.emacs.d/.

4 Learning Spacemacs

4.1 Editing Styles

Spacemacs can be used by Vim users or Emacs users by setting the dotspacemacs-editing-style variable to vim, emacs or even hybrid in the dotfile ~/.spacemacs.

4.2 The leader keys

Spacemacs key bindings use a leader key which is by default bound to SPC (space bar) in vim or hybrid editing styles and M-m in emacs style.

You can change it by setting the variable dotspacemacs-leader-key if you use the vim style or dotspacemacs-emacs-leader-key if you use the emacs style (these variables must be set in the file ~/.spacemacs).

For simplicity the documentation always refers to the leader key as SPC.

There is secondary leader key called the major-mode leader key which is set to , by default. This key is a shortcut for SPC m where all the major-mode specific commands are bound.

4.3 Evil-tutor

If you are willing to learn the Vim key bindings (highly recommended since you can benefit from them even in emacs style), press SPC h T to begin an Evil-adapted Vimtutor.

4.4 Universal argument

In vim editing style the universal argument defaults to SPC u instead of C-u because the latter is used to scroll up as in Vim.

4.5 Configuration layers and Package discovery

By using helm-spacemacs-help with SPC h SPC you can quickly search for a package and get the name of the layers using it.

You can also easily go to the README.org of a layer or go to the initialization function of a package.

4.6 Key bindings discovery

Thanks to which-key, whenever a prefix command is pressed (like SPC) a buffer appears after one second listing the possible keys for this prefix.

It is also possible to search for specific key bindings by pressing:

SPC ?

To narrow the bindings list to those prefixed with SPC, type a pattern like this regular expression:

SPC\ b

which would list all buffer related bindings. Note: You are at the HELM-Descbind prompt, the pattern consists of 6 letters: uppercase SPC, a backslash, an actual space and a lowercase b.

4.7 Describe functions

Describe functions are powerful Emacs introspection commands to get information about functions, variables, modes etc. These commands are bound thusly:

Key Binding	Description
`SPC h d f`	describe-function
`SPC h d k`	describe-key
`SPC h d m`	describe-mode
`SPC h d v`	describe-variable

5 How-To's

Some quick how-to's are compiled in the FAQ.org file.