Spacemacs documentation

Spacemacs will automatically check for a new version every startup. When it detects that a new version is available an arrow will appear in the modeline. Click it to update Spacemacs. You must restart Emacs after updating. Update Button

Note: If you use the develop branch of Spacemacs, automatic update is disabled—you have to update manually using git.

Use the button labeled "Update Spacemacs" in the Spacemacs buffer. You will be prompted for the version you would like to use.

Note: If you use the develop branch of Spacemacs, you cannot use this method.

To update manually close Emacs and update the git repository:

$ git pull origin master

Note: The master branch is considered to be immutable in the sense that you must not modify it by adding your own commit. If you do so you will break the automatic update of Spacemacs on the master branch. To fork Spacemacs code you have to use a custom branch that you manage manually.

Sometimes a layer can be an unnecessary overhead, this is the case if you just want to install a package with very few configuration associated to it. A good example is some niche language where you are only interested in syntax highlighting.

You can install such packages by adding them to the variable dotspacemacs-additional-packages under the dotspacemacs/layers function in your dotfile.

For example, to install llvm-mode and dts-mode:

(defun dotspacemacs/layers ()
  "Configuration Layers declaration..."
  (setq-default
   ;; ...
   dotspacemacs-additional-packages '(llvm-mode dts-mode)
   ;; ...
   ))

If you want to add some configuration for them then put the configuration in the dotspacemacs/user-config function or consider creating a layer.

Everything in the private directory is ignored by Git so it is a good place to store private layers. There is a huge drawback to this approach though: your layers are not source controlled.

This is the recommended way to manage your private layers.

The best approach is to store all your private layers into an external Git repository. It is especially a good practice to store them in your dotfiles repository if you have one. Put also your ~/.spacemacs file in it.

Then you are free to symlink your layers into ~/emacs.d/private or let them anywhere you want and reference the parent directory in the variable dotspacemacs-configuration-layer-path of your ~/.spacemacs.

Note that you could also have a dedicated repository for all your private layers and then directly clone this repository in ~/.emacs.d/private.

The final main way to manage your private layers is to push them in a personal branch that you keep up to date with upstream master or develop.

Three special functions in the ~/.spacemacs file can be used to perform configuration at the beginning and end of Spacemacs loading process:

• dotspacemacs/layers is called at the very startup of Spacemacs initilialization, this is where you set the Spacemacs distribution and declare layers to be used in your configuration. You can also add or excluded packages of your choice and tweak some behavior of Spacemacs loading.
• dotspacemacs/init is called at the very startup of Spacemacs initialization before layers configuration. You should not put any user code in there besides modifying the Spacemacs variable values prefixed with dotspacemacs-.
• dotspacemacs/user-init is called immediately after dotspacemacs/init, before layer configuration. This function is mostly useful for variables that need to be set before packages are loaded.
• dotspacemacs/user-config 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.

Custom variables configuration from M-x customize-group built-in Emacs feature are automatically saved by Emacs at the end of your ~/.spacemacs file.

Some configuration layers have configuration variables to enable specific feature. For instance the git layer has several configuration variables, they can be set directly in the dotspacemacs-configuration-layers like this:

(defun dotspacemacs/layers ()
  ;; List of configuration layers to load.
  (setq-default dotspacemacs-configuration-layers
    '(auto-completion
      (git :variables
           git-magit-status-fullscreen t
           git-variable-example nil)
      smex)))

The :variables keyword is a convenience to keep layer configuration close to their declaration. Setting layer variables in the dotspacemacs/user-init function of your dotfile is also a perfectly valid way to configure a layer.

Often layers enable services that other layers can use. For instance if you use the layer auto-completion then every other layers supporting auto-completion will have this feature enabled.

Sometimes you may want to disable a service added by a layer in some specific layers. Say you want to disable auto-completion in org and git layers, you can do it with the following layer declaration.

(defun dotspacemacs/layers ()
  ;; List of configuration layers to load.
  (setq-default dotspacemacs-configuration-layers
    '(org git
      (auto-completion :disabled-for org git))))

You can also use the :enabled-for construct to disable it for all layers except those explicitly identified.

(defun dotspacemacs/layers ()
  ;; List of configuration layers to load.
  (setq-default dotspacemacs-configuration-layers
    '(java python c-c++
      (auto-completion :enabled-for java python))))

Note that :enabled-for may be an empty list.

(defun dotspacemacs/layers ()
  ;; List of configuration layers to load.
  (setq-default dotspacemacs-configuration-layers
    '(java python c-c++
      (auto-completion :enabled-for))))

:enabled-for takes precedence over :disabled-for if both are present.

By default a declared layer installs/configures all its associated packages. You may want to select only some of them or ignoring some of them. This is possible with the :packages keyword.

For instance to ignore the neotree and fancy-battery packages from spacemacs-ui-visual layer:

(defun dotspacemacs/layers ()
  ;; List of configuration layers to load.
  (setq-default dotspacemacs-configuration-layers
    '(auto-completion
      (spacemacs-ui-visual :packages (not neotree fancy-battery))))

The opposite would be to ignore all packages except neotree and fancy-battery:

(defun dotspacemacs/layers ()
  ;; List of configuration layers to load.
  (setq-default dotspacemacs-configuration-layers
    '(auto-completion
      (spacemacs-ui-visual :packages neotree fancy-battery)))

Note: Ignoring a package from a layer is different than excluding a package. An excluded packages is completely removed from your configuration whereas an ignored package is ignored only for a given layer but it can remain on your system. It happens that if the given layer is the owner of the package then ignoring this package is the same as excluding it (because the package becomes orphan so it is considered unused by Spacemacs).

You can exclude packages you don't want to install with the variable dotspacemacs-excluded-packages (see Configuration layers for more info on packages).

For instance, to disable the rainbow-delimiters package:

(setq-default dotspacemacs-excluded-packages '(rainbow-delimiters))

When you exclude a package, Spacemacs will automatically delete it for you the next time you launch Emacs or at the next dotfile synchronization. All the orphan dependencies are also deleted automatically. Excluding a package effectively remove all references to it in Spacemacs without breaking the rest of the configuration, this is a powerful feature which allows you to quickly remove any feature from Spacemacs.

Note: A few packages are essential for Spacemacs to correctly operate, those packages are protected and cannot be excluded or unsintalled even if they become orphans or are excluded. use-package is an example of a protected package that cannot be removed from Spacemacs.

Spacemacs behaves like in Vim using Evil mode package to emulate Vim key bindings. This is the default style of Spacemacs; it can be set explicitly by setting the dotspacemacs-editing-style variable to vim in the dotfile.

To bind keys in Vim editing style (insert state):

(define-key evil-insert-state-map (kbd "C-]") 'forward-char)

Spacemacs behaves like in raw Emacs using the Holy mode which configures Evil to make the emacs state the default state everywhere. Set the dotspacemacs-editing-style variable to emacs in the dotfile.

In Emacs style the leader is available on M-m. It is possible to toggle it on and off with SPC t E e and M-m t E e. When off the vim style is enabled.

To bind keys in Emacs editing style (emacs state):

(define-key evil-emacs-state-map (kbd "C-]") 'forward-char)

The hybrid editing style is like the Vim style except that insert state is replaced by a new state called hybrid state. In hybrid state all the Emacs key bindings are available; this is like replacing the insert state with the emacs state but provides an isolated key map evil-hybrid-state-map.

To bind keys in Hybrid editing style (hybrid state):

(define-key evil-hybrid-state-map (kbd "C-]") 'forward-char)

This style can be tweaked to be more like Emacs or more like Vim depending on the user preferences. The following variable are available to change the style configuration:

• hybrid-mode-default-state The default state when opening a new buffer, default is normal. Set it to emacs for a more emacsy style.
• hybrid-mode-enable-hjkl-bindings If non nil then packages will configure h j k l key bindings for navigation.
• hybrid-mode-enable-evilified-state If non nil buffer are evilified when supported, if nil then emacs state is enabled in those buffers instead.

Default configuration is:

(setq-default dotspacemacs-editing-style '(hybrid :variables
                                           hybrid-mode-enable-evilified-state t
                                           hybrid-mode-enable-hjkl-bindings nil
                                           hybrid-mode-default-state 'normal)

To toggle the hybrid style on and off use SPC t E h and M-m t E h. When off the vim style is enabled.

Line numbers can be toggled on in all prog-mode and text-mode buffers by setting the dotspacemacs-line-numbers variable in your ~/.spacemacs to something different than nil.

(setq-default dotspacemacs-line-numbers t)

If it is set to relative, line numbers are show in a relative way:

(setq-default dotspacemacs-line-numbers 'relative)

Users who run Emacs in terminal mode may need to install the Powerline patched fonts and configure their terminal clients to use them to make the Powerline separators render correctly.

When Flycheck minor mode is enabled, a new element appears showing the number of errors, warnings and info.

Flycheck integration in mode-line

Anzu shows the number of occurrence when performing a search. Spacemacs integrates nicely the Anzu status by displaying it temporarily when n or N are being pressed. See the 5/6 segment on the screenshot below.

Anzu integration in mode-line

fancy-battery displays the percentage of total charge of the battery as well as the time remaining to charge or discharge completely the battery.

A color code is used for the battery status:

Note the these colors may vary depending on your theme.

It is possible to easily customize the powerline separator by setting the powerline-default-separator variable in your ~./spacemacs and then recompiling the modeline. For instance if you want to set back the separator to the well-known arrow separator add the following snippet to your configuration file:

(defun dotspacemacs/user-config ()
  "This is were you can ultimately override default Spacemacs configuration.
This function is called at the very end of Spacemacs initialization."
  (setq powerline-default-separator 'arrow))

To save you the time to try all the possible separators provided by the powerline, here is an exhaustive set of screenshots:

Separator	Screenshot
alternate
arrow
arrow-fade
bar
box
brace
butt
chamfer
contour
curve
rounded
roundstub
slant
wave
zigzag
nil

Spacemacs uses diminish mode to reduce the size of minor mode indicators:

The minor mode area can be toggled on and off with SPC t m m

Unicode symbols are displayed by default. Setting the variable dotspacemacs-mode-line-unicode-symbols to nil in your ~/.spacemacs will display ASCII characters instead (may be useful in terminal if you cannot set an appropriate font).

The letters displayed in the mode-line correspond to the key bindings used to toggle them.

Some toggle have two flavors: local and global. The global version of the toggle can be reached using the control key.

Spacemacs uses Spaceline to provide its mode-line. It consists of a number of segments arranged on the left and right sides. These are defined in the variables spaceline-left and spaceline-right. Segments can be defined using spaceline-define-segment, and added to the appropriate location in the left or right hand side variables.

Please see the Spaceline documentation for more information.

The default layout (the layout created at the startup of Emacs) is not displayed in the mode-line but it is possible to display it by setting the variable dotspacemacs-display-default-layout to t.

Its name is "default" by default but it can be changed by setting the variable dotspacemacs-default-layout-name.

The default layout is special because it has a global scope which means that all the opened buffers belong to it. So using only the default layout feels like not using layouts at all.

A project layout is bound to a projectile project. To create a project layout use SPC p l.

The name of the layout is the name of the project root directory.

Custom layouts can be defined using the macro spacemacs|define-custom-layout, they are accessible via SPC l o.

By convention the name of a custom layout should start with @.

Example of custom layout definition for ERC buffers:

(spacemacs|define-custom-layout "@ERC"
  :binding "E"
  :body
  (progn
    ;; hook to add all ERC buffers to the layout
    (defun spacemacs-layouts/add-erc-buffer-to-persp ()
      (persp-add-buffer (current-buffer)
                        (persp-get-by-name
                         erc-spacemacs-layout-name)))
    (add-hook 'erc-mode-hook #'spacemacs-layouts/add-erc-buffer-to-persp)
    ;; Start ERC
    (call-interactively 'erc)))

Then use SPC l o E to start ERC inside its own layout. Any new ERC buffer will be part of the custom layout.

Some custom layouts that ship with Spacemacs:

With SPC l s and SPC l L you can save and load layouts to/from a file.

Note: By default, Spacemacs will automatically save the layouts under the name persp-auto-save.

Setting the variable dotspacemacs-auto-resume-layouts to t will automatically resume the last saved layouts.

The key bindings are registered in a transient state. The docstring of the transient state displays the existing layouts and the currently active layout has square brackets. Pressing a layout number will activate it (or create a new one) and exit the transient state. It is possible to just preview a layout with Ctrl-<number>. Pressing TAB will activate the previously selected layout.

Press ? to toggle the full help.

The key bindings are registered in a transient state. The docstring of the transient state displays the existing workspaces and the currently active workspace has square brackets. Pressing a workspace number will activate it (or create a new one) and exit the transient state. It is possible to just preview a workspace with Ctrl-<number>. Pressing TAB will activate the previously selected workspace.

Press ? to toggle the full help.

There are also some handy globally available key bindings related to workspaces:

Spacemacs uses evil-escape to easily switch between insert state and normal state by quickly pressing the fd keys.

The choice of fd was made to be able to use the same sequence to escape from "everything" in Emacs:

• escape from all stock evil states to normal state
• escape from evil-lisp-state to normal state
• escape from evil-iedit-state to normal state
• abort evil ex command
• quit minibuffer
• abort isearch
• quit magit buffers
• quit help buffers
• quit apropos buffers
• quit ert buffers
• quit undo-tree buffer
• quit paradox
• quit gist-list menu
• quit helm-ag-edit
• hide neotree buffer

If you find yourself in a buffer where the Spacemacs (SPC) or Vim keybindings don't work you can use this to get back to normal state (for example in SPC SPC customize press fd to make SPC b b work again).

This sequence can be customized in your ~/.spacemacs. Example to set it to jj:

(defun dotspacemacs/user-config ()
  (setq-default evil-escape-key-sequence "jj"))

Note: Although jj or jk are popular choices of vim users, these key sequences are not optimal for Spacemacs. Indeed it is very easy in visual state to press quickly jj and inadvertently escape to normal state.

The emacs command key SPC (executed after the leader key) can be changed with the variable dotspacemacs-emacs-command-key of your ~/.spacemacs.

On top of Vim modes (modes are called states in Spacemacs) there is a special key called the leader key which once pressed gives a whole new keyboard layer. The leader key is by default SPC (space). It is possible to change this key with the variable dotspacemacs-leader-key.

Additional text objects are defined in Spacemacs:

Do not hesitate to read the Helm documentation wiki.

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

Other help key bindings:

Navigation key bindings in help-mode:

Reporting an issue:

Note: If these two bindings are used with the *Backtrace* buffer open, the backtrace is automatically included

All layers can be easily discovered via helm-spacemacs-help accessible with SPC h SPC.

The following helm actions are available:

• default: open the layer README.org
• 2nd: open the layer packages.el

helm-spacemacs-help is also a central place to discover the available toggles. To display only the toggles source press C-l (or in Helm transient state you can press just l).

The following helm actions are available on packages:

• default: toggle on/off

Tips Use SPC h l to resume the last helm session. It is handy to quickly toggle on and off a toggle.

Navigation is performed using the Vi key bindings hjkl.

Spacemacs uses the evil integration of avy which enables the invocation of avy during motions.

For instance, it is useful for deleting a set of visual lines from the current line. Try the following sequence in a buffer containing some text: d SPC j l, followed by selecting an avy candidate.

Spacemacs comes with a built-in port of tpope's vim-unimpaired.

This plugin provides several pairs of bracket maps using [ to denote previous, and ] as next.

The SPC j prefix is for jumping, joining and splitting.

By default Spacemacs uses helm to open files.

Spacemacs displays the ido minibuffer vertically thanks to the ido-vertical-mode.

Basic ido operations can be done with Ctrl key:

Spacemacs defines a transient state for ido.

Initiate the transient state with M-SPC or s-M-SPC while in an ido buffer.

Spacemacs provides a quick and simple way to navigate in an unknown project file tree with NeoTree.

To toggle the NeoTree buffer press SPC f t or SPC p t (the latter open NeoTree with the root set to the projectile project root).

The NeoTree window always has the number 0 so it does not shift the current number of the other windows. To select the NeoTree window you then use SPC 0.

VCS integration is supported, the file color will change depending on its current state. With default spacemacs-dark theme:

• green: new file
• purple: modified file

Bookmarks can be set anywhere in a file. Bookmarks are persistent. They are very useful to jump to/open a known project. Spacemacs uses helm-bookmarks to manage them.

Open an helm window with the current bookmarks by pressing: SPC f b

Then in the helm-bookmarks buffer:

To save a new bookmark, just type the name of the bookmark and press RET.

doc-view-mode is a built-in major mode to view DVI, PostScript (PS), PDF, OpenDocument, and Microsoft Office documents.

By default auto-saving of files is performed every 300 characters and every 30 seconds of idle time which can be changed by setting to a new value the variables auto-save-inteval and auto-save-timeout respectively.

Auto-save of modified files can be performed in-place on the original file itself or in the cache directory (in this case the original file will remain unsaved). By default Spacemacs auto-save the file in the cache directory.

To modify the location set the variable dotspacemacs-auto-save-file-location to original or cache.

Local files are auto-saved in a sub-directory called site in the cache directory whereas remote files (i.e. files edited over TRAMP) are auto-saved in a sub-directory called dist.

To disable auto-saving set the variable dotspacemacs-auto-save-file-location to nil.

You can toggle auto-save in a buffer by calling the command auto-save-mode.

Spacemacs can be interfaced with different search utilities like:

• ack
• grep
• ag
• pt

The search commands in Spacemacs are organized under the SPC s prefix with the next key is the tool to use and the last key is the scope. For instance SPC s a b will search in all opened buffers using ag.

If the last key (determining the scope) is uppercase then the current region or symbol under point is used as default input for the search. For instance SPC s a B will search with symbol under point (if there is no active region).

If the tool key is omitted then a default tool will be automatically selected for the search. This tool corresponds to the first tool found on the system of the list dotspacemacs-search-tools, the default order is ag, pt, ack then grep. For instance SPC s b will search in the opened buffers using pt if ag has not been found on the system.

The tool keys are:

The available scopes and corresponding keys are:

It is possible to search in the current file by double tapping the second key of the sequence, for instance SPC s a a will search in the current file with ag.

Notes:

• ag and pt are optimized to be used in a source control repository but they can be used in an arbitrary directory as well.
• It is also possible to search in several directories at once by marking them in the helm buffer.

Beware if you use pt, TCL parser tools also install a command line tool called pt.

Spacemacs uses evil-search-highlight-persist to keep the searched expression highlighted until the next search. It is also possible to clear the highlighting by pressing SPC s c or executing the ex command :noh.

Spacemacs supports highlighting of the current symbol on demand (provided by auto-highlight-symbol mode) and adds a transient state to easily navigate and rename this symbol.

It is also possible to change the range of the navigation on the fly to:

• buffer
• function
• visible area

To initiate the highlighting of the current symbol under point press SPC s h.

Navigation between the highlighted symbols can be done with the commands:

In 'Spacemacs' highlight symbol transient state:

(*) using iedit or the default implementation of auto-highlight-symbol

The transient state text in minibuffer display the following information:

<M> [6/11]* press (n/N) to navigate, (e) to edit, (r) to change range or (R)
for reset

Where <M> [x/y]* is:

• M: the current range mode
• <B>: whole buffer range
• <D>: current display range
• <F>: current function range
• x: the index of the current highlighted occurrence
• y: the total number of occurrences
• *: appears if there is at least one occurrence which is not currently visible.

With evil-visualstar you can search for the next occurrence of the current selection.

It is pretty useful combined with the expand-region bindings.

Note: If the current state is not the visual state then pressing * uses auto-highlight-symbol and its transient state.

Use helm-semantic-or-imenu command from Helm to quickly navigate between the symbols in a buffer.

To list all the symbols of a buffer press: SPC s j

This is very similar to moccur, it displays a helm buffer with all the occurrences of the word under point. You can then change the search query in real-time and navigate between them easily.

You can even edit the occurrences directly in the helm buffer and apply the modifications to the buffer.

Text related commands (start with x):

Text insertion commands (start with i):

Smartparens comes with a strict mode which prevents deletion of parenthesis if the result is unbalanced.

This mode can be frustrating for novices, this is why it is not enabled by default.

It is possible to enable it easily for all programming modes with the variable dotspacemacs-smartparens-strict-mode of you ~/.spacemacs.

(setq-default dotspacemacs-smartparens-strict-mode t)

Spacemacs uses evil-numbers to easily increase or decrease numbers.

In transient state:

Tips: you can increase or decrease a value by more that once by using a prefix argument (ie. 10 SPC n + will add 10 to the number under point).

Spell checking is enabled by including the spell checking layer in your dotfile.

Keybindings are listed in the layer documentation.

Vi Visual modes are all supported by evil.

The displayed text of a buffer can be narrowed with the commands (start with n):

Spacemacs uses the powerful iedit mode through evil-iedit-state to quickly edit multiple occurrences of a symbol or selection.

evil-iedit-state defines two new evil states:

• iedit state
• iedit-insert state

The color code for these states is red.

evil-iedit-state has also a nice integration with expand-region for quick editing of the currently selected text by pressing e.

If you have ag, pt or ack installed, replacing an occurrence of text in several files can be performed via helm-ag.

Say you want to replace all foo occurrences by bar in your current project:

• initiate a search with SPC /
• enter in edit mode with C-c C-e
• go to the occurrence and enter in iedit state with SPC s e
• edit the occurrences then leave the iedit state
• press C-c C-c

Note: In Spacemacs, helm-ag despite its name works with ack and pt as well (but not with grep).

It is possible to batch rename files in a directory using wdired from an helm session:

• browse for a directory using SPC f f
• enter wdired with C-c C-e
• edit the file names and use C-c C-c to confirm the changes
• use C-c C-k to abort any changes

Comments are handled by evil-nerd-commenter, it's bound to the following keys.

Tips: To comment efficiently a block of line use the combo SPC ; SPC y

Spacemacs uses the packages pcre2el to manipulate regular expressions. It is useful when working with Emacs Lisp buffers since it allows to easily converts PCRE (Perl Compatible RegExp) to Emacs RegExp or rx. It can also be used to "explain" a PCRE RegExp around point in rx form.

The key bindings start with SPC x r and have the following mnemonic structure:

• SPC x r <source> <target> convert from source to target
• SPC x r do what I mean

Deletion is configured to send deleted files to system trash.

On OS X the trash program is required. It can be installed with homebrew with the following command:

$ brew install trash

To disable the trash you can set the variable delete-by-moving-to-trash to nil in your ~/.spacemacs.

Editing of lisp code is provided by evil-lisp-state.

Commands will set the current state to lisp state where different commands combo can be repeated without pressing on SPC k.

When in lisp state the color of the mode-line changes to pink.

Examples:

• to slurp three times while in normal state: SPC k 3 s
• to wrap a symbol in parentheses then slurp two times: SPC k w 2 s

Note: The lisp state commands are available in any modes! Try it out.

There are some added mouse features set for the line number margin (if shown):

• single click in line number margin visually selects the entire line
• drag across line number margin visually selects the region
• double click in line number margin visually select the current code block

Key bindings specific to the current major mode start with SPC m. For convenience a shortcut key called the major mode leader key is set by default on ​,​ which saves one precious keystroke.

It is possible to change the major mode leader key by defining the variable dotspacemacs-major-mode-leader-key in your ~/.spacemacs. For example to setup the key on tabulation:

(setq-default dotspacemacs-major-mode-leader-key "<tab>")

Spacemacs add hjkl navigation to helm buffers:

You can open a file in Emacs from the terminal using emacsclient. Use emacsclient -c to open the file in Emacs GUI. Use emacsclient -t to open the file in Emacs within the terminal.

If you want your Linux/OS X system to use Emacs by default for any prompt, you need to set it in your shell configuration, e.g. ~/.bashrc or ~/.zshrc:

export EDITOR="emacsclient -c"

Note that if you're on OS X, you may have to refer to the emacsclient that comes with your GUI Emacs, e.g.:

export EDITOR="/Applications/Emacs.app/Contents/MacOS/bin/emacsclient -c"

Tip: Remember to use :wq or C-x # after you are done editing the file in Emacs.

See Emacs as a Server in the official Emacs manual for more details.

If any errors happen during the loading the mode-line will turn red and the errors should appear inline in the startup buffer. Spacemacs should still be usable; if it is not then restart Emacs with emacs --debug-init and open a Github issue with the backtrace.

To ensure that packages are correctly compiled for the new Emacs version you installed, be sure to run the interactive command spacemacs/recompile-elpa with SPC SPC spacemacs/recompile-elpa.