- Configuration layers
- Dotfile (.spacemacs)
- Dotdirectory (~/.spacemacs.d)
- Learning Spacemacs
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
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
The following command creates a layer in the
SPC SPC configuration-layer/create-layer RET
Any configuration layers you create must be explicitly loaded in
Note: For your privacy, the contents of the
private directory are not
under source control. See the section on private configuration management in
.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 SPC dotspacemacs/install RET
To open the installed dotfile:
SPC f e d
To load some configuration layers using the variable
;; 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.
Emacs, Spacemacs initialization can also be contained in an
in a special directory
~/.spacemacs.d. The contents of the dotfile should be
then copied in the
The Emacs dotfile or dotdirectory is not replaced but rather
complemented by the Spacemacs dotfile or dotdirectory. During startup,
Emacs still uses
~/.emacs) for its
initialization, and variable
user-emacs-directory will still point
~/.emacs.d/, even if
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
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
Spacemacs can be used by Vim users or Emacs users by setting the
dotspacemacs-editing-style variable to
emacs or even
in the dotfile
The leader keys
Spacemacs key bindings use a leader key which is by default bound to
SPC (space bar) in
hybrid editing styles and
You can change it by setting the variable
you use the
vim style or
dotspacemacs-emacs-leader-key if you use
emacs style (these variables must be set in the file
For simplicity the documentation always refers to the leader key as
There is secondary leader key called the major-mode leader key which is
, by default. This key is a shortcut for
where all the major-mode specific commands are bound.
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.
vim editing style the universal argument defaults to
C-u because the latter is used to scroll up as in Vim.
Configuration layers and Package discovery
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.
Key bindings discovery
Thanks to which-key, whenever a prefix command is pressed (like
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:
To narrow the bindings list to those prefixed with
type a pattern like this regular expression:
which would list all
buffer related bindings. Note: You are at the
HELM-Descbind prompt, the pattern consists of 6 letters: uppercase
backslash, an actual space and a lowercase
Describe functions are powerful Emacs introspection commands to get information
about functions, variables, modes etc. These commands are bound thusly:
how-to's are compiled in the FAQ.