3591 lines
195 KiB
Org Mode
3591 lines
195 KiB
Org Mode
#+TITLE: Spacemacs documentation
|
||
|
||
* Table of Contents :TOC_4_gh:noexport:
|
||
- [[#core-pillars][Core Pillars]]
|
||
- [[#mnemonic][Mnemonic]]
|
||
- [[#discoverable][Discoverable]]
|
||
- [[#consistent][Consistent]]
|
||
- [[#crowd-configured][Crowd-Configured]]
|
||
- [[#highlighted-features][Highlighted features]]
|
||
- [[#screenshots][Screenshots]]
|
||
- [[#who-can-benefit-from-this][Who can benefit from this?]]
|
||
- [[#update-and-rollback][Update and Rollback]]
|
||
- [[#update-spacemacs-repository][Update Spacemacs repository]]
|
||
- [[#automatic-updates][Automatic Updates]]
|
||
- [[#updating-from-the-spacemacs-buffer][Updating from the Spacemacs Buffer]]
|
||
- [[#updating-manually-with-git][Updating Manually with git]]
|
||
- [[#update-packages][Update packages]]
|
||
- [[#configuration-layers][Configuration layers]]
|
||
- [[#purpose][Purpose]]
|
||
- [[#structure][Structure]]
|
||
- [[#configure-packages][Configure packages]]
|
||
- [[#with-a-layer][With a layer]]
|
||
- [[#declaration][Declaration]]
|
||
- [[#initialization][Initialization]]
|
||
- [[#exclusion][Exclusion]]
|
||
- [[#without-a-layer][Without a layer]]
|
||
- [[#packages-synchronization][Packages synchronization]]
|
||
- [[#types-of-configuration-layers][Types of configuration layers]]
|
||
- [[#submitting-a-configuration-layer-upstream][Submitting a configuration layer upstream]]
|
||
- [[#example-themes-megapack-example][Example: Themes Megapack example]]
|
||
- [[#managing-private-configuration-layers][Managing private configuration layers]]
|
||
- [[#using-the-private-directory][Using the private directory]]
|
||
- [[#using-an-external-git-repository][Using an external Git repository]]
|
||
- [[#using-a-personal-branch][Using a personal branch]]
|
||
- [[#tips-for-writing-layers][Tips for writing layers]]
|
||
- [[#dotfile-configuration][Dotfile Configuration]]
|
||
- [[#dotfile-installation][Dotfile Installation]]
|
||
- [[#alternative-dotdirectory][Alternative dotdirectory]]
|
||
- [[#synchronization-of-dotfile-changes][Synchronization of dotfile changes]]
|
||
- [[#testing-the-dotfile][Testing the dotfile]]
|
||
- [[#dotfile-contents][Dotfile Contents]]
|
||
- [[#configuration-functions][Configuration functions]]
|
||
- [[#custom-variables][Custom variables]]
|
||
- [[#declaring-configuration-layers][Declaring Configuration layers]]
|
||
- [[#setting-configuration-layers-variables][Setting configuration layers variables]]
|
||
- [[#disabling-layer-services-in-other-layers][Disabling layer services in other layers]]
|
||
- [[#selectingignoring-packages-of-a-layer][Selecting/Ignoring packages of a layer]]
|
||
- [[#excluding-packages][Excluding packages]]
|
||
- [[#concepts][Concepts]]
|
||
- [[#editing-styles][Editing Styles]]
|
||
- [[#vim][Vim]]
|
||
- [[#emacs][Emacs]]
|
||
- [[#hybrid][Hybrid]]
|
||
- [[#states][States]]
|
||
- [[#evilified-modes][Evilified modes]]
|
||
- [[#evil-leader][Evil leader]]
|
||
- [[#universal-argument][Universal argument]]
|
||
- [[#transient-states][Transient-states]]
|
||
- [[#toggles][Toggles]]
|
||
- [[#configuring-toggles-in-the-dotfile][Configuring toggles in the dotfile]]
|
||
- [[#differences-between-vim-evil-and-spacemacs][Differences between Vim, Evil and Spacemacs]]
|
||
- [[#the-vim-surround-case][The vim-surround case]]
|
||
- [[#evil-plugins][Evil plugins]]
|
||
- [[#environment-variables-and-path][Environment variables and PATH]]
|
||
- [[#default-behavior][Default behavior]]
|
||
- [[#managing-environment-variables-by-yourself][Managing environment variables by yourself]]
|
||
- [[#note-about-the-function-dotspacemacsuser-env][Note about the function dotspacemacs/user-env]]
|
||
- [[#binding-keys][Binding keys]]
|
||
- [[#gui-elements][GUI Elements]]
|
||
- [[#color-themes][Color themes]]
|
||
- [[#default-theme][Default theme]]
|
||
- [[#choosing-themes][Choosing themes]]
|
||
- [[#themes-transient-state][Themes Transient State]]
|
||
- [[#browsing-themes][Browsing themes]]
|
||
- [[#notes][Notes]]
|
||
- [[#font][Font]]
|
||
- [[#gui-toggles][GUI Toggles]]
|
||
- [[#global-line-numbers][Global line numbers]]
|
||
- [[#mode-line][Mode-line]]
|
||
- [[#mode-line-themes][Mode-line themes]]
|
||
- [[#separators][Separators]]
|
||
- [[#separator-scale][Separator scale]]
|
||
- [[#spacemacs-mode-line-theme][Spacemacs mode-line theme]]
|
||
- [[#flycheck-integration][Flycheck integration]]
|
||
- [[#anzu-integration][Anzu integration]]
|
||
- [[#battery-status-integration][Battery status integration]]
|
||
- [[#all-the-icons-theme][All-the-Icons theme]]
|
||
- [[#custom-spaceline-theme][Custom spaceline theme]]
|
||
- [[#minor-modes][Minor Modes]]
|
||
- [[#frame-title][Frame title]]
|
||
- [[#iconified-tabified-title][Iconified (tabified) title]]
|
||
- [[#layouts-and-workspaces][Layouts and workspaces]]
|
||
- [[#layouts][Layouts]]
|
||
- [[#the-default-layout][The default layout]]
|
||
- [[#project-layouts][Project layouts]]
|
||
- [[#custom-layouts][Custom Layouts]]
|
||
- [[#saveload-layouts-into-a-file][Save/Load layouts into a file]]
|
||
- [[#layout-key-bindings][Layout key bindings]]
|
||
- [[#workspaces][Workspaces]]
|
||
- [[#workspace-key-bindings][Workspace key bindings]]
|
||
- [[#commands][Commands]]
|
||
- [[#vim-key-bindings][Vim key bindings]]
|
||
- [[#escaping][Escaping]]
|
||
- [[#executing-vim-and-emacs-exm-x-commands][Executing Vim and Emacs ex/M-x commands]]
|
||
- [[#leader-key][Leader key]]
|
||
- [[#major-mode-leader-key][Major Mode leader key]]
|
||
- [[#additional-text-objects][Additional text objects]]
|
||
- [[#reserved-prefix-command-for-user][Reserved prefix command for user]]
|
||
- [[#completion][Completion]]
|
||
- [[#discovering][Discovering]]
|
||
- [[#key-bindings][Key bindings]]
|
||
- [[#which-key][Which-key]]
|
||
- [[#describe-key-bindings][Describe key bindings]]
|
||
- [[#getting-help][Getting help]]
|
||
- [[#available-layers][Available layers]]
|
||
- [[#available-packages-in-spacemacs][Available packages in Spacemacs]]
|
||
- [[#new-packages-from-elpa-repositories][New packages from ELPA repositories]]
|
||
- [[#toggles-1][Toggles]]
|
||
- [[#navigating][Navigating]]
|
||
- [[#pointcursor][Point/Cursor]]
|
||
- [[#smooth-scrolling][Smooth scrolling]]
|
||
- [[#vim-motions-with-avy][Vim motions with avy]]
|
||
- [[#ace-link-mode][ace-link mode]]
|
||
- [[#unimpaired-bindings][Unimpaired bindings]]
|
||
- [[#jumping-joining-and-splitting][Jumping, Joining and Splitting]]
|
||
- [[#jumping][Jumping]]
|
||
- [[#joining-and-splitting][Joining and splitting]]
|
||
- [[#window-manipulation][Window manipulation]]
|
||
- [[#window-manipulation-key-bindings][Window manipulation key bindings]]
|
||
- [[#window-manipulation-transient-state][Window manipulation transient state]]
|
||
- [[#golden-ratio][Golden ratio]]
|
||
- [[#buffers-and-files][Buffers and Files]]
|
||
- [[#buffers-manipulation-key-bindings][Buffers manipulation key bindings]]
|
||
- [[#create-a-new-empty-buffer][Create a new empty buffer]]
|
||
- [[#buffers-manipulation-transient-state][Buffers manipulation transient state]]
|
||
- [[#files-manipulations-key-bindings][Files manipulations key bindings]]
|
||
- [[#frame-manipulation-key-bindings][Frame manipulation key bindings]]
|
||
- [[#emacs-and-spacemacs-files][Emacs and Spacemacs files]]
|
||
- [[#browsing-files-in-completion-buffer][Browsing files in completion buffer]]
|
||
- [[#ido][Ido]]
|
||
- [[#ido-transient-state][Ido transient state]]
|
||
- [[#bookmarks][Bookmarks]]
|
||
- [[#docview-mode][DocView mode]]
|
||
- [[#auto-saving][Auto-saving]]
|
||
- [[#frequency-of-auto-saving][Frequency of auto-saving]]
|
||
- [[#location-of-auto-saved-files][Location of auto-saved files]]
|
||
- [[#disable-auto-save][Disable auto-save]]
|
||
- [[#searching][Searching]]
|
||
- [[#with-an-external-tool][With an external tool]]
|
||
- [[#useful-key-bindings][Useful key bindings]]
|
||
- [[#searching-in-current-file][Searching in current file]]
|
||
- [[#searching-in-all-open-buffers-visiting-files][Searching in all open buffers visiting files]]
|
||
- [[#searching-in-files-in-an-arbitrary-directory][Searching in files in an arbitrary directory]]
|
||
- [[#searching-in-current-directory][Searching in current directory]]
|
||
- [[#searching-in-a-project][Searching in a project]]
|
||
- [[#searching-the-web][Searching the web]]
|
||
- [[#persistent-highlighting][Persistent highlighting]]
|
||
- [[#highlight-current-symbol][Highlight current symbol]]
|
||
- [[#visual-star][Visual Star]]
|
||
- [[#listing-symbols-by-semantic][Listing symbols by semantic]]
|
||
- [[#editing][Editing]]
|
||
- [[#paste-text][Paste text]]
|
||
- [[#paste-transient-state][Paste Transient-state]]
|
||
- [[#auto-indent-pasted-text][Auto-indent pasted text]]
|
||
- [[#text-manipulation-commands][Text manipulation commands]]
|
||
- [[#text-insertion-commands][Text insertion commands]]
|
||
- [[#smartparens-strict-mode][Smartparens Strict mode]]
|
||
- [[#zooming][Zooming]]
|
||
- [[#text][Text]]
|
||
- [[#frame][Frame]]
|
||
- [[#increasedecrease-numbers][Increase/Decrease numbers]]
|
||
- [[#spell-checking][Spell checking]]
|
||
- [[#region-selection][Region selection]]
|
||
- [[#expand-region][Expand-region]]
|
||
- [[#indent-text-object][Indent text object]]
|
||
- [[#region-narrowing][Region narrowing]]
|
||
- [[#replacing-text-with-iedit][Replacing text with iedit]]
|
||
- [[#iedit-states-key-bindings][iedit states key bindings]]
|
||
- [[#examples][Examples]]
|
||
- [[#replacing-text-in-several-files][Replacing text in several files]]
|
||
- [[#renaming-files-in-a-directory][Renaming files in a directory]]
|
||
- [[#commenting][Commenting]]
|
||
- [[#regular-expressions][Regular expressions]]
|
||
- [[#deleting-files][Deleting files]]
|
||
- [[#editing-lisp-code][Editing Lisp code]]
|
||
- [[#lisp-key-bindings][Lisp Key bindings]]
|
||
- [[#mouse-usage][Mouse usage]]
|
||
- [[#managing-projects][Managing projects]]
|
||
- [[#registers][Registers]]
|
||
- [[#errors-handling][Errors handling]]
|
||
- [[#error-transient-state][Error transient state]]
|
||
- [[#custom-fringe-bitmaps][Custom fringe bitmaps]]
|
||
- [[#compiling][Compiling]]
|
||
- [[#editorconfig][EditorConfig]]
|
||
- [[#emacs-server][Emacs Server]]
|
||
- [[#connecting-to-the-emacs-server][Connecting to the Emacs server]]
|
||
- [[#keeping-the-server-alive][Keeping the server alive]]
|
||
- [[#disabling-the-emacs-server][Disabling the Emacs server]]
|
||
- [[#troubleshoot][Troubleshoot]]
|
||
- [[#loading-fails][Loading fails]]
|
||
- [[#upgradingdowngrading-emacs-version][Upgrading/Downgrading Emacs version]]
|
||
- [[#achievements][Achievements]]
|
||
- [[#issues][Issues]]
|
||
- [[#merged-pull-requests][Merged Pull Requests]]
|
||
- [[#stars-forks-and-watchers][Stars, forks and watchers]]
|
||
- [[#gitter-chat][Gitter chat]]
|
||
- [[#first-times][First times]]
|
||
- [[#special-mentions][Special Mentions]]
|
||
- [[#special-titles][Special Titles]]
|
||
- [[#thank-you][Thank you]]
|
||
|
||
* Core Pillars
|
||
Four core pillars: Mnemonic, Discoverable, Consistent and “Crowd-Configured”.
|
||
|
||
If any of these core pillars are violated, open an issue and we’ll try our best
|
||
to fix it.
|
||
|
||
** Mnemonic
|
||
Key bindings are organized using mnemonic prefixes like ~b~ for buffer, ~p~ for
|
||
project, ~s~ for search, ~h~ for help, etc...
|
||
|
||
** Discoverable
|
||
Innovative real-time display of available key bindings. Simple query
|
||
system to quickly find available layers, packages, and more.
|
||
|
||
** Consistent
|
||
Similar functionalities have the same key binding everywhere, thanks to a
|
||
clearly defined set of conventions. Documentation is mandatory for any layer
|
||
that ships with Spacemacs.
|
||
|
||
** Crowd-Configured
|
||
Community-driven configuration provides curated packages tuned by power users
|
||
and bugs are fixed quickly.
|
||
|
||
* Highlighted features
|
||
- *Bring the efficiency of modal editing* to the powerful Emacs lisp platform.
|
||
Modal UX is optional and Spacemacs can be used with only Emacs key bindings.
|
||
- Integrate nicely with =Evil= states (=Vim= modes).
|
||
- *Keep your fingers on the home row* for quicker editing with support for
|
||
QWERTY and BEPO layouts.
|
||
- *Minimalistic and nice graphical UI* keeps your available screen space for
|
||
what matters: your text files.
|
||
- *Fast boot time*: packages and configuration are lazy-loaded as much as
|
||
possible.
|
||
- *Lower the risk of RSI* by heavily using the space bar instead of modifiers.
|
||
If you have issues with your thumbs you can still use Spacemacs using
|
||
modifiers.
|
||
- Contribute easily with your improvements and new configuration layers.
|
||
- *Very active and helpful community* on =Gitter= and =IRC=
|
||
(via Gitter IRC bridge)
|
||
|
||
* Screenshots
|
||
[[file:img/spacemacs-python.png]]
|
||
/Python/
|
||
*Note*: Even though screenshots are updated frequently, Spacemacs is evolving
|
||
quickly and the screenshots may not reflect exactly the current state of the
|
||
project.
|
||
|
||
* Who can benefit from this?
|
||
- Spacemacs was initially intended to be used by *Vim users* who want to go to
|
||
the next level by using Emacs (see [[https://github.com/syl20bnr/spacemacs/blob/master/doc/VIMUSERS.org][guide]] for Vimmers). But it is now
|
||
perfectly *usable by non Vim users* by choosing the =emacs= editing style.
|
||
- It is also a good fit for people wanting to *lower the [[https://en.wikipedia.org/wiki/Repetitive_strain_injury][risk of RSI]]* induced by
|
||
the default Emacs key bindings. (This is an assumption, there are no official
|
||
studies to prove this!) If you have issues using your thumbs you can still
|
||
use the =emacs= editing style which puts the leader key on a modifier
|
||
combination.
|
||
- Emacs users wanting to learn *a different way to edit files* or wanting to
|
||
learn Vim key bindings or even wanting to mix both editing styles by setting
|
||
their style to =hybrid=.
|
||
- Emacs users wanting a simple but deep configuration system that greatly *lowers the risk of .emacs bankruptcy*.
|
||
- *Pair-programming* users thanks to out of the box support for dynamic
|
||
switching of editing style. A Vim user and an Emacs user can use the same
|
||
Spacemacs comfortably.
|
||
|
||
* Update and Rollback
|
||
** Update Spacemacs repository
|
||
There are several methods of updating the core files and layer information for
|
||
Spacemacs. It is recommended to update the packages first; see the next section.
|
||
|
||
*** Automatic Updates
|
||
Spacemacs will automatically check for a new version periodically. 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.
|
||
[[file:img/powerline-update.png]]
|
||
/Update Button/
|
||
*Note*: If you use the =develop= branch of Spacemacs, automatic update is
|
||
disabled---you have to update manually using git.
|
||
|
||
*** Updating from the Spacemacs Buffer
|
||
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.
|
||
|
||
*** Updating Manually with git
|
||
To update manually close Emacs and update the git repository:
|
||
|
||
#+BEGIN_SRC sh
|
||
$ git pull origin master
|
||
#+END_SRC
|
||
*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.
|
||
|
||
** Update packages
|
||
To update the Emacs packages used by Spacemacs press RET (enter) or click on the
|
||
link =[Update Packages]= in the startup page under the banner then restart
|
||
Emacs. If you prefer, you can use the command
|
||
=configuration-layer/update-packages= instead of the button.
|
||
|
||
If anything goes wrong you should be able to rollback the update by pressing
|
||
~RET~ or clicking on the =[Rollback Package Update]= link in the startup page
|
||
and choosing a rollback slot (sorted by date). This button uses the command
|
||
=configuration-layer/rollback=.
|
||
|
||
* Configuration layers
|
||
This section is an overview of layers. A more extensive introduction to writing
|
||
configuration layers can be found [[https://github.com/syl20bnr/spacemacs/blob/master/doc/LAYERS.org][here]] (recommended reading!).
|
||
|
||
** Purpose
|
||
Layers help collect related packages together to provide features. For example,
|
||
the =python= layer provides auto-completion, syntax checking, and REPL support
|
||
for python files. This approach helps keep configuration organized and reduces
|
||
overhead for the user by keeping them from having to think about what packages
|
||
to install. To install all the =python= features the user has just to add the
|
||
=python= layer to their dotfile.
|
||
|
||
** Structure
|
||
Configuration is organized in layers. Each layer has the following structure:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
[layer_name]
|
||
|__ [local]
|
||
| |__ [package 1]
|
||
| | ...
|
||
| |__ [package n]
|
||
|-- layers.el
|
||
|__ packages.el
|
||
|__ funcs.el
|
||
|__ config.el
|
||
|__ keybindings.el
|
||
|
||
[] = directory
|
||
#+END_EXAMPLE
|
||
|
||
Where:
|
||
|
||
| File | Usage |
|
||
|----------------+--------------------------------------------------------------------------------------------------|
|
||
| layers.el | The place to declare additional layers |
|
||
| packages.el | The list of packages and their configuration functions (init, post-init, etc...) |
|
||
| funcs.el | All functions defined in the layer (used in package configuration for instance) |
|
||
| config.el | Layer configuration (defines the layer variables default values and setup some config variables) |
|
||
| keybindings.el | General key bindings not tied to a specific package configuration |
|
||
=Packages= can be:
|
||
- =ELPA= packages installed from an =ELPA= compliant repository
|
||
- local packages in a layer’s =local= folder
|
||
- installed from an online source using [[https://github.com/quelpa/quelpa][quelpa]].
|
||
|
||
** Configure packages
|
||
*** With a layer
|
||
**** Declaration
|
||
=Packages= are declared in a variable called =<layer>-packages= where =<layer>=
|
||
is the name of the layer.
|
||
|
||
Example:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq <layer>-packages '(package1 package2 ...)
|
||
#+END_SRC
|
||
|
||
All packages from all layers are processed in alphabetical order so sometimes
|
||
you’ll have to use some =with-eval-after-load= black magic to configure them
|
||
properly. For instance, if package =A= depends on =B= then you can configure
|
||
=A= with:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(with-eval-after-load 'B ...)
|
||
#+END_SRC
|
||
|
||
For details on installing packages using quelpa or local packages see [[https://github.com/syl20bnr/spacemacs/blob/master/doc/LAYERS.org#packagesel][LAYERS]].
|
||
|
||
**** Initialization
|
||
To initialize a package =xxx=, define a function with this format in
|
||
=packages.el=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun <layer>/init-xxx () ...body )
|
||
#+END_SRC
|
||
|
||
It is common to define the body with the [[https://github.com/jwiegley/use-package][use-package]] macro.
|
||
|
||
**** Exclusion
|
||
It is possible to exclude some packages from Spacemacs on a per-layer basis.
|
||
This is useful when a configuration layer aims to replace a stock package
|
||
declared in the Spacemacs layer.
|
||
|
||
To do so add the package names to exclude to the variable
|
||
=<layer>-excluded-packages=.
|
||
|
||
Example:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq <layer>-excluded-packages '(package1 package2 ...)
|
||
#+END_SRC
|
||
|
||
*** Without a layer
|
||
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=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun dotspacemacs/layers ()
|
||
"Configuration Layers declaration..."
|
||
(setq-default
|
||
;; ...
|
||
dotspacemacs-additional-packages '(llvm-mode dts-mode)
|
||
;; ...
|
||
))
|
||
#+END_SRC
|
||
|
||
If you want to add some configuration for them, do so in the
|
||
=dotspacemacs/user-config= function, or consider creating a layer.
|
||
|
||
** Packages synchronization
|
||
Spacemacs will only install the packages that are explicitly used by the user.
|
||
A package is considered to be used if its layer is used (i.e. listed in
|
||
=dotspacemacs-configuration-layers=).
|
||
Any package that is not used will be considered an orphan and will be deleted at
|
||
the next startup of Emacs.
|
||
|
||
** Types of configuration layers
|
||
There are two types of configuration layers:
|
||
- distributed layers (in the =layers= directory, those layers are contributions shared
|
||
by the community and merged upstream)
|
||
- private (in the =private= directory, they are ignored by Git)
|
||
|
||
** Submitting a configuration layer upstream
|
||
If you decide to provide a configuration layer, please check the contribution
|
||
guidelines first in [[https://github.com/syl20bnr/spacemacs/blob/develop/COMMUNITY.org][CONTRIBUTING]].
|
||
|
||
** Example: Themes Megapack example
|
||
This is a simple configuration layer listing a bunch of themes which you can
|
||
find [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Bthemes/themes-megapack/README.org][here]].
|
||
|
||
To install it, just add =themes-megapack= to your =~/.spacemacs= like so:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-configuration-layers '(themes-megapack))
|
||
#+END_SRC
|
||
|
||
Adding this layer will install around 100 themes; to uninstall them remove the
|
||
layer from the =dotspacemacs-configuration-layers= and press ~SPC f e R~.
|
||
|
||
** Managing private configuration layers
|
||
Spacemacs’s configuration system is flexible enough to let you manage your
|
||
private layers in different ways.
|
||
|
||
*** Using the private directory
|
||
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/.
|
||
|
||
*** Using an external Git repository
|
||
This is the recommended way to manage your private layers.
|
||
|
||
The best approach is to store all your private layers in an external Git
|
||
repository. For example, if you have a =dotfiles= repository it is a good
|
||
practice to store these layers in there, along with your =~/.spacemacs= file.
|
||
|
||
Then you are free to symlink your layers into =~/emacs.d/private= /or/ leave them
|
||
anywhere you want, and reference the parent directory in the variable
|
||
=dotspacemacs-configuration-layer-path= of your =~/.spacemacs=.
|
||
*Note*: You could also have a dedicated repository for all your private layers
|
||
and then directly clone this repository in =~/.emacs.d/private=.
|
||
|
||
*** Using a personal branch
|
||
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=.
|
||
|
||
** Tips for writing layers
|
||
Please refer to [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/LAYERS.org][this]] introduction for some tips on writing layers, and how to
|
||
best make them fit with the Spacemacs philosophy and loading strategy.
|
||
|
||
* Dotfile Configuration
|
||
User configuration can be stored in your =~/.spacemacs= file.
|
||
|
||
** Dotfile Installation
|
||
The very first time Spacemacs starts up, it will ask you several questions
|
||
and then install the =.spacemacs= file in your =HOME= directory.
|
||
|
||
** Alternative dotdirectory
|
||
A dotdirectory =~/.spacemacs.d/= can be used instead of a dotfile.
|
||
If you want to use this option, move =~/.spacemacs= to =~/.spacemacs.d/init.el=.
|
||
|
||
It is also possible to override the location of =~/.spacemacs.d/= using the
|
||
environment variable =SPACEMACSDIR=. Of course, you can also use symlinks to
|
||
change the location of this directory.
|
||
*Note*: =~/.spacemacs= will always take priority over =~/.spacemacs.d/init.el=,
|
||
so =~/.spacemacs= must not exist for =~/.spacemacs.d/init.el= to be used by
|
||
Spacemacs.
|
||
|
||
** Synchronization of dotfile changes
|
||
To apply the modifications made in =~/.spacemacs= press ~SPC f e R~. It will
|
||
re-execute the Spacemacs initialization process.
|
||
*Note*: A synchronization re-executes the functions =dotspacemacs/init=,
|
||
=dotspacemacs/user-init= and =dotspacemacs/user-config=.
|
||
Depending on the contents of these functions, you may encounter some unwanted side
|
||
effects. For instance, if you use a toggle in =dotspacemac/user-config= to enable
|
||
some behavior, this behavior will be turned off whenever the dotfile is
|
||
re-synchronized. To avoid these side-effects, it is recommended to either use
|
||
=setq= expressions instead of toggle functions, or to use the =on= or =off=
|
||
versions instead (i.e. instead of =spacemacs/toggle-<thing>=, use
|
||
=spacemacs/toggle-<thing>-on= or =spacemacs/toggle-<thing>-off=).
|
||
|
||
It is possible to /skip/ the execution of =dotspacemacs/user-config= with the
|
||
universal argument (~SPC u SPC f e R~).
|
||
|
||
** Testing the dotfile
|
||
You can use the command =SPC SPC dotspacemacs/test-dotfile= to check if your
|
||
=~/.spacemacs= looks correct. This will check, among other things, whether the
|
||
declared layers can be found and that the variables have sensible values. These
|
||
tests are also run automatically when you synchronize with ~SPC f e R~.
|
||
|
||
** Dotfile Contents
|
||
*** Configuration functions
|
||
Five 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 initialization,
|
||
this is where you set the Spacemacs distribution and declare layers to be used
|
||
in your configuration. You can also add or exclude packages of your choice
|
||
and tweak some behaviors 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-env= is called before the layers and packages configuration
|
||
and it is responsible to setup environment variables.
|
||
- =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.
|
||
- =dotspacemacs/emacs-custom-settings= is a generated function where all Emacs
|
||
custom settings are written. You should not edit this function. See =Custom variables= section for more information.
|
||
|
||
*** Custom variables
|
||
By default custom variables from =M-x customize-group= are automatically saved
|
||
at the end of your =~/.spacemacs= file in the function
|
||
=dotspacemacs/emacs-custom-settings= unless you declare a custom =custom-file=
|
||
in the =dotspacemacs/user-init= function, in this case custom variables will be
|
||
written to the user defined =custom-file= and the function
|
||
=dotspacemacs/emacs-custom-settings= will remain empty.
|
||
*Note*: If you set a custom =custom-file= value then it is your responsibility
|
||
to load this file at the appropriate time. Often the best time to load it is
|
||
just after setting the value for =custom-file= in the =dotspacemacs/user-init=
|
||
function.
|
||
|
||
** Declaring Configuration layers
|
||
To use a configuration layer, declare it in your dotfile by adding it to the
|
||
=dotspacemacs-configuration-layers= variable of your =~/.spacemacs=.
|
||
*Note*: In this documentation a =used layer= is equivalent to a =declared
|
||
layer=.
|
||
|
||
For instance, [[#thank-you][RMS]] can add his private configuration layer like this:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-configuration-layers
|
||
'(
|
||
;; other layers
|
||
;; rms layer added at the end of the list
|
||
rms
|
||
))
|
||
#+END_SRC
|
||
|
||
Official layers shipped with Spacemacs are stored in =~/.emacs.d/layers=. The
|
||
directory =~/.emacs.d/private= is a drop-in location for your private layers.
|
||
It is possible to put layers at the location of your choice provided you tell
|
||
Spacemacs where to look for them. This is done by setting the list
|
||
=dotspacemacs-configuration-layer-path= in your =~/.spacemacs=. For instance
|
||
to add some layers in =~/.myconfig=, set the variable like this:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-configuration-layer-path '("~/.myconfig/"))
|
||
#+END_SRC
|
||
|
||
*** Setting configuration layers variables
|
||
Some configuration layers have configuration variables to enable specific
|
||
features. For instance the [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Bsource-control/git/README.org][git layer]] has several configuration variables, they
|
||
can be set directly in the =dotspacemacs-configuration-layers= like this:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(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)))
|
||
#+END_SRC
|
||
|
||
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.
|
||
|
||
*** Disabling layer services in other layers
|
||
Often layers enable services that other layers can use. For instance if you use
|
||
the layer =auto-completion= then all 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.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun dotspacemacs/layers ()
|
||
;; List of configuration layers to load.
|
||
(setq-default dotspacemacs-configuration-layers
|
||
'(org git
|
||
(auto-completion :disabled-for org git))))
|
||
#+END_SRC
|
||
|
||
You can also use the =:enabled-for= construct to disable it for /all/ layers
|
||
/except/ those explicitly identified.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun dotspacemacs/layers ()
|
||
;; List of configuration layers to load.
|
||
(setq-default dotspacemacs-configuration-layers
|
||
'(java python c-c++
|
||
(auto-completion :enabled-for java python))))
|
||
#+END_SRC
|
||
|
||
Note that =:enabled-for= may be an empty list.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun dotspacemacs/layers ()
|
||
;; List of configuration layers to load.
|
||
(setq-default dotspacemacs-configuration-layers
|
||
'(java python c-c++
|
||
(auto-completion :enabled-for))))
|
||
#+END_SRC
|
||
=:enabled-for= takes precedence over =:disabled-for= if both are present.
|
||
|
||
*** Selecting/Ignoring packages of a layer
|
||
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 =treemacs= and =fancy-battery= packages from
|
||
=spacemacs-ui-visual= layer:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun dotspacemacs/layers ()
|
||
;; List of configuration layers to load.
|
||
(setq-default dotspacemacs-configuration-layers
|
||
'(auto-completion
|
||
(spacemacs-ui-visual :packages (not treemacs fancy-battery))))
|
||
#+END_SRC
|
||
|
||
The opposite would be to ignore all packages except =treemacs= and
|
||
=fancy-battery=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun dotspacemacs/layers ()
|
||
;; List of configuration layers to load.
|
||
(setq-default dotspacemacs-configuration-layers
|
||
'(auto-completion
|
||
(spacemacs-ui-visual :packages treemacs fancy-battery)))
|
||
#+END_SRC
|
||
*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).
|
||
|
||
*** Excluding packages
|
||
You can exclude packages you don’t want to install with the variable
|
||
=dotspacemacs-excluded-packages= (see [[#configuration-layers][Configuration layers]] for more info
|
||
on packages).
|
||
|
||
For instance, to disable the =rainbow-delimiters= package:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-excluded-packages '(rainbow-delimiters))
|
||
#+END_SRC
|
||
|
||
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 uninstalled even if they become
|
||
orphans or are excluded. =use-package= is an example of a protected package that
|
||
cannot be removed from Spacemacs.
|
||
|
||
* Concepts
|
||
** Editing Styles
|
||
Spacemacs comes with several editing styles which can be switched dynamically
|
||
providing an easier way to do pair programming, for instance between a Vim user
|
||
and an Emacs user.
|
||
|
||
Three styles are available:
|
||
- Vim,
|
||
- Emacs,
|
||
- Hybrid (a mix between Vim and Emacs).
|
||
|
||
To set the editing style set the variable =dotspacemacs-editing-style= to
|
||
either =vim=, =hybrid=, or =emacs=. It possible to pass a list of variables
|
||
as well with the keyword =:variables=, just like for layer variables.
|
||
|
||
*** Vim
|
||
Spacemacs behaves like in Vim using the [[https://github.com/emacs-evil/evil/][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=):
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(define-key evil-insert-state-map (kbd "C-]") 'forward-char)
|
||
#+END_SRC
|
||
|
||
When setting the Vim style you can pass any variable supported by =evil-mode=
|
||
with the keyword =:variables=. Spacemacs also supports the following editing
|
||
style variables for Vim:
|
||
|
||
| Variables | Description |
|
||
|------------------------------------------+-------------------------------------------------------------------------|
|
||
| =vim-style-visual-feedback= | If non-nil then objects are briefly highlighted |
|
||
| =vim-style-remap-Y-to-y$= | If non-nil ~Y~ is remapped to ~y$~ in Evil states |
|
||
| =vim-style-retain-visual-state-on-shift= | If non-nil, the shift mappings ~<~ and ~>~ retain visual state |
|
||
| =vim-style-visual-line-move-text= | If non-nil, ~J~ and ~K~ move lines up and down when in visual mode |
|
||
| =vim-style-ex-substitute-global= | If non-nil, inverse the meaning of ~g~ in =:substitute= Evil ex-command |
|
||
|
||
Default configuration is:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-editing-style '(vim :variables
|
||
vim-style-visual-feedback nil
|
||
vim-style-remap-Y-to-y$ nil
|
||
vim-style-retain-visual-state-on-shift t
|
||
vim-style-visual-line-move-text nil
|
||
vim-style-ex-substitute-global nil)
|
||
#+END_SRC
|
||
|
||
*** Emacs
|
||
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=):
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(define-key evil-emacs-state-map (kbd "C-]") 'forward-char)
|
||
#+END_SRC
|
||
|
||
*** Hybrid
|
||
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=):
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(define-key evil-hybrid-state-map (kbd "C-]") 'forward-char)
|
||
#+END_SRC
|
||
|
||
This style can be tweaked to be more like Emacs or more like Vim depending
|
||
on the user preferences. The following variables are available to change the
|
||
style configuration:
|
||
|
||
| Variables | Description |
|
||
|---------------------------------------+----------------------------------------------------------------------------------------|
|
||
| =hybrid-style-visual-feedback= | If non-nil then objects are briefly highlighted |
|
||
| =hybrid-style-default-state= | The default state when opening a new buffer. Set it to =emacs= for a more emacsy style |
|
||
| =hybrid-style-enable-hjkl-bindings= | If non-nil then packages will configure =h j k l= key bindings for navigation |
|
||
| =hybrid-style-enable-evilified-state= | If non-nil buffer are =evilified= when supported, if nil then =emacs= state is enabled |
|
||
| =hybrid-style-use-evil-search-module= | If non-nil then use evil own search module which is closer to Vim search behavior |
|
||
|
||
Default configuration is:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-editing-style '(hybrid :variables
|
||
hybrid-style-visual-feedback nil
|
||
hybrid-style-enable-evilified-state t
|
||
hybrid-style-enable-hjkl-bindings nil
|
||
hybrid-style-use-evil-search-module nil
|
||
hybrid-style-default-state 'normal)
|
||
#+END_SRC
|
||
|
||
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.
|
||
|
||
** States
|
||
Spacemacs has 10 states:
|
||
|
||
| State | Default Color | Description |
|
||
|--------------+---------------+------------------------------------------------------------------------------------------------------------|
|
||
| normal | orange | like the =normal mode of Vim=, used to execute and combine commands |
|
||
| insert | green | like the =insert mode of Vim=, used to actually insert text |
|
||
| visual | gray | like the =visual mode of Vim=, used to make text selection |
|
||
| motion | purple | exclusive to =Evil=, used to navigate read only buffers |
|
||
| emacs | blue | exclusive to =Evil=, using this state is like using a regular Emacs without Vim |
|
||
| replace | chocolate | like =replace mode of Vim=, overwrites the character under point instead of inserting a new one |
|
||
| hybrid | blue | exclusive to Spacemacs, this is like the insert state except that all the emacs key bindings are available |
|
||
| evilified | light brown | exclusive to Spacemacs, this is an =emacs state= modified to bring Vim navigation, selection and search. |
|
||
| lisp | pink | exclusive to Spacemacs, used to navigate Lisp code and modify it (more [[#editing-lisp-code][info]]) |
|
||
| iedit | red | exclusive to Spacemacs, used to navigate between multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]]) |
|
||
| iedit-insert | red | exclusive to Spacemacs, used to replace multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]]) |
|
||
*Note*: Technically speaking there is also the =operator= evil state.
|
||
|
||
** Evilified modes
|
||
Some buffers are not for editing text and provide their own key bindings for
|
||
certain operations. These often conflict with Vim bindings. To make such buffers
|
||
behave more like Vim in a consistent manner, they use a special state called
|
||
/evilified/ state. In evilified state, a handful of keys work as in Evil, namely
|
||
=/=, =:=, =h=, =j=, =k=, =l=, =n=, =N=, =v=, =V=, =gg=, =G=, =C-f=, =C-b=,
|
||
=C-d=, =C-e=, =C-u=, =C-y= and =C-z=. All other keys work as intended by the
|
||
underlying mode.
|
||
|
||
Shadowed keys are moved according to the pattern: =a= → =A= → =C-a= → =C-A=
|
||
|
||
For example, if the mode binds a function to =n=, that is found under =C-n= in
|
||
evilified state, since both =n= and =N= are reserved, but =C-n= is not. On the
|
||
other hand, anything originally bound to =k= will be found on =K=, since =k= is
|
||
reserved but =K= is not. If there is a binding on =K=, that will be moved to
|
||
=C-k=.
|
||
|
||
In addition to this, =C-g=, being an important escape key in Emacs, is skipped.
|
||
So anything bound to =g= originally will be found on =C-G=, since =g=, =G= and
|
||
=C-g= are all reserved.
|
||
|
||
** Evil leader
|
||
Spacemacs uses a leader key to bind almost all its key bindings.
|
||
|
||
This leader key is commonly set to ~,~ by Vim users. In Spacemacs the leader
|
||
key is set on ~SPC~ (the space bar, hence the name =spacemacs=). This key is the
|
||
most accessible key on a keyboard and it is pressed with the thumb which is a
|
||
good choice to lower the risk of [[https://en.wikipedia.org/wiki/Repetitive_strain_injury][RSI]]. It can be customized to any other key
|
||
using the variable =dotspacemacs-leader-key= and =dotspacemacs-emacs-leader-key=.
|
||
|
||
With Spacemacs there is no need to remap your keyboard modifiers to attempt
|
||
to reduce the risk of RSI, every command can be executed very easily while you
|
||
are in =normal= mode by pressing the ~SPC~ leader key, here are a few examples:
|
||
- Save a buffer: ~SPC f s~
|
||
- Save all opened buffers: ~SPC f S~
|
||
- Open (switch) to a buffer: ~SPC b b~
|
||
|
||
** Universal argument
|
||
The universal argument ~C-u~ is an important command in Emacs but it is also a
|
||
very handy Vim key binding to scroll up.
|
||
|
||
Spacemacs binds ~C-u~ to =scroll-up= and changes the universal argument binding
|
||
to ~SPC u~.
|
||
|
||
** Transient-states
|
||
Spacemacs defines a wide variety of =transient states= (temporary overlay maps)
|
||
where it makes sense. This prevents one from doing repetitive and tedious
|
||
presses on the ~SPC~ key.
|
||
|
||
When a =transient state= is active, documentation is displayed in the
|
||
minibuffer. Additional information may also be displayed in the minibuffer.
|
||
|
||
Auto-highlight-symbol transient state:
|
||
[[file:img/spacemacs-ahs-transient-state.png]]
|
||
[[#text][Text scale transient state]]:
|
||
|
||
[[file:img/spacemacs-scale-transient-state.png]]
|
||
|
||
** Toggles
|
||
Spacemacs tries to unify the interface to handle toggles using a custom macro
|
||
called =spacemacs|add-toggle=.
|
||
|
||
There exists two type of toggles:
|
||
- globally available toggles under the key prefixes ~SPC t~ and ~SPC T~
|
||
- major mode specific toggles under the key prefix ~SPC m T~
|
||
|
||
When a toggle is turned on a unicode symbol is displayed in the mode-line, this
|
||
symbol is a circled letter for globally available toggles and a plain squared
|
||
letter for major mode specific toggles. The letter corresponds to the key
|
||
binding for this toggle.
|
||
|
||
For instance the globally available toggle for =which-key= is under ~SPC t K~
|
||
and its corresponding symbol in the mode-line is =Ⓚ=. Also the major mode
|
||
specific toggle for =nameless= available only in =emacs-lisp= mode is under
|
||
~SPC m T n~ and its corresspoding symbol in the mode-line is =🅽=.
|
||
|
||
All toggles can be browsed via the Spacemacs help system under ~SPC h t~.
|
||
|
||
*** Configuring toggles in the dotfile
|
||
To set the toggle states to your preference you can use a set of functions
|
||
that should be called in your =dotspacemacs/user-config= function of your
|
||
dotfile.
|
||
|
||
Globally available toggles can be turned on and off using the functions
|
||
=spacemacs/toggle-NAME-on= and =spacemacs/toggle-NAME-off= respectively.
|
||
=NAME= corresponds to the name of the toggle, for instance =which-key=
|
||
for the toggle to turn on and off the =which-key= minor mode.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(spacemacs/toggle-which-key-on)
|
||
#+END_SRC
|
||
|
||
Major mode specific toggles can be turned on by registering a hook on them to
|
||
call the “toggle on” function automatically whenever a buffer using this major
|
||
mode is opened. It can be done convenienty using the function
|
||
=spacemacs/toggle-NAME-on-register-hooks=. It also exists variants of this
|
||
function for each supported major mode like
|
||
=spacemacs/toggle-NAME-on-register-hook-MODE=.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(spacemacs/toggle-nameless-on-register-hooks)
|
||
;; or to enable it for emacs-lips buffers only
|
||
(spacemacs/toggle-nameless-on-register-hook-emacs-lisp-mode)
|
||
#+END_SRC
|
||
|
||
* Differences between Vim, Evil and Spacemacs
|
||
- The ~,~ key does repeat last ~f~, ~t~, ~F~, or ~T~ command in
|
||
opposite direction in =Vim=, but in Spacemacs it is the major mode specific
|
||
leader key by default (which can be set on another key binding in the
|
||
dotfile).
|
||
|
||
Send a PR to add the differences you found in this section.
|
||
|
||
** The vim-surround case
|
||
There is one obvious visible difference though. It is not between =Evil= and
|
||
=Vim= but between Spacemacs and [[https://github.com/tpope/vim-surround][vim-surround]]: in visual mode the =surround=
|
||
command is on ~S~ in =vim-surround= whereas it is on ~s~ in Spacemacs.
|
||
|
||
This is something that can surprise some Vim users so here are some motivations
|
||
behind this change:
|
||
- ~s~ and ~c~ do the same thing in =visual state=,
|
||
- ~s~ is only useful to delete /one/ character and add more than one character
|
||
which is a /very/ narrow use case
|
||
- ~c~ accept motions and can do everything ~s~ can do in =normal state=
|
||
(note that this is also true for ~r~ but ~r~ is more useful because it
|
||
stays in =normal state=)
|
||
- =surround= command is just a more powerful command than ~s~.
|
||
|
||
If you are not convinced, then here is the snippet to revert back to the default
|
||
=Vim + vim-surround= setup (add it to your =dotspacemacs/user-config=):
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(evil-define-key 'visual evil-surround-mode-map "s" 'evil-substitute)
|
||
(evil-define-key 'visual evil-surround-mode-map "S" 'evil-surround-region)
|
||
#+END_SRC
|
||
|
||
* Evil plugins
|
||
Spacemacs ships with the following evil plugins:
|
||
|
||
| Mode | Description |
|
||
|-------------------------------+--------------------------------------------|
|
||
| [[https://github.com/wcsmith/evil-args][evil-args]] | motions and text objects for arguments |
|
||
| [[https://github.com/Dewdrops/evil-exchange][evil-exchange]] | port of [[https://github.com/tommcdo/vim-exchange][vim-exchange]] |
|
||
| [[https://github.com/cofi/evil-indent-textobject][evil-indent-textobject]] | add text object based on indentation level |
|
||
| [[https://github.com/redguardtoo/evil-matchit][evil-matchit]] | port of [[http://www.vim.org/scripts/script.php?script_id=39][matchit.vim]] |
|
||
| [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commenter]] | port of [[https://github.com/scrooloose/nerdcommenter][nerdcommenter]] |
|
||
| [[https://github.com/cofi/evil-numbers][evil-numbers]] | like ~C-a~ and ~C-x~ in vim |
|
||
| [[https://github.com/juanjux/evil-search-highlight-persist][evil-search-highlight-persist]] | emulation of hlsearch behavior |
|
||
| [[https://github.com/timcharper/evil-surround][evil-surround]] | port of [[https://github.com/tpope/vim-surround][vim-surround]] |
|
||
| [[https://github.com/bling/evil-visualstar][evil-visualstar]] | search for current selection with ~*~ |
|
||
| [[https://github.com/Alexander-Miller/treemacs][Treemacs]] | a file explorer like [[https://github.com/scrooloose/nerdtree][NERD Tree]] |
|
||
|
||
* Environment variables and PATH
|
||
Environment variables are handled by the function =dotspacemacs/user-env= of
|
||
your dotfile.
|
||
|
||
** Default behavior
|
||
By default, the function =dotspacemacs/user-env= only calls the function
|
||
=spacemacs/load-spacemacs-env= which loads the environment variables from
|
||
the file =~/.spacemacs.env=. This file is automatically created for you by
|
||
Spacemacs and it is initialized with the environment variables of your
|
||
system as well as the environment variables of your default shell.
|
||
|
||
To open this file use ~SPC f e e~. You can edit it to change or add/remove
|
||
environment variables. Use ~SPC f e E~ to reload it.
|
||
|
||
Some dynamic environment variables are ignored by Spacemacs when it first
|
||
creates the =~/.spacemacs.env= file. These ignored variables are listed in
|
||
the variable =spacemacs-ignored-environment-variables=.
|
||
|
||
It is possible to force a new import of system and shell environment variables
|
||
with ~SPC f e C-e~. Note that this action will overwrite =~/.spacemacs.env=.
|
||
|
||
** Managing environment variables by yourself
|
||
For full flexibility you can bypass the default behavior simply by removing
|
||
the call to =spacemacs/load-spacemacs-env= from your =dotspacemacs/user-env=
|
||
function.
|
||
|
||
From there you can choose to use the popular package =exec-path-from-shell=
|
||
or just call built-in functions like =setenv= or =(add-to-list 'exec-path ...)=.
|
||
|
||
If you choose to handle the environment variables by yourself then ~SPC f e e~
|
||
will go to the function =dotspacemacs/user-env= instead of opening the file
|
||
=~/.spacemacs.env=. In all cases ~SPC f e E~ calls the function
|
||
=dotspacemacs/user-env= so you can update your variables in place.
|
||
|
||
** Note about the function dotspacemacs/user-env
|
||
Its possible that you don’t have this function defined if you have an older
|
||
dotfile. It is recommended to update your dotfile by adding this function,
|
||
see the file =~/.emacs.d/core/template/.spacemacs.template= to copy it.
|
||
If you don’t create such function then Spacemacs assumes you are using the
|
||
default behavior described above.
|
||
|
||
* Binding keys
|
||
Key sequences are bound to commands in Emacs in various keymaps. The most basic
|
||
map is the =global-map=. Setting a key binding in the =global-map= is achieved
|
||
with the function =global-set-key=. Example to bind a key to the command
|
||
=forward-char=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(global-set-key (kbd "C-]") 'forward-char)
|
||
#+END_SRC
|
||
|
||
The =kbd= macro accepts a string describing a key sequence. The =global-map= is
|
||
often shadowed by other maps. For example, =evil-mode= defines keymaps that
|
||
target states (or modes in vim terminology). Here is an example that creates the
|
||
same binding as above but only in =insert state= (=define-key= is a built-in
|
||
function. =Evil-mode= has its own functions for defining keys).
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(define-key evil-insert-state-map (kbd "C-]") 'forward-char)
|
||
#+END_SRC
|
||
|
||
Perhaps most importantly for Spacemacs is the use of the bind-map package to
|
||
bind keys behind a leader key.
|
||
This is where most of the Spacemacs bindings live. Binding keys behind the
|
||
leader key is achieved with the functions =spacemacs/set-leader-keys= and
|
||
=spacemacs/set-leader-keys-for-major-mode=, example:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(spacemacs/set-leader-keys "C-]" 'forward-char)
|
||
(spacemacs/set-leader-keys-for-major-mode 'emacs-lisp-mode "C-]" 'forward-char)
|
||
#+END_SRC
|
||
|
||
These functions use a macro like =kbd= to translate the key sequences for you.
|
||
The second function, =spacemacs/set-leader-keys-for-major-mode=, binds the key
|
||
only in the specified mode. The second key binding is active only when the
|
||
major mode is =emacs-lisp=.
|
||
|
||
Finally, one should be aware of prefix keys. Essentially, all keymaps can be
|
||
nested. Nested keymaps are used extensively in spacemacs, and in vanilla Emacs
|
||
for that matter. For example, ~SPC a~ points to key bindings for “applications”,
|
||
like ~SPC a c~ for =calc-dispatch=. Nesting bindings is easy.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(spacemacs/declare-prefix "]" "bracket-prefix")
|
||
(spacemacs/set-leader-keys "]]" 'double-bracket-command)
|
||
#+END_SRC
|
||
|
||
The first line declares ~SPC ]~ to be a prefix and the second binds the key
|
||
sequence ~SPC ]]~ to the corresponding command. The first line is actually
|
||
unnecessary to create the prefix, but it will give your new prefix a name that
|
||
key-discovery tools can use (e.g., which-key).
|
||
|
||
There is much more to say about bindings keys, but these are the basics. Keys
|
||
can be bound in your =~/.spacemacs= file or in individual layers.
|
||
|
||
* GUI Elements
|
||
Spacemacs has a minimalistic and distraction free graphical UI:
|
||
- custom [[https://github.com/milkypostman/powerline][powerline]] mode-line [[#flycheck-integration][with color feedback]] according to current [[https://github.com/flycheck/flycheck][Flycheck]] status
|
||
- Unicode symbols for minor mode lighters which appear in the mode-line
|
||
- [[#errors-handling][custom fringe bitmaps]] and error feedbacks for [[https://github.com/flycheck/flycheck][Flycheck]]
|
||
|
||
** Color themes
|
||
*** Default theme
|
||
The official Spacemacs theme is [[https://github.com/nashamri/spacemacs-theme][spacemacs-dark]] and it is the default theme
|
||
installed when you first started Spacemacs. There are two variants of the
|
||
theme, a dark one and a light one. Some aspects of these themes can be customized
|
||
in the function =dotspacemacs/user-init= of your =~/.spacemacs=:
|
||
- the comment background with the boolean =spacemacs-theme-comment-bg=
|
||
- the height of org section titles with =spacemacs-theme-org-height=
|
||
|
||
*** Choosing themes
|
||
It is possible to define your default themes in your =~/.spacemacs= with the
|
||
variable =dotspacemacs-themes=. For instance, to specify =spacemacs-light=,
|
||
=leuven= and =zenburn=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-themes '(spacemacs-light leuven zenburn))
|
||
#+END_SRC
|
||
=dotspacemacs-themes= entries accept the same properties as packages listed
|
||
in layers package lists or in =dotspacemacs-additional-packages=. So it is
|
||
possible to fetch a package from a specific location. For example, you could
|
||
fetch =zenburn= theme directly from the GitHub repository with the following
|
||
declaration:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-themes
|
||
'(spacemacs-light
|
||
leuven
|
||
(zenburn :location (recipe :fetcher github
|
||
:repo "bbatsov/zenburn-emacs"))
|
||
))
|
||
#+END_SRC
|
||
*Important note:* If you use =:location local= then you have to put your theme
|
||
in the directory =private/local/<theme-package-name>/= with =theme-package-name=
|
||
being the name of your package suffixed with =-theme= as mentioned in the Emacs
|
||
conventions.
|
||
For instance if your theme is =foo= then you have to put our theme
|
||
files in the directory =private/local/foo-theme=.
|
||
|
||
You can cycle between the themes declared in =dotspacemacs-themes= with
|
||
~SPC T n~ and select an installed theme with ~SPC T s~.
|
||
|
||
**** Themes Transient State
|
||
|
||
| Key binding | Description |
|
||
|------------------+-----------------------------------------------|
|
||
| ~n~ or ~<right>~ | change to the next theme |
|
||
| ~p~ or ~<left>~ | change to the previous theme |
|
||
| ~t~ or ~<up>~ | open helm-themes to select an installed theme |
|
||
|
||
*** Browsing themes
|
||
You can see samples of all themes included in the =themes-megapack= layer
|
||
in this [[http://themegallery.robdor.com][theme gallery]] from [[https://twitter.com/robmerrell][Rob Merrell]].
|
||
|
||
*** Notes
|
||
- You don’t need to explicitly list in a layer the theme packages you are
|
||
defining in =dotspacemacs-themes=, Spacemacs is smart enough to remove those
|
||
packages from the list of orphans.
|
||
- Due to the inner working of themes in Emacs, switching theme during the same
|
||
session may have some weird side effects. Although these side effects should
|
||
be pretty rare.
|
||
- In the terminal version of Emacs, color themes will not render correctly as
|
||
colors are rendered by the terminal and not by emacs. You will probably have
|
||
to change your terminal color palette. More explanations can be found on
|
||
[[https://github.com/sellout/emacs-color-theme-solarized#important-note-for-terminal-users][emacs-color-theme-solarized webpage]].
|
||
|
||
** Font
|
||
The default font used by Spacemacs is [[https://github.com/adobe-fonts/source-code-pro][Source Code Pro]] by Adobe. It is
|
||
recommended to install it on your system if you wish to use it.
|
||
|
||
To change the default font set the variable =dotspacemacs-default-font= in your
|
||
=.spacemacs= file. By default its value is:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-default-font '("Source Code Pro"
|
||
:size 13
|
||
:weight normal
|
||
:width normal))
|
||
#+END_SRC
|
||
|
||
If the specified font is not found, the fallback one will be used (depends on
|
||
your system). Also note that changing this value has no effect if you are
|
||
running Emacs in terminal.
|
||
|
||
The properties should be pretty straightforward, it is possible to set any valid
|
||
property of a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Low_002dLevel-Font.html][font-spec]]:
|
||
- =:family= Font family or fontset (a string).
|
||
- =:width= Relative character width. This should be one of the symbols:
|
||
- ultra-condensed
|
||
- extra-condensed
|
||
- condensed
|
||
- semi-condensed
|
||
- normal
|
||
- semi-expanded
|
||
- expanded
|
||
- extra-expanded
|
||
- ultra-expanded
|
||
- =:height= The height of the font. In the simplest case, this is an integer
|
||
in units of 1/10 point.
|
||
- =:weight= Font weight- one of the symbols (from densest to faintest):
|
||
- ultra-bold
|
||
- extra-bold
|
||
- bold
|
||
- semi-bold
|
||
- normal
|
||
- semi-light
|
||
- light
|
||
- extra-light
|
||
- ultra-light
|
||
- =:slant= Font slant- one of the symbols:
|
||
- italic
|
||
- oblique
|
||
- normal
|
||
- reverse-italic
|
||
- reverse-oblique
|
||
- =:size= The font size- either a non-negative integer that specifies the
|
||
pixel size, or a floating-point number that specifies the point size.
|
||
- =:adstyle= Additional typographic style information for the font, such as
|
||
’sans’. The value should be a string or a symbol.
|
||
- =:registry= The charset registry and encoding of the font, such as
|
||
’iso8859-1’. The value should be a string or a symbol.
|
||
- =:script= The script that the font must support (a symbol).
|
||
|
||
** GUI Toggles
|
||
Some graphical UI indicators can be toggled on and off (toggles start with ~t~
|
||
and ~T~):
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------------------------------|
|
||
| ~SPC t 8~ | highlight any character past the 80th column |
|
||
| ~SPC t f~ | display the fill column (by default the fill column is set to 80) |
|
||
| ~SPC t h h~ | toggle highlight of the current line |
|
||
| ~SPC t h i~ | toggle highlight indentation levels |
|
||
| ~SPC t h c~ | toggle highlight indentation current column |
|
||
| ~SPC t h s~ | toggle syntax highlighting |
|
||
| ~SPC t i~ | toggle indentation guide at point |
|
||
| ~SPC t l~ | toggle truncate lines |
|
||
| ~SPC t L~ | toggle visual lines |
|
||
| ~SPC t n~ | toggle line numbers |
|
||
| ~SPC t v~ | toggle smooth scrolling |
|
||
| ~SPC t z~ | toggle 0/1 based column indexing |
|
||
|
||
| Key binding | Description |
|
||
|-------------+------------------------------------------------------------------|
|
||
| ~SPC T ~~ | display =~= in the fringe on empty lines |
|
||
| ~SPC T F~ | toggle frame fullscreen |
|
||
| ~SPC T f~ | toggle display of the fringe |
|
||
| ~SPC T m~ | toggle menu bar |
|
||
| ~SPC T M~ | toggle frame maximize |
|
||
| ~SPC T t~ | toggle tool bar |
|
||
| ~SPC T T~ | toggle frame transparency and enter transparency transient state |
|
||
*Note*: These toggles are all available via the =spacemacs-help= interfaces
|
||
(press ~SPC h SPC~ to display the =spacemacs-help= buffer).
|
||
|
||
*** Global line numbers
|
||
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 =t=.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-line-numbers t)
|
||
#+END_SRC
|
||
|
||
If it is set to =relative=, line numbers are show in a relative way:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-line-numbers 'relative)
|
||
#+END_SRC
|
||
=dotspacemacs-line-numbers= can also be set to a property list for finer control
|
||
over line numbers activation.
|
||
|
||
Available properties:
|
||
|
||
| Property | Description |
|
||
|-----------------------+----------------------------------------------------------------------------------------------|
|
||
| =:disabled-for-modes= | list of major modes where line numbering is inhibited |
|
||
| =:enabled-for-modes= | disable for all major modes except those listed. Takes precedence over =:disabled-for-modes= |
|
||
| =:relative= | if non-nil, line numbers are relative to the position of the cursor |
|
||
| =:size-limit-kb= | size limit in kilobytes after which line numbers are not activated |
|
||
|
||
Note that if =:enabled-for-modes= is =nil= or not specified, then the default is
|
||
to enable line numbers in any =prog-mode= and =text-mode= that wasn’t explicitly
|
||
disabled via =:disabled-for-modes=. To enable line numbers in a major mode that
|
||
doesn’t derive from =prog-mode= or =text-mode=, you must specify it directly in
|
||
=:enabled-for-modes=. To enable line numbers even in non-prog-mode and
|
||
non-text-mode buffers, set =:enabled-for-modes= to =all=.
|
||
|
||
Examples:
|
||
|
||
Disable *line numbers* in dired-mode, doc-view-mode, markdown-mode, org-mode,
|
||
pdf-view-mode, text-mode as well as buffers over 1Mb:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-line-numbers '(:relative nil
|
||
:disabled-for-modes dired-mode
|
||
doc-view-mode
|
||
markdown-mode
|
||
org-mode
|
||
pdf-view-mode
|
||
text-mode
|
||
:size-limit-kb 1000))
|
||
#+END_SRC
|
||
|
||
Enable *relative line numbers* only in c-mode and c++ mode with a size limit of =dotspacemacs-large-file-size=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-line-numbers '(:relative t
|
||
:enabled-for-modes c-mode
|
||
c++-mode
|
||
:size-limit-kb (* dotspacemacs-large-file-size 1000))
|
||
#+END_SRC
|
||
|
||
Enable *line numbers* everywhere, except for buffers over 1Mb:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-line-numbers '(:relative nil
|
||
:size-limit-kb 1000))
|
||
#+END_SRC
|
||
|
||
Enable *line numbers* only in programming modes, except for c-mode and c++ mode:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-line-numbers '(:relative nil
|
||
:enabled-for-modes prog-mode
|
||
:disabled-for-modes c-mode c++-mode
|
||
:size-limit-kb (* dotspacemacs-large-file-size 1000))
|
||
#+END_SRC
|
||
|
||
Enable *line numbers* everywhere, even in non-prog-mode and non-text-mode buffers:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-line-numbers '(:enabled-for-modes 'all))
|
||
#+END_SRC
|
||
|
||
** Mode-line
|
||
*** Mode-line themes
|
||
Spacemacs supports different mode-line themes. The mode-line theme is set in the
|
||
dotfile with the variable =dotspacemacs-mode-line-theme=.
|
||
|
||
Currently supported themes are:
|
||
- spaceline themes: =spacemacs=, =all-the-icons=, =custom=
|
||
- a powerline theme: =vim-powerline=
|
||
- no theme at all: =vanilla=
|
||
|
||
The default theme is =spacemacs= and this theme is described in more detailed in
|
||
the next section.
|
||
=all-the-icons= is the theme defined in the package [[https://github.com/domtronn/spaceline-all-the-icons.el][spaceline-all-the-icons]].
|
||
=custom= is a user custom spaceline theme, see the guide in the following section.
|
||
=vim-powerline= is for the Vim users who are nostalgic of the good old Vim
|
||
powerline.
|
||
=vanilla= is the stock mode-line that comes with Emacs.
|
||
|
||
*** Separators
|
||
For =spacemacs=, =all-the-icons= and =custom= themes you can specify the type
|
||
of separator you want with the property =:separator=.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq dotspacemacs-mode-line-theme '(all-the-icons :separator 'slant))
|
||
#+END_SRC
|
||
|
||
Supported separators and preview:
|
||
|
||
| Separator | Spacemacs | All-the-icons | Screenshot |
|
||
|--------------+-----------+---------------+-----------------------------------|
|
||
| =alternate= | X | | [[file:img/powerline-alternate.png]] |
|
||
| =arrow= | X | X | [[file:img/powerline-arrow.png]] |
|
||
| =arrow-fade= | X | | [[file:img/powerline-arrow-fade.png]] |
|
||
| =bar= | X | | [[file:img/powerline-bar.png]] |
|
||
| =box= | X | | [[file:img/powerline-box.png]] |
|
||
| =brace= | X | | [[file:img/powerline-brace.png]] |
|
||
| =butt= | X | | [[file:img/powerline-butt.png]] |
|
||
| =chamfer= | X | | [[file:img/powerline-chamfer.png]] |
|
||
| =contour= | X | | [[file:img/powerline-contour.png]] |
|
||
| =cup= | | X | |
|
||
| =curve= | X | | [[file:img/powerline-curve.png]] |
|
||
| =rounded= | X | | [[file:img/powerline-rounded.png]] |
|
||
| =roundstub= | X | | [[file:img/powerline-roundstub.png]] |
|
||
| =slant= | X | X | [[file:img/powerline-slant.png]] |
|
||
| =wave= | X | X | [[file:img/powerline-wave.png]] |
|
||
| =zigzag= | X | | [[file:img/powerline-zigzag.png]] |
|
||
| =nil= | X | | [[file:img/powerline-nil.png]] |
|
||
| =none= | | X | |
|
||
|
||
A last special separator is supported, it is =utf-8= which uses actual font
|
||
glyphs so it can be rendered in a terminal. You’ll need a font patched for the
|
||
Vim powerline to be able to use it. The default font used by Spacemacs =Source
|
||
Code Pro= already contains the glyphs.
|
||
|
||
*** Separator scale
|
||
For =spacemacs=, =all-the-icons= and =custom= themes you can specify the size of
|
||
the separator with the property =:separator-scale=. It allows to avoid crappy
|
||
rendering of the separators like on the following screenshot.
|
||
|
||
[[file:img/crappy-powerline-separators.png]]
|
||
/Ugly separators/
|
||
|
||
Example:
|
||
|
||
#+BEGIN_SRC elisp
|
||
(setq dotspacemacs-mode-line-theme '(all-the-icons :separator-scale 1.5))
|
||
#+END_SRC
|
||
|
||
Note that this setting won’t work correctly when the separator is =utf-8=, if
|
||
you use this separator then it is recommended to set =:separator-scale= to =1.0=.
|
||
|
||
*** Spacemacs mode-line theme
|
||
This theme is a heavily customized [[https://github.com/milkypostman/powerline][powerline]] using [[https://github.com/TheBB/spaceline][spaceline]].
|
||
It has the following capabilities among others:
|
||
- show the window number
|
||
- color code for current state
|
||
- show the number of search occurrences via anzu
|
||
- toggle flycheck info
|
||
- toggle battery info
|
||
- toggle minor mode lighters
|
||
|
||
Reminder of the color codes for the states:
|
||
|
||
| Evil State | Color |
|
||
|--------------------+-----------|
|
||
| Normal | Orange |
|
||
| Insert | Green |
|
||
| Visual | Grey |
|
||
| Emacs | Blue |
|
||
| Motion | Purple |
|
||
| Replace | Chocolate |
|
||
| Lisp | Pink |
|
||
| Iedit/Iedit-Insert | Red |
|
||
|
||
Some elements can be dynamically toggled:
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------------------|
|
||
| ~SPC t m b~ | toggle the battery status |
|
||
| ~SPC t m c~ | toggle the =org= task clock (available in =org= layer) |
|
||
| ~SPC t m m~ | toggle the minor mode lighters |
|
||
| ~SPC t m M~ | toggle the major mode |
|
||
| ~SPC t m n~ | toggle the cat! (if =colors= layer is declared in your dotfile) |
|
||
| ~SPC t m p~ | toggle the point character position |
|
||
| ~SPC t m r~ | toggle responsivness of the mode-line |
|
||
| ~SPC t m s~ | toggle system monitor (displayed in the minibuffer) |
|
||
| ~SPC t m t~ | toggle the time |
|
||
| ~SPC t m T~ | toggle the mode line itself |
|
||
| ~SPC t m v~ | toggle the version control info |
|
||
| ~SPC t m V~ | toggle the new version lighter |
|
||
|
||
**** Flycheck integration
|
||
When [[https://github.com/flycheck/flycheck][Flycheck]] minor mode is enabled, a new element appears showing the number of
|
||
errors, warnings and info.
|
||
|
||
[[file:img/powerline-wave.png]]
|
||
/Flycheck integration in mode-line/
|
||
|
||
**** Anzu integration
|
||
[[https://github.com/syohex/emacs-anzu][Anzu]] shows the number of occurrence when performing a search. Spacemacs
|
||
integrates the Anzu status nicely by displaying it temporarily when ~n~ or ~N~
|
||
are being pressed. See the =5/6= segment on the screenshot below.
|
||
|
||
[[file:img/powerline-anzu.png]]
|
||
/Anzu integration in mode-line/
|
||
|
||
**** Battery status integration
|
||
[[https://github.com/lunaryorn/fancy-battery.el][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:
|
||
|
||
| Battery State | Color |
|
||
|---------------+--------|
|
||
| Charging | Green |
|
||
| Discharging | Orange |
|
||
| Critical | Red |
|
||
*Note*: These colors may vary depending on your theme.
|
||
|
||
*** All-the-Icons theme
|
||
If you want to use this theme you need to make sure to install the required
|
||
fonts from the package repository, see [[https://github.com/domtronn/all-the-icons.el/tree/master/fonts][all-the-icons fonts directory]].
|
||
|
||
*** Custom spaceline theme
|
||
You can create your own Spaceline theme by setting the variable
|
||
=dotspacemacs-mode-line-theme= to =custom= and define a function called
|
||
=spaceline-custom-theme= in your =dotspacemacs/user-init= function of your
|
||
dotfile. This functions must accept a variadic number of arguments which are
|
||
additional segments added by Spacemacs (like a segment to notify about available
|
||
updates etc...).
|
||
|
||
Example:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun spaceline-custom-theme (&rest additional-segments)
|
||
"My custom spaceline theme."
|
||
(spaceline-compile
|
||
`(major-mode (minor-modes :when active) buffer-id)
|
||
`((line-column :separator " | " :priority 3)
|
||
,@additional-segments))
|
||
(setq-default mode-line-format '("%e" (:eval (spaceline-ml-main)))))
|
||
#+END_SRC
|
||
|
||
Restart Emacs and enjoy your very own mode-line!
|
||
|
||
*** Minor Modes
|
||
Spacemacs uses [[https://www.emacswiki.org/emacs/DiminishedModes][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.
|
||
|
||
Additionally all globally available toggles have a circled unicode symbols like
|
||
=ⓟ=. Toggles specific to a major mode under the ~SPC m T~ prefix have plain
|
||
squared symbols like =🅿=.
|
||
|
||
| Key binding | Unicode | ASCII | Mode |
|
||
|-------------+---------+-------+----------------------------------------------------------------------|
|
||
| ~SPC t -~ | =⊝= | - | [[https://www.emacswiki.org/emacs/centered-cursor-mode.el][centered-cursor]] mode |
|
||
| ~SPC t 8~ | =⑧= | 8 | toggle highlight of characters for long lines |
|
||
| ~SPC t C-8~ | =⑧= | 8 | global toggle highlight of characters for long lines |
|
||
| ~SPC t C--~ | =⊝= | - | global centered cursor |
|
||
| ~SPC t a~ | =ⓐ= | a | auto-completion |
|
||
| ~SPC t c~ | =ⓒ= | c | camel case motion with subword mode |
|
||
| =none= | =ⓔ= | e | [[https://github.com/edwtjo/evil-org-mode][evil-org]] mode |
|
||
| ~SPC t E e~ | =Ⓔe= | Ee | emacs editing style (holy mode) |
|
||
| ~SPC t E h~ | =Ⓔh= | Eh | hybrid editing style (hybrid mode) |
|
||
| ~SPC t f~ | =ⓕ= | f | fill-column-indicator mode |
|
||
| ~SPC t F~ | =Ⓕ= | F | auto-fill mode |
|
||
| ~SPC t G~ | =Ⓖ= | G | [[http://spacemacs.org/layers/+tags/gtags/README.html][ggtags]] mode |
|
||
| ~SPC t g~ | =ⓖ= | g | [[https://github.com/roman/golden-ratio.el][golden-ratio]] mode |
|
||
| ~SPC t h i~ | =ⓗi= | hi | toggle highlight indentation levels |
|
||
| ~SPC t h c~ | =ⓗc= | hc | toggle highlight indentation current column |
|
||
| ~SPC t i~ | =ⓘ= | i | indentation guide |
|
||
| ~SPC t C-i~ | =ⓘ= | i | global indentation guide |
|
||
| ~SPC t I~ | =Ⓘ= | I | aggressive indent mode |
|
||
| ~SPC t K~ | =Ⓚ= | K | which-key mode |
|
||
| ~SPC t p~ | =ⓟ= | p | [[https://github.com/Fuco1/smartparens][smartparens]] mode |
|
||
| ~SPC t C-p~ | =ⓟ= | p | global smartparens |
|
||
| ~SPC t s~ | =ⓢ= | s | syntax checking (flycheck) |
|
||
| ~SPC t S~ | =Ⓢ= | S | enabled in [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Bcheckers/spell-checking/README.org][spell checking layer]] (flyspell) |
|
||
| ~SPC t w~ | =ⓦ= | w | whitespace mode |
|
||
| ~SPC t C-w~ | =ⓦ= | w | global whitespace |
|
||
| ~SPC t W~ | =Ⓦ= | W | automatic whitespace cleanup (see =dotspacemacs-whitespace-cleanup=) |
|
||
| ~SPC t C-W~ | =Ⓦ= | W | automatic whitespace cleanup globally |
|
||
| ~SPC t y~ | =ⓨ= | y | [[https://github.com/capitaomorte/yasnippet][yasnippet]] mode |
|
||
|
||
** Frame title
|
||
Default frame title displays name of current process and hostname of system. You
|
||
can include more information (like name of current file, name of current project
|
||
etc) by setting =dotspacemacs-frame-title-format= variable.
|
||
|
||
Following format short codes are available:
|
||
|
||
| Code | Description |
|
||
|------+------------------------------------------------------------------------------|
|
||
| =%a= | the =abbreviated-file-name=, or =buffer-name= |
|
||
| =%t= | =projectile-project-name= |
|
||
| =%I= | =invocation-name= |
|
||
| =%S= | =system-name= |
|
||
| =%U= | contents of $USER |
|
||
| =%b= | buffer name |
|
||
| =%f= | visited file name |
|
||
| =%F= | frame name |
|
||
| =%s= | process status |
|
||
| =%p= | percent of buffer above top of window, or Top, Bot or All |
|
||
| =%P= | percent of buffer above bottom of window, perhaps plus Top, or Bottom or All |
|
||
| =%m= | mode name |
|
||
| =%n= | Narrow if appropriate |
|
||
| =%z= | mnemonics of buffer, terminal, and keyboard coding systems |
|
||
| =%Z= | like %z, but including the end-of-line format“ |
|
||
|
||
*** Iconified (tabified) title
|
||
If you are using tiling window manager with tab support you may want to display
|
||
different title for inactive tabs with =dotspacemacs-icon-title-format=
|
||
variable. Short codes are same as for frame title.
|
||
|
||
If this variable is set to =nil= (default) its value will be same as
|
||
=dotspacemacs-frame-title-format=.
|
||
|
||
* Layouts and workspaces
|
||
Layouts are window configurations with buffer isolation. Each layout can define
|
||
several workspaces (think of them as sub-layouts), sharing the same list of
|
||
buffers as their parent layout.
|
||
|
||
** Layouts
|
||
A layout is a window configuration associated with a list of buffers. The list
|
||
of buffers can be an arbitrarily chosen set of buffers. Spacemacs provides
|
||
some facilities to create meaningful sets of buffers, for instance the buffers
|
||
related to a projectile project.
|
||
|
||
The name of the current layout appears in the mode-line at the far left (first
|
||
element of the mode-line).
|
||
|
||
To create a new layout, type a layout number that does not exist yet.
|
||
For instance if you have two layouts currently then type ~SPC l 3~ to create a
|
||
third layout.
|
||
|
||
*** The default layout
|
||
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.
|
||
|
||
*** Project layouts
|
||
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
|
||
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:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(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)))
|
||
#+END_SRC
|
||
|
||
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:
|
||
|
||
| Name | Key binding | Description |
|
||
|------------+-------------+---------------------------------------------------------------------------------|
|
||
| @Spacemacs | ~e~ | Custom perspective containing all buffers of =~/.emacs.d= |
|
||
| @Mu4e | ~m~ | Custom perspective containing all mu4e buffers (needs the mu4e layer enabled) |
|
||
| @ERC | ~E~ | Custom perspective containing all ERC buffers (needs the erc layer enabled) |
|
||
| @RCIRC | ~i~ | Custom perspective containing all RCIRC buffers (needs the rcirc layer enabled) |
|
||
| @Slack | ~s~ | Custom perspective containing all Slack buffers (needs the slack layer enabled) |
|
||
| @Org | ~o~ | Custom perspective containing all the =org-agenda= buffers |
|
||
|
||
*** Save/Load layouts into a file
|
||
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.
|
||
|
||
*** Layout key bindings
|
||
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.
|
||
|
||
| Key binding | Description |
|
||
|---------------------+------------------------------------------------------------|
|
||
| ~SPC l~ | initiate transient state |
|
||
| ~?~ | toggle the documentation |
|
||
| ~[0..9]~ | switch to nth layout |
|
||
| ~[C-0..C-9]~ | switch to nth layout and keep the transient state active |
|
||
| ~<tab>~ | switch to the latest layout |
|
||
| ~a~ | add a buffer to the current layout |
|
||
| ~A~ | add all the buffers from another layout in the current one |
|
||
| ~b~ | select a buffer in the current layout |
|
||
| ~d~ | delete the current layout and keep its buffers |
|
||
| ~D~ | delete the other layouts and keep their buffers |
|
||
| ~h~ | go to default layout |
|
||
| ~l~ | select/create a layout |
|
||
| ~L~ | load layouts from file |
|
||
| ~n~ or ~C-l~ | next layout in list |
|
||
| ~N~ or ~p~ or ~C-h~ | previous layout in list |
|
||
| ~o~ | open a custom layout |
|
||
| ~r~ | remove current buffer from layout |
|
||
| ~R~ | rename current layout |
|
||
| ~s~ | save layouts |
|
||
| ~t~ | display a buffer without adding it to the current layout |
|
||
| ~w~ | workspaces transient state (needs eyebrowse layer enabled) |
|
||
| ~x~ | kill current layout with its buffers |
|
||
| ~X~ | kill other layouts with their buffers |
|
||
|
||
** Workspaces
|
||
Workspaces are sub-layouts, they allow to define multiple layouts into a given
|
||
layout, those layouts share the same buffer as the parent layout.
|
||
|
||
The currently active workspace number is displayed before the window number,
|
||
for instance “➊|➍” or “1|4” means the fourth window of the first workspace.
|
||
|
||
Any new layout comes with a default workspace which is the workspace 1.
|
||
|
||
Switching to a workspace that does not exist in the current layout will create a
|
||
new one. For instance at startup you can press ~SPC l w 2~ to create the
|
||
workspace 2 in the =default= layout.
|
||
|
||
When created a workspace is anonymous, you can give them a name with
|
||
~SPC l w R~.
|
||
|
||
*** Workspace key bindings
|
||
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.
|
||
|
||
| Key binding | Description |
|
||
|-------------------+-------------------------------------------------------------|
|
||
| ~SPC l w~ | initiate transient state |
|
||
| ~?~ | toggle the documentation |
|
||
| ~[0..9]~ | switch to nth workspace |
|
||
| ~[C-0..C-9]~ | switch to nth workspace and keep the transient state active |
|
||
| ~TAB~ | switch to last active workspace |
|
||
| ~d~ | close current workspace |
|
||
| ~n~ or ~l~ | switch to next workspace |
|
||
| ~N~ or ~p~ or ~h~ | switch to previous workspace |
|
||
| ~R~ | set a tag to the current workspace |
|
||
| ~w~ | switched to tagged workspace |
|
||
|
||
There are also some handy globally available key bindings related to workspaces:
|
||
|
||
| Key binding | Description |
|
||
|-------------+--------------------------------------|
|
||
| ~gt~ | go to next workspace |
|
||
| ~gT~ | go to previous workspace |
|
||
| ~SPC b W~ | go to workspace and window by buffer |
|
||
|
||
* Commands
|
||
** Vim key bindings
|
||
Spacemacs is based on =Vim= modal user interface to navigate and edit text. If
|
||
you are not familiar with the =Vim= way of editing text you can try the
|
||
[[https://github.com/syl20bnr/evil-tutor][evil-tutor]] lessons by pressing ~SPC h T~ at any time.
|
||
|
||
*** Escaping
|
||
Spacemacs uses [[https://github.com/syl20bnr/evil-escape][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~:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun dotspacemacs/user-config ()
|
||
(setq-default evil-escape-key-sequence "jj"))
|
||
#+END_SRC
|
||
*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=.
|
||
|
||
*** Executing Vim and Emacs ex/M-x commands
|
||
|
||
| Command | Key binding |
|
||
|------------------+-------------|
|
||
| Vim (ex-command) | ~:~ |
|
||
| Emacs (M-x) | ~SPC SPC~ |
|
||
|
||
The emacs command key ~SPC~ (executed after the leader key) can be changed
|
||
with the variable =dotspacemacs-emacs-command-key= of your =~/.spacemacs=.
|
||
|
||
*** Leader key
|
||
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=.
|
||
|
||
*** Major Mode leader key
|
||
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:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-major-mode-leader-key "<tab>")
|
||
#+END_SRC
|
||
|
||
*** Additional text objects
|
||
Additional text objects are defined in Spacemacs:
|
||
|
||
| Object | Description |
|
||
|---------+----------------------------|
|
||
| ~a~ | an argument |
|
||
| ~g~ | the entire buffer |
|
||
| ~l~ | a line |
|
||
| ~$~ | text between =$= |
|
||
| ~*~ | text between =*= |
|
||
| ~8~ | text between =/*= and =*/= |
|
||
| ~%~ | text between =%= |
|
||
| ~\vert~ | text between =\vert= |
|
||
|
||
** Reserved prefix command for user
|
||
~SPC o~ and ~SPC m o~ are reserved for the user. Setting key bindings behind
|
||
these is *guaranteed* to never conflict with Spacemacs default key bindings.
|
||
*Example:* Put =(spacemacs/set-leader-keys "oc" 'org-capture)= inside
|
||
=dotspacemacs/user-config= in your =~/.spacemacs= file, to be able to use
|
||
~SPC o c~ to run org mode capture.
|
||
|
||
** Completion
|
||
Spacemacs is powered by one of two incremental completion and selection
|
||
narrowing frameworks: [[https://github.com/emacs-helm/helm][Helm]] (default) or [[https://github.com/abo-abo/swiper][Ivy]]. To use Ivy, add the =ivy= layer to
|
||
your list of enabled layers. If the =ivy= layer is not enabled, Helm will be
|
||
enabled automatically. (Please note that, as Helm is the more mature of the two,
|
||
some functions may be unavailable if you choose Ivy.)
|
||
|
||
These completion systems are the central control towers of Spacemacs, they are
|
||
used to manage buffers, projects, search results, configuration layers, toggles
|
||
and more...
|
||
|
||
Mastering your choice of completion system will make you a Spacemacs power user.
|
||
|
||
For more information go to the layers documentation for [[https://github.com/syl20bnr/spacemacs/blob/master/layers/+completion/helm/README.org][Helm]] and [[https://github.com/syl20bnr/spacemacs/blob/master/layers/+completion/ivy/README.org][Ivy]].
|
||
*Note*: To open the Spacemacs documentation for Helm of Ivy in Emacs, open the
|
||
=spacemacs-help= menu with ~SPC h SPC~ and type ~helm~ or ~ivy~ then ~return~.
|
||
|
||
** Discovering
|
||
*** Key bindings
|
||
**** Which-key
|
||
A help buffer is displayed each time the ~SPC~ key is pressed in normal mode.
|
||
It lists the available key bindings and their associated commands.
|
||
|
||
By default the [[https://github.com/justbur/emacs-which-key][which-key]] buffer will be displayed quickly after the key has been
|
||
pressed. You can change the delay by setting the variable
|
||
=dotspacemacs-which-key-delay= to your liking (the value is in seconds).
|
||
|
||
**** Describe key bindings
|
||
It is possible to search for specific key bindings by pressing ~SPC ?~.
|
||
|
||
To narrow the list to some key bindings, use the leader key to type a pattern like
|
||
this regular expression: ~SPC\ b~ which would list all =buffer= related
|
||
bindings.
|
||
|
||
*** Getting help
|
||
=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 a~ | describe current expression under point |
|
||
| ~SPC h d b~ | describe bindings |
|
||
| ~SPC h d c~ | describe current character under point |
|
||
| ~SPC h d f~ | describe a function |
|
||
| ~SPC h d F~ | describe a face |
|
||
| ~SPC h d k~ | describe a key |
|
||
| ~SPC h d K~ | describe a keymap |
|
||
| ~SPC h d l~ | copy last pressed keys that you can paste in gitter chat |
|
||
| ~SPC h d m~ | describe current modes |
|
||
| ~SPC h d p~ | describe a package (Emacs built-in function) |
|
||
| ~SPC h d P~ | describe a package (Spacemacs layer information) |
|
||
| ~SPC h d s~ | copy system information that you can paste in gitter chat |
|
||
| ~SPC h d t~ | describe a theme |
|
||
| ~SPC h d v~ | describe a variable |
|
||
|
||
Other help key bindings:
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------------------|
|
||
| ~SPC h SPC~ | discover Spacemacs documentation, layers and packages |
|
||
| ~SPC h .~ | search dotfile variables |
|
||
| ~SPC h f~ | discover the =FAQ= |
|
||
| ~SPC h i~ | search in info pages with the symbol at point |
|
||
| ~SPC h k~ | show top-level bindings with =which-key= |
|
||
| ~SPC h l~ | search layers |
|
||
| ~SPC h m~ | search available man pages |
|
||
| ~SPC h n~ | browse emacs news |
|
||
| ~SPC h p~ | search packages |
|
||
| ~SPC h r~ | search documentation files |
|
||
| ~SPC h t~ | search toggles |
|
||
|
||
The =Profiler= is a tool that helps you identify why your editor is running
|
||
slowly or consumes a lot of memory. Here are key bindings relate to it:
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------|
|
||
| ~SPC h P k~ | stop the profiler |
|
||
| ~SPC h P r~ | display the profiler report |
|
||
| ~SPC h P s~ | start the profiler |
|
||
| ~SPC h P w~ | write the report to file |
|
||
|
||
Navigation key bindings in =help-mode=:
|
||
|
||
| Key binding | Description |
|
||
|--------------+-----------------------------------------------------|
|
||
| ~g b~ or ~[~ | go back (same as clicking on =[back]= button) |
|
||
| ~g f~ or ~]~ | go forward (same as clicking on =[forward]= button) |
|
||
| ~g h~ | go to help for symbol under point |
|
||
|
||
Reporting an issue:
|
||
|
||
| Key binding | Description |
|
||
|-----------------+------------------------------------------------------------------------------------------|
|
||
| ~SPC h I~ | Open Spacemacs GitHub issue page with pre-filled information |
|
||
| ~SPC u SPC h I~ | Open Spacemacs GitHub issue page with pre-filled information - include last pressed keys |
|
||
*Note*: To be able to report an issue you need to be logged into GitHub
|
||
*Note*: If these two bindings are used with the =*Backtrace*= buffer open, the
|
||
backtrace is automatically included
|
||
|
||
*** Available layers
|
||
All layers can be easily discovered via =spacemacs-help= accessible with ~SPC h SPC~.
|
||
|
||
The following actions on the selected candidate are available:
|
||
- default: open the layer =README.org=
|
||
- 2nd: open the layer =packages.el=
|
||
|
||
**** Available packages in Spacemacs
|
||
=spacemacs-help= also lists all the packages available in Spacemacs. The
|
||
entry format is =(layer) packages=. If you type =flycheck= you’ll be able to see
|
||
all the layers where =flycheck= is used.
|
||
|
||
The following actions are available on selected package:
|
||
- default: go the package init function
|
||
|
||
**** New packages from ELPA repositories
|
||
=package-list-packages= is where you can browse for all available packages in the
|
||
different Elpa repositories. It is possible to upgrade packages from there but
|
||
it is not recommended, use the =[Update Packages]= link on the Spacemacs startup
|
||
page instead.
|
||
|
||
Spacemacs uses [[https://github.com/Bruce-Connor/paradox][Paradox]] instead of =package-list-packages= to list available
|
||
ELPA packages. Paradox enhances the package list buffer with better feedbacks,
|
||
new filters and Github information like the number of stars. Optionally you can
|
||
also star packages directly in the buffer.
|
||
*Important Note 1*: Installing a new package from =Paradox= won’t make it
|
||
persistent. To install a package persistently you have to add it explicitly to a
|
||
configuration layer.
|
||
*Important Note 2*: Don’t /update/ your packages from =Paradox= or
|
||
=package-list-packages= because they don’t support the rollback feature of
|
||
Spacemacs.
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------------------|
|
||
| ~SPC a k~ | launch =paradox= |
|
||
| ~/~ | evil-search |
|
||
| ~f k~ | filter by keywords |
|
||
| ~f r~ | filter by regexp |
|
||
| ~f u~ | display only installed package with updates available |
|
||
| ~h~ | go left |
|
||
| ~H~ | show help (not accurate) |
|
||
| ~j~ | go down |
|
||
| ~k~ | go up |
|
||
| ~l~ | go right |
|
||
| ~L~ | show last commits |
|
||
| ~n~ | next search occurrence |
|
||
| ~N~ | previous search occurrence |
|
||
| ~o~ | open package homepage |
|
||
| ~r~ | refresh |
|
||
| ~S P~ | sort by package name |
|
||
| ~S S~ | sort by status (installed, available, etc...) |
|
||
| ~S *~ | sort by Github stars |
|
||
| ~v~ | =visual state= |
|
||
| ~V~ | =visual-line state= |
|
||
| ~x~ | execute (action flags) |
|
||
|
||
*** Toggles
|
||
=spacemacs-help= is also a central place to discover the available toggles.
|
||
To display only the toggles source press ~C-l~.
|
||
|
||
The following actions are available on selected toggle:
|
||
- default: toggle on/off
|
||
|
||
** Navigating
|
||
*** Point/Cursor
|
||
Navigation is performed using the Vi key bindings ~hjkl~.
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------------------------------------|
|
||
| ~h~ | move cursor left |
|
||
| ~j~ | move cursor down |
|
||
| ~k~ | move cursor up |
|
||
| ~l~ | move cursor right |
|
||
| ~H~ | move cursor to the top of the screen |
|
||
| ~L~ | move cursor to the bottom of the screen |
|
||
| ~SPC j 0~ | go to the beginning of line (and set a mark at the previous location in the line) |
|
||
| ~SPC j $~ | go to the end of line (and set a mark at the previous location in the line) |
|
||
| ~SPC t -~ | lock the cursor at the center of the screen |
|
||
|
||
**** Smooth scrolling
|
||
[[https://github.com/aspiers/smooth-scrolling][smooth-scrolling]] prevent the point to jump when it reaches the top or
|
||
bottom of the screen. It is enabled by default.
|
||
|
||
On Windows, you may want to disable it. To disable the smooth scrolling set the
|
||
=dotspacemacs-smooth-scrolling= variable in your =~/.spacemacs= to =nil=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-smooth-scrolling nil)
|
||
#+END_SRC
|
||
|
||
You can also toggle smooth scrolling with ~SPC t v~.
|
||
|
||
*** Vim motions with avy
|
||
Spacemacs uses the =evil= integration of [[https://github.com/abo-abo/avy][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.
|
||
|
||
| Key binding | Description |
|
||
|-------------+----------------------------------------------------|
|
||
| ~SPC j b~ | go back to the previous location (before the jump) |
|
||
| ~SPC j j~ | initiate avy jump char |
|
||
| ~SPC j w~ | initiate avy jump word |
|
||
| ~SPC j l~ | initiate avy jump line |
|
||
|
||
**** ace-link mode
|
||
Similar to =avy=, [[https://github.com/abo-abo/ace-link][ace-link]] allows one to jump to any link in
|
||
=help-mode= and =info-mode= with two key strokes.
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------------------|
|
||
| ~o~ | initiate ace link mode in =help-mode= and =info-mode= |
|
||
|
||
*** Unimpaired bindings
|
||
Spacemacs comes with a built-in port of [[https://github.com/tpope/vim-unimpaired][tpope’s vim-unimpaired]].
|
||
|
||
This plugin provides several pairs of bracket maps using ~[~ to denote
|
||
previous, and ~]~ as next.
|
||
|
||
| Key bindings | Description |
|
||
|--------------+----------------------------------|
|
||
| ~[ SPC~ | Insert space above |
|
||
| ~] SPC~ | Insert space below |
|
||
| ~[ b~ | Go to previous buffer |
|
||
| ~] b~ | Go to next buffer |
|
||
| ~[ f~ | Go to previous file in directory |
|
||
| ~] f~ | Go to next file in directory |
|
||
| ~[ l~ | Go to the previous error |
|
||
| ~] l~ | Go to the next error |
|
||
| ~[ h~ | Go to the previous vcs hunk |
|
||
| ~] h~ | Go to the next vcs hunk |
|
||
| ~[ q~ | Go to the previous error |
|
||
| ~] q~ | Go to the next error |
|
||
| ~[ t~ | Go to the previous frame |
|
||
| ~] t~ | Go to the next frame |
|
||
| ~[ w~ | Go to the previous window |
|
||
| ~] w~ | Go to the next window |
|
||
| ~[ e~ | Move line up |
|
||
| ~] e~ | Move line down |
|
||
| ~[ p~ | Paste above current line |
|
||
| ~] p~ | Paste below current line |
|
||
| ~g p~ | Select pasted text |
|
||
|
||
*** Jumping, Joining and Splitting
|
||
The ~SPC j~ prefix is for jumping, joining and splitting.
|
||
|
||
**** Jumping
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------------------------------------|
|
||
| ~SPC j 0~ | go to the beginning of line (and set a mark at the previous location in the line) |
|
||
| ~SPC j $~ | go to the end of line (and set a mark at the previous location in the line) |
|
||
| ~SPC j b~ | undo a jump (go back to previous location) |
|
||
| ~SPC j d~ | jump to a listing of the current directory |
|
||
| ~SPC j D~ | jump to a listing of the current directory (other window) |
|
||
| ~SPC j f~ | jump to the definition of an Emacs Lisp function |
|
||
| ~SPC j i~ | jump to a definition in buffer (imenu) |
|
||
| ~SPC j I~ | jump to a definition in any buffer (imenu) |
|
||
| ~SPC j j~ | jump to one or more characters in the buffer (works as an evil motion) |
|
||
| ~SPC j k~ | jump to next line and indent it using auto-indent rules |
|
||
| ~SPC j l~ | jump to a line with avy (works as an evil motion) |
|
||
| ~SPC j q~ | show the dumb-jump quick look tooltip |
|
||
| ~SPC j u~ | jump to a URL in the current buffer |
|
||
| ~SPC j v~ | jump to the definition/declaration of an Emacs Lisp variable |
|
||
| ~SPC j w~ | jump to a word in the current buffer (works as an evil motion) |
|
||
|
||
**** Joining and splitting
|
||
|
||
| Key binding | Description |
|
||
|-------------+--------------------------------------------------------------------------|
|
||
| ~J~ | join the current line with the next line |
|
||
| ~SPC j k~ | go to next line and indent it using auto-indent rules |
|
||
| ~SPC j n~ | split the current line at point, insert a new line and auto-indent |
|
||
| ~SPC j o~ | split the current line at point but let point on current line |
|
||
| ~SPC j s~ | split a quoted string or s-expression in place |
|
||
| ~SPC j S~ | split a quoted string or s-expression, insert a new line and auto-indent |
|
||
|
||
*** Window manipulation
|
||
**** Window manipulation key bindings
|
||
Every window has a number displayed at the start of the mode-line and
|
||
can be quickly accessed using =SPC number=.
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------|
|
||
| ~SPC 1~ | go to window number 1 |
|
||
| ~SPC 2~ | go to window number 2 |
|
||
| ~SPC 3~ | go to window number 3 |
|
||
| ~SPC 4~ | go to window number 4 |
|
||
| ~SPC 5~ | go to window number 5 |
|
||
| ~SPC 6~ | go to window number 6 |
|
||
| ~SPC 7~ | go to window number 7 |
|
||
| ~SPC 8~ | go to window number 8 |
|
||
| ~SPC 9~ | go to window number 9 |
|
||
|
||
Window number 0 is a special case and selects sidebar windows, like treemacs. If there is no window
|
||
number 0, =SPC 0= attempts to select window number 10.
|
||
|
||
Windows manipulation commands (start with ~w~):
|
||
|
||
| Key binding | Description |
|
||
|------------------------+-----------------------------------------------------------------------------|
|
||
| ~SPC w TAB~ | switch to alternate window in the current frame (switch back and forth) |
|
||
| ~SPC w =~ | balance split windows |
|
||
| ~SPC w _~ | maximize window horizontally |
|
||
| ~SPC w \vert~ | maximize window vertically |
|
||
| ~SPC w b~ | force the focus back to the minibuffer |
|
||
| ~SPC w c c~ | toggle visual centering of the current buffer |
|
||
| ~SPC w c C~ | toggle visual distraction free mode |
|
||
| ~SPC w c .~ | center buffer and enable centering transient state |
|
||
| ~SPC w d~ | delete a window |
|
||
| ~SPC u SPC w d~ | delete a window and its current buffer (does not delete the file) |
|
||
| ~SPC w D~ | delete another window using [[https://github.com/abo-abo/ace-window][ace-window]] |
|
||
| ~SPC u SPC w D~ | delete another window and its current buffer using [[https://github.com/abo-abo/ace-window][ace-window]] |
|
||
| ~SPC w t~ | toggle window dedication (dedicated window cannot be reused by a mode) |
|
||
| ~SPC w f~ | toggle follow mode |
|
||
| ~SPC w F~ | create new frame |
|
||
| ~SPC w h~ | move to window on the left |
|
||
| ~SPC w H~ | move window to the left |
|
||
| ~SPC w j~ | move to window below |
|
||
| ~SPC w J~ | move window to the bottom |
|
||
| ~SPC w k~ | move to window above |
|
||
| ~SPC w K~ | move window to the top |
|
||
| ~SPC w l~ | move to window on the right |
|
||
| ~SPC w L~ | move window to the right |
|
||
| ~SPC w m~ | maximize/minimize a window (maximize is equivalent to delete other windows) |
|
||
| ~SPC w M~ | swap windows using [[https://github.com/abo-abo/ace-window][ace-window]] |
|
||
| ~SPC w o~ | cycle and focus between frames |
|
||
| ~SPC w p m~ | open messages buffer in a popup window |
|
||
| ~SPC w p p~ | close the current sticky popup window |
|
||
| ~SPC w r~ | rotate windows forward |
|
||
| ~SPC w R~ | rotate windows backward |
|
||
| ~SPC w s~ or ~SPC w -~ | horizontal split |
|
||
| ~SPC w S~ | horizontal split and focus new window |
|
||
| ~SPC w u~ | undo window layout (used to effectively undo a closed window) |
|
||
| ~SPC w U~ | redo window layout |
|
||
| ~SPC w v~ or ~SPC w /~ | vertical split |
|
||
| ~SPC w V~ | vertical split and focus new window |
|
||
| ~SPC w w~ | cycle and focus between windows |
|
||
| ~SPC w W~ | select window using [[https://github.com/abo-abo/ace-window][ace-window]] |
|
||
| ~SPC w x~ | delete a window and its current buffer (does not delete the file) |
|
||
|
||
Split the current window into multiple ones, deleting all others using the
|
||
following commands:
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------|
|
||
| ~SPC w 1~ | make 1 window layout |
|
||
| ~SPC w 2~ | make 2 windows layout (split vertically) |
|
||
| ~SPC w 3~ | make 3 windows layout (split vertically) |
|
||
| ~SPC w 4~ | make 4 windows layout (split in 2x2 grid) |
|
||
|
||
By default, the commands above ignore some windows, like the filetrees (treemacs
|
||
and neotree) but you can use a prefix argument to force delete them.
|
||
|
||
| Key binding | Description |
|
||
|-----------------+-------------------------------------------------------------|
|
||
| ~SPC u SPC w 1~ | make 1 window layout with force delete |
|
||
| ~SPC u SPC w 2~ | make 2 windows layout (split vertically) with force delete |
|
||
| ~SPC u SPC w 3~ | make 3 windows layout (split vertically) with force delete |
|
||
| ~SPC u SPC w 4~ | make 4 windows layout (split in 2x2 grid) with force delete |
|
||
|
||
You can also configure which windows get ignored when executing the above
|
||
commands by adding a prefix to the =spacemacs-window-split-ignore-prefixes=
|
||
list:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(add-to-list 'spacemacs-window-split-ignore-prefixes "My Favourite Window")
|
||
#+END_SRC
|
||
|
||
Or if you want a certain ignored window to always be deleted you can remote it
|
||
from the list:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq spacemacs-window-split-ignore-prefixes
|
||
(remove treemacs--buffer-name-prefix spacemacs-window-split-ignore-prefixes))
|
||
#+END_SRC
|
||
|
||
And if you want even more control over the way windows are removed you can
|
||
define your own deletion function:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun my-delete-other-windows () (delete-other-windows))
|
||
(setq spacemacs-window-split-delete-function 'my-delete-other-windows)
|
||
#+END_SRC
|
||
|
||
**** Window manipulation transient state
|
||
A convenient window manipulation transient state allows performing most of the
|
||
actions listed above. The transient state allows additional actions as well like
|
||
window resizing.
|
||
|
||
| Key binding | Description |
|
||
|-------------+---------------------------------------------------------------|
|
||
| ~SPC w .~ | initiate transient state |
|
||
| ~?~ | display the full documentation in minibuffer |
|
||
| ~0~ | go to window number 0 |
|
||
| ~1~ | go to window number 1 |
|
||
| ~2~ | go to window number 2 |
|
||
| ~3~ | go to window number 3 |
|
||
| ~4~ | go to window number 4 |
|
||
| ~5~ | go to window number 5 |
|
||
| ~6~ | go to window number 6 |
|
||
| ~7~ | go to window number 7 |
|
||
| ~8~ | go to window number 8 |
|
||
| ~9~ | go to window number 9 |
|
||
| ~/~ | vertical split |
|
||
| ~-~ | horizontal split |
|
||
| ~[~ | shrink window horizontally |
|
||
| ~]~ | enlarge window horizontally |
|
||
| ~{~ | shrink window vertically |
|
||
| ~}~ | enlarge window vertically |
|
||
| ~d~ | delete window |
|
||
| ~D~ | delete other windows |
|
||
| ~g~ | toggle =golden-ratio= on and off |
|
||
| ~h~ | go to window on the left |
|
||
| ~j~ | go to window below |
|
||
| ~k~ | go to window above |
|
||
| ~l~ | go to window on the right |
|
||
| ~H~ | move window to the left |
|
||
| ~J~ | move window to the bottom |
|
||
| ~K~ | move bottom to the top |
|
||
| ~L~ | move window to the right |
|
||
| ~o~ | focus other frame |
|
||
| ~r~ | rotate windows forward |
|
||
| ~R~ | rotate windows backward |
|
||
| ~s~ | horizontal split |
|
||
| ~S~ | horizontal split and focus new window |
|
||
| ~u~ | undo window layout (used to effectively undo a closed window) |
|
||
| ~U~ | redo window layout |
|
||
| ~v~ | vertical split |
|
||
| ~V~ | vertical split and focus new window |
|
||
| ~w~ | focus other window |
|
||
|
||
**** Golden ratio
|
||
If you resize windows like crazy you may want to give a try to [[https://github.com/roman/golden-ratio.el][golden-ratio]].
|
||
=golden-ratio= resizes windows dynamically depending on whether they are
|
||
selected or not. By default =golden-ratio= is off.
|
||
|
||
The mode can be toggled on and off with ~SPC t g~.
|
||
|
||
*** Buffers and Files
|
||
**** Buffers manipulation key bindings
|
||
Buffer manipulation commands (start with ~b~):
|
||
|
||
| Key binding | Description |
|
||
|-----------------+----------------------------------------------------------------------------------------|
|
||
| ~SPC TAB~ | switch to alternate buffer in the current window (switch back and forth) |
|
||
| ~SPC b b~ | switch to a buffer |
|
||
| ~SPC b d~ | kill the current buffer (does not delete the visited file) |
|
||
| ~SPC u SPC b d~ | kill the current buffer and window (does not delete the visited file) |
|
||
| ~SPC b D~ | kill a visible buffer using [[https://github.com/abo-abo/ace-window][ace-window]] |
|
||
| ~SPC u SPC b D~ | kill a visible buffer and its window using [[https://github.com/abo-abo/ace-window][ace-window]] |
|
||
| ~SPC b C-d~ | kill other buffers |
|
||
| ~SPC b C-D~ | kill buffers using a regular expression |
|
||
| ~SPC b e~ | erase the content of the buffer (ask for confirmation) |
|
||
| ~SPC b h~ | open =*spacemacs*= home buffer |
|
||
| ~SPC b H~ | open or select the =*Help*= buffer |
|
||
| ~SPC b n~ | switch to next buffer avoiding buffers matching =spacemacs-useless-buffers-regexp= |
|
||
| ~SPC b m~ | open =*Messages*= buffer |
|
||
| ~SPC u SPC b m~ | kill all buffers and windows except the current one |
|
||
| ~SPC b M~ | kill all buffers matching the regexp |
|
||
| ~SPC b p~ | switch to previous buffer avoiding buffers matching =spacemacs-useless-buffers-regexp= |
|
||
| ~SPC b P~ | copy clipboard and replace buffer (useful when pasting from a browser) |
|
||
| ~SPC b R~ | revert the current buffer (reload from disk) |
|
||
| ~SPC b s~ | switch to the =*scratch*= buffer (create it if needed) |
|
||
| ~SPC b u~ | reopen the most recently killed file buffer |
|
||
| ~SPC b w~ | toggle read-only (writable state) |
|
||
| ~SPC b x~ | kill the current buffer and window (does not delete the visited file) |
|
||
| ~SPC b Y~ | copy whole buffer to clipboard (useful when copying to a browser) |
|
||
| ~z f~ | Make current function or comments visible in buffer as much as possible |
|
||
|
||
**** Create a new empty buffer
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------------------|
|
||
| ~SPC b N h~ | create new empty buffer in a new window on the left |
|
||
| ~SPC b N j~ | create new empty buffer in a new window at the bottom |
|
||
| ~SPC b N k~ | create new empty buffer in a new window above |
|
||
| ~SPC b N l~ | create new empty buffer in a new window below |
|
||
| ~SPC b N n~ | create new empty buffer in current window |
|
||
|
||
**** Buffers manipulation transient state
|
||
A convenient buffer manipulation transient state allows to quickly cycles through
|
||
the opened buffer and kill them.
|
||
|
||
| Key binding | Description |
|
||
|------------------------+--------------------------------------------------------------------------------------------|
|
||
| ~SPC b .~ | initiate transient state |
|
||
| ~[1..9]~ | move current buffer to nth window |
|
||
| ~[C-1..C-9]~ | switch focus to nth window |
|
||
| ~[M-1..M-9]~ | swap current buffer with nth window |
|
||
| ~b~ | list all buffers with helm/ivy (avoid buffers matching =spacemacs-useless-buffers-regexp=) |
|
||
| ~d~ | kill current buffer |
|
||
| ~C-d~ | bury current buffer |
|
||
| ~n~ or ~<right>~ | go to next buffer (avoid buffers matching =spacemacs-useless-buffers-regexp=) |
|
||
| ~N~ or ~p~ or ~<left>~ | go to previous buffer (avoid buffers matching =spacemacs-useless-buffers-regexp=) |
|
||
| ~o~ | switch focus to other window |
|
||
| ~z~ | recenter buffer in window |
|
||
|
||
Unlike vim, emacs creates many buffers that most people do not need to see. Some
|
||
examples are the =*Messages*= and =*Compile-Log*= buffers. Spacemacs tries to
|
||
automatically ignore buffers that are not useful. However, you may want to
|
||
change the way Spacemacs marks buffers as useful. For instructions, see the
|
||
[[https://github.com/syl20bnr/spacemacs/blob/develop/doc/FAQ.org#change-special-buffer-rules][special buffer howto]].
|
||
|
||
**** Files manipulations key bindings
|
||
Files manipulation commands (start with ~f~):
|
||
|
||
| Key binding | Description |
|
||
|-------------+--------------------------------------------------------------------------------------------------------|
|
||
| ~SPC f A~ | open a file and replace the current buffer with the new file |
|
||
| ~SPC f b~ | go to file bookmarks |
|
||
| ~SPC f c~ | copy current file to a different location |
|
||
| ~SPC f C d~ | convert file from unix to dos encoding |
|
||
| ~SPC f C u~ | convert file from dos to unix encoding |
|
||
| ~SPC f D~ | delete a file and the associated buffer (ask for confirmation) |
|
||
| ~SPC f E~ | open a file with elevated privileges (sudo edit) |
|
||
| ~SPC f f~ | open file |
|
||
| ~SPC f F~ | try to open the file under point |
|
||
| ~SPC f h~ | open binary file with =hexl= (a hex editor) |
|
||
| ~SPC f j~ | jump to the current buffer file in dired |
|
||
| ~SPC f J~ | open a junk file, in mode determined by the file extension provided (defaulting to =fundamental mode=) |
|
||
| ~SPC f l~ | open file literally in =fundamental mode= |
|
||
| ~SPC f L~ | Locate a file (using =locate=) |
|
||
| ~SPC f o~ | open a file using the default external program |
|
||
| ~SPC f R~ | rename the current file |
|
||
| ~SPC f s~ | save a file |
|
||
| ~SPC f S~ | save all files |
|
||
| ~SPC f r~ | open a recent file |
|
||
| ~SPC f t~ | toggle file tree side bar using [[https://github.com/Alexander-Miller/treemacs][Treemacs]] |
|
||
| ~SPC f v d~ | add a directory variable |
|
||
| ~SPC f v f~ | add a local variable to the current file |
|
||
| ~SPC f v p~ | add a local variable to the first line of the current file |
|
||
| ~SPC f y c~ | show and copy current file absolute path with line and column number in the minibuffer |
|
||
| ~SPC f y d~ | show and copy current directory absolute path in the minibuffer |
|
||
| ~SPC f y l~ | show and copy current file absolute path with line number in the minibuffer |
|
||
| ~SPC f y n~ | show and copy current file name with extension in the minibuffer |
|
||
| ~SPC f y N~ | show and copy current file name without extension in the minibuffer |
|
||
| ~SPC f y y~ | show and copy current file absolute path in the minibuffer |
|
||
|
||
**** Frame manipulation key bindings
|
||
Frame manipulation commands (start with ~F~):
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------|
|
||
| ~SPC F f~ | open a file in another frame |
|
||
| ~SPC F d~ | delete the current frame (unless it’s the only one) |
|
||
| ~SPC F D~ | delete all other frames |
|
||
| ~SPC F b~ | open a buffer in another frame |
|
||
| ~SPC F B~ | open a buffer in another frame (but don’t switch) |
|
||
| ~SPC F o~ | cycle focus between frames |
|
||
| ~SPC F O~ | open a dired buffer in another frame |
|
||
| ~SPC F n~ | create a new frame |
|
||
|
||
**** Emacs and Spacemacs files
|
||
Convenient key bindings are located under the prefix ~SPC f e~ to quickly
|
||
navigate between =Emacs= and Spacemacs specific files.
|
||
|
||
| Key binding | Description |
|
||
|---------------+---------------------------------------------------------------------------------------------------------|
|
||
| ~SPC f e d~ | open the spacemacs dotfile (=~/.spacemacs=) |
|
||
| ~SPC f e D~ | open =ediff= buffer of =~/.spacemacs= and =.spacemacs.template= |
|
||
| ~SPC f e e~ | open the =~/.spacemacs.env= file where environment variables are set or goes to =dotspacemacs/user-env= |
|
||
| ~SPC f e E~ | reload the environment variables by executing the function =dotspacemacs/user-env= |
|
||
| ~SPC f e C-e~ | reinitialize the =~/.spacemacs.env= file by importing system and shell environment variables |
|
||
| ~SPC f e i~ | open the all mighty =init.el= |
|
||
| ~SPC f e l~ | locate an Emacs library |
|
||
| ~SPC f e R~ | resync the dotfile with spacemacs |
|
||
| ~SPC f e U~ | update packages |
|
||
| ~SPC f e v~ | display and copy the spacemacs version |
|
||
|
||
**** Browsing files in completion buffer
|
||
In =vim= style and =hybrid= style with the variable
|
||
=hybrid-mode-enable-hjkl-bindings= set to =t=, you can navigation with ~hjkl~.
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------|
|
||
| ~C-h~ | go up one level (parent directory |
|
||
| ~C-H~ | describe key (replace ~C-h~) |
|
||
| ~C-j~ | go to previous candidate |
|
||
| ~C-k~ | go to next candidate |
|
||
| ~C-l~ | enter current directory |
|
||
|
||
*** Ido
|
||
Spacemacs displays the =ido= minibuffer vertically thanks to the
|
||
[[https://github.com/gempesaw/ido-vertical-mode.el][ido-vertical-mode]].
|
||
|
||
Basic =ido= operations can be done with ~Ctrl~ key:
|
||
|
||
| Key binding | Description |
|
||
|--------------------+---------------------------------------------------|
|
||
| ~C-RET~ | open a =dired buffer= |
|
||
| ~M-RET~ | select the buffer or file named by the prompt |
|
||
| ~C-d~ | delete selected file (ask for confirmation) |
|
||
| ~C-h~ | go to parent directory |
|
||
| ~C-j~ | select next file or directory |
|
||
| ~C-k~ | select previous file or directory |
|
||
| ~C-l~ | open the selected file |
|
||
| ~C-n~ | select next file or directory |
|
||
| ~C-o~ | open selected file in other window |
|
||
| ~C-p~ | select previous file or directory |
|
||
| ~C-s~ | open selected file in a vertically split window |
|
||
| ~C-t~ | open selected file in a new frame |
|
||
| ~C-v~ | open selected file in a horizontally split window |
|
||
| ~C-S-h~ | go to previous directory |
|
||
| ~C-S-j~ or ~C-S-n~ | next history element |
|
||
| ~C-S-k~ or ~C-S-p~ | previous history element |
|
||
| ~C-S-l~ | go to next directory |
|
||
|
||
*** Ido transient state
|
||
Spacemacs defines a [[#transient-states][transient state]] for =ido=.
|
||
|
||
Initiate the transient state with ~M-SPC~ or ~s-M-SPC~ while in an =ido= buffer.
|
||
|
||
| Key binding | Description |
|
||
|----------------------+---------------------------------------|
|
||
| ~M-SPC~ or ~s-M-SPC~ | initiate or leave the transient state |
|
||
| ~?~ | display help |
|
||
| ~e~ | open dired |
|
||
| ~h~ | delete backward or parent directory |
|
||
| ~j~ | next match |
|
||
| ~J~ | sub directory |
|
||
| ~k~ | previous match |
|
||
| ~K~ | parent directory |
|
||
| ~l~ | select match |
|
||
| ~n~ | next directory in history |
|
||
| ~o~ | open in other window |
|
||
| ~p~ | previous directory in history |
|
||
| ~q~ | quit transient state |
|
||
| ~s~ | open in a new horizontal split |
|
||
| ~t~ | open in other frame |
|
||
| ~v~ | open in a new vertical split |
|
||
|
||
*** Bookmarks
|
||
Bookmarks can be set anywhere in a file. Bookmarks are persistent. They are very
|
||
useful to jump to/open a known project.
|
||
|
||
Open the bookmark completion window by pressing= ~SPC f b~
|
||
|
||
| Key binding | Description |
|
||
|-------------+----------------------------------------------|
|
||
| ~C-d~ | delete the selected bookmark |
|
||
| ~C-e~ | edit the selected bookmark |
|
||
| ~C-f~ | toggle filename location |
|
||
| ~C-o~ | open the selected bookmark in another window |
|
||
|
||
To save a new bookmark, just type the name of the bookmark and press ~RET~.
|
||
|
||
*** DocView mode
|
||
=doc-view-mode= is a built-in major mode to view DVI, PostScript (PS), PDF,
|
||
OpenDocument, and Microsoft Office documents.
|
||
|
||
| Key binding | Description |
|
||
|-------------+------------------------------------------|
|
||
| ~/~ | search forward |
|
||
| ~?~ | search backward |
|
||
| ~+~ | enlarge |
|
||
| ~-~ | shrink |
|
||
| ~gg~ | go to first page |
|
||
| ~G~ | go to last page |
|
||
| ~gt~ | go to page number |
|
||
| ~h~ | previous page |
|
||
| ~H~ | adjust to height |
|
||
| ~j~ | next line |
|
||
| ~k~ | previous line |
|
||
| ~K~ | kill proc and buffer |
|
||
| ~l~ | next page |
|
||
| ~n~ | go to next search occurrence |
|
||
| ~N~ | go to previous search occurrence |
|
||
| ~P~ | fit page to window |
|
||
| ~r~ | revert |
|
||
| ~W~ | adjust to width |
|
||
| ~C-d~ | scroll down |
|
||
| ~C-k~ | kill proc |
|
||
| ~C-u~ | scroll up |
|
||
| ~C-c C-c~ | toggle display text and image display |
|
||
| ~C-c C-t~ | open new buffer with doc’s text contents |
|
||
|
||
** Auto-saving
|
||
*** Frequency of auto-saving
|
||
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-interval= and =auto-save-timeout=
|
||
respectively.
|
||
|
||
*** Location of auto-saved files
|
||
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=.
|
||
|
||
*** Disable auto-save
|
||
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=.
|
||
|
||
** Searching
|
||
*** With an external tool
|
||
Spacemacs can be interfaced with different search utilities like:
|
||
- [[https://github.com/BurntSushi/ripgrep][rg]]
|
||
- [[https://github.com/ggreer/the_silver_searcher][ag]]
|
||
- [[https://github.com/monochromegane/the_platinum_searcher][pt]]
|
||
- [[https://beyondgrep.com/][ack]]
|
||
- grep
|
||
|
||
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 =rg=, =ag=, =pt=,
|
||
=ack= then =grep=. For instance ~SPC s b~ will search in the opened buffers
|
||
using =pt= if =rg= and =ag= have not been found on the system.
|
||
|
||
The tool keys are:
|
||
|
||
| Tool | Key |
|
||
|------+-----|
|
||
| ag | a |
|
||
| grep | g |
|
||
| ack | k |
|
||
| rg | r |
|
||
| pt | t |
|
||
|
||
The available scopes and corresponding keys are:
|
||
|
||
| Scope | Key |
|
||
|----------------------------+-----|
|
||
| opened buffers | b |
|
||
| files in a given directory | f |
|
||
| current project | p |
|
||
|
||
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*:
|
||
- =rg=, =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 (not available in Ivy).
|
||
*Beware* if you use =pt=, [[https://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/apps/pt.html][TCL parser tools]] also install a command line tool
|
||
called =pt=.
|
||
|
||
**** Useful key bindings
|
||
|
||
| Key binding | Description |
|
||
|------------------------+--------------------------------------------------------------|
|
||
| ~F3~ | in a completion buffer, save results to a regular buffer |
|
||
| ~SPC r l~ | resume the last =completion= buffer |
|
||
| ~SPC r s~ or ~SPC s l~ | resume search buffer (completion or converted search buffer) |
|
||
| ~SPC s `~ | go back to the previous place before jump |
|
||
| Prefix argument | will ask for file extensions |
|
||
|
||
When results have been saved in a regular buffer with ~F3~, that buffer supports
|
||
browsing through the matches with Spacemacs’ =next-error= and =previous-error=
|
||
bindings (~SPC e n~ and ~SPC e p~) as well as the error transient state (~SPC e .~).
|
||
|
||
**** Searching in current file
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------|
|
||
| ~SPC s s~ | search with the first found tool |
|
||
| ~SPC s S~ | search with the first found tool with default input |
|
||
| ~SPC s a a~ | =ag= |
|
||
| ~SPC s a A~ | =ag= with default input |
|
||
| ~SPC s g g~ | =grep= |
|
||
| ~SPC s g G~ | =grep= with default input |
|
||
| ~SPC s r r~ | =rg= |
|
||
| ~SPC s r R~ | =rg= with default input |
|
||
|
||
**** Searching in all open buffers visiting files
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------|
|
||
| ~SPC s b~ | search with the first found tool |
|
||
| ~SPC s B~ | search with the first found tool with default input |
|
||
| ~SPC s a b~ | =ag= |
|
||
| ~SPC s a B~ | =ag= with default text |
|
||
| ~SPC s g b~ | =grep= |
|
||
| ~SPC s g B~ | =grep= with default text |
|
||
| ~SPC s k b~ | =ack= |
|
||
| ~SPC s k B~ | =ack= with default text |
|
||
| ~SPC s r b~ | =rg= |
|
||
| ~SPC s r B~ | =rg= with default text |
|
||
| ~SPC s t b~ | =pt= |
|
||
| ~SPC s t B~ | =pt= with default text |
|
||
|
||
**** Searching in files in an arbitrary directory
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------|
|
||
| ~SPC s f~ | search with the first found tool |
|
||
| ~SPC s F~ | search with the first found tool with default input |
|
||
| ~SPC s a f~ | =ag= |
|
||
| ~SPC s a F~ | =ag= with default text |
|
||
| ~SPC s g f~ | =grep= |
|
||
| ~SPC s g F~ | =grep= with default text |
|
||
| ~SPC s k f~ | =ack= |
|
||
| ~SPC s k F~ | =ack= with default text |
|
||
| ~SPC s r f~ | =rg= |
|
||
| ~SPC s r F~ | =rg= with default text |
|
||
| ~SPC s t f~ | =pt= |
|
||
| ~SPC s t F~ | =pt= with default text |
|
||
|
||
**** Searching in current directory
|
||
|
||
| Key binding | Description |
|
||
|----------------------+-----------------------------------------------------|
|
||
| ~SPC /~ or ~SPC s d~ | search with the first found tool |
|
||
| ~SPC *~ or ~SPC s D~ | search with the first found tool with default input |
|
||
| ~SPC s a d~ | =ag= |
|
||
| ~SPC s a D~ | =ag= with default text |
|
||
| ~SPC s g d~ | =grep= with default text |
|
||
| ~SPC s k d~ | =ack= |
|
||
| ~SPC s k D~ | =ack= with default text |
|
||
| ~SPC s t d~ | =pt= |
|
||
| ~SPC s t D~ | =pt= with default text |
|
||
| ~SPC s r d~ | =rg= |
|
||
| ~SPC s r D~ | =rg= with default text |
|
||
|
||
**** Searching in a project
|
||
|
||
| Key binding | Description |
|
||
|----------------------+-----------------------------------------------------|
|
||
| ~SPC /~ or ~SPC s p~ | search with the first found tool |
|
||
| ~SPC *~ or ~SPC s P~ | search with the first found tool with default input |
|
||
| ~SPC s a p~ | =ag= |
|
||
| ~SPC s a P~ | =ag= with default text |
|
||
| ~SPC s g p~ | =grep= with default text |
|
||
| ~SPC s k p~ | =ack= |
|
||
| ~SPC s k P~ | =ack= with default text |
|
||
| ~SPC s t p~ | =pt= |
|
||
| ~SPC s t P~ | =pt= with default text |
|
||
| ~SPC s r p~ | =rg= |
|
||
| ~SPC s r P~ | =rg= with default text |
|
||
*Hint*: It is also possible to search in a project without needing to open a
|
||
file beforehand. To do so use ~SPC p p~ and then ~C-s~ on a given project to
|
||
directly search into it like with ~SPC s p~.
|
||
|
||
**** Searching the web
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------------------------------|
|
||
| ~SPC s w g~ | Get Google suggestions in emacs. Opens Google results in Browser. |
|
||
|
||
*** Persistent highlighting
|
||
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=.
|
||
|
||
*** Highlight current symbol
|
||
Spacemacs supports highlighting of the current symbol on demand (provided by
|
||
[[https://github.com/emacsmirror/auto-highlight-symbol][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:
|
||
|
||
| Key binding | Description |
|
||
|-------------+------------------------------------------------------------------------------------|
|
||
| ~*~ | initiate navigation transient state on current symbol and jump forwards |
|
||
| ~#~ | initiate navigation transient state on current symbol and jump backwards |
|
||
| ~SPC s e~ | edit all occurrences of the current symbol(/) |
|
||
| ~SPC s h~ | highlight the current symbol and all its occurrence within the current range |
|
||
| ~SPC s H~ | go to the last searched occurrence of the last highlighted symbol |
|
||
| ~SPC t h a~ | toggle automatic highlight of symbol under point after =ahs-idle-interval= seconds |
|
||
|
||
During the symbol highlight transient state, the following bindings are active:
|
||
|
||
| Key binding | Description |
|
||
|-------------+---------------------------------------------------------------|
|
||
| ~e~ | edit occurrences (*) |
|
||
| ~n~ | go to next occurrence |
|
||
| ~N~ or ~p~ | go to previous occurrence |
|
||
| ~d~ | go to next definition occurrence |
|
||
| ~D~ | go to previous definition occurrence |
|
||
| ~r~ | change range (=function=, =display area=, =whole buffer=) |
|
||
| ~R~ | go to home occurrence (reset position to starting occurrence) |
|
||
| ~s~ | search current buffer for symbol using ivy / helm |
|
||
| ~b~ | search all open buffers for symbol using ivy / helm |
|
||
| ~f~ | search files for symbol |
|
||
| ~/~ | search current project for symbol |
|
||
| ~z~ | recenter buffer in window |
|
||
|
||
(*) using [[https://github.com/tsdh/iedit][iedit]] or the default implementation of =auto-highlight-symbol=
|
||
|
||
The minibuffer displays the following information during the transient state:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
Buffer [6/11]*
|
||
#+END_EXAMPLE
|
||
|
||
Where =M [x/y]*= indicates:
|
||
- =M=: the current search scope, which is one of the following:
|
||
- =Buffer=: whole buffer range
|
||
- =Display=: current display range
|
||
- =Function=: current function range (dependent on the programming language major mode)
|
||
- =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.
|
||
|
||
*** Visual Star
|
||
With [[https://github.com/bling/evil-visualstar][evil-visualstar]] you can search for the next occurrence of the current
|
||
selection.
|
||
|
||
It is pretty useful combined with the [[#expand-region][expand-region]] bindings.
|
||
|
||
*Note*: If the current state is not the =visual state= then pressing ~*~ uses
|
||
auto-highlight-symbol and its transient state.
|
||
|
||
*** Listing symbols by semantic
|
||
To list all the symbols of a buffer press ~SPC s j~
|
||
|
||
** Editing
|
||
*** Paste text
|
||
**** Paste Transient-state
|
||
The paste transient state can be enabled by setting the variable
|
||
=dotspacemacs-enable-paste-transient-state= to =t=. By default it is disabled.
|
||
|
||
When the transient state is enabled, after you paste something, pressing ~C-j~
|
||
or ~C-k~ will replace the pasted text with the previous or next yanked (copied)
|
||
text on the kill ring.
|
||
|
||
For example if you copy =foo= and =bar= then press ~p~ the text =bar= will
|
||
be pasted, pressing ~C-j~ will replace =bar= with =foo=.
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------------------------------------------|
|
||
| ~p~ or ~P~ | paste the text before or after point and initiate the =paste= transient state |
|
||
| ~C-j~ | in transient state: replace paste text with the previously copied one |
|
||
| ~C-k~ | in transient state: replace paste text with the next copied one |
|
||
|
||
**** Auto-indent pasted text
|
||
By default any pasted text will be auto-indented. To paste text un-indented use
|
||
the universal argument.
|
||
|
||
It is possible to disable the auto-indentation for specific major-modes by
|
||
adding a major-mode to the variable =spacemacs-indent-sensitive-modes= in your
|
||
=dotspacemacs/user-config= function.
|
||
|
||
*** Text manipulation commands
|
||
Text related commands (start with ~x~):
|
||
|
||
| Key binding | Description |
|
||
|---------------+---------------------------------------------------------------|
|
||
| ~SPC x a &~ | align region at & |
|
||
| ~SPC x a (~ | align region at ( |
|
||
| ~SPC x a )~ | align region at ) |
|
||
| ~SPC x a [~ | align region at [ |
|
||
| ~SPC x a ]~ | align region at ] |
|
||
| ~SPC x a {~ | align region at { |
|
||
| ~SPC x a }~ | align region at } |
|
||
| ~SPC x a ,~ | align region at , |
|
||
| ~SPC x a .~ | align region at . (for numeric tables) |
|
||
| ~SPC x a :~ | align region at : |
|
||
| ~SPC x a ;~ | align region at ; |
|
||
| ~SPC x a =~ | align region at = |
|
||
| ~SPC x a a~ | align region (or guessed section) using default rules |
|
||
| ~SPC x a c~ | align current indentation region using default rules |
|
||
| ~SPC x a l~ | left-align with evil-lion |
|
||
| ~SPC x a L~ | right-align with evil-lion |
|
||
| ~SPC x a r~ | align region using user-specified regexp |
|
||
| ~SPC x a m~ | align region at arithmetic operators (+-*/) |
|
||
| ~SPC x a ¦~ | align region at ¦ |
|
||
| ~SPC x c~ | count the number of chars/words/lines in the selection region |
|
||
| ~SPC x d w~ | delete trailing whitespaces |
|
||
| ~SPC x d SPC~ | Delete all spaces and tabs around point, leaving one space |
|
||
| ~SPC x g l~ | set languages used by translate commands |
|
||
| ~SPC x g t~ | translate current word using Google Translate |
|
||
| ~SPC x g T~ | reverse source and target languages |
|
||
| ~SPC x i c~ | change symbol style to =lowerCamelCase= |
|
||
| ~SPC x i C~ | change symbol style to =UpperCamelCase= |
|
||
| ~SPC x i i~ | cycle symbol naming styles (~i~ to keep cycling) |
|
||
| ~SPC x i -~ | change symbol style to =kebab-case= |
|
||
| ~SPC x i k~ | change symbol style to =kebab-case= |
|
||
| ~SPC x i _~ | change symbol style to =under_score= |
|
||
| ~SPC x i u~ | change symbol style to =under_score= |
|
||
| ~SPC x i U~ | change symbol style to =UP_CASE= |
|
||
| ~SPC x j c~ | set the justification to center |
|
||
| ~SPC x j f~ | set the justification to full |
|
||
| ~SPC x j l~ | set the justification to left |
|
||
| ~SPC x j n~ | set the justification to none |
|
||
| ~SPC x j r~ | set the justification to right |
|
||
| ~SPC x J~ | move down a line of text (enter transient state) |
|
||
| ~SPC x K~ | move up a line of text (enter transient state) |
|
||
| ~SPC x l d~ | duplicate line or region |
|
||
| ~SPC x l s~ | sort lines |
|
||
| ~SPC x l u~ | uniquify lines |
|
||
| ~SPC x o~ | use avy to select a link in the frame and open it |
|
||
| ~SPC x O~ | use avy to select multiple links in the frame and open them |
|
||
| ~SPC x t c~ | swap (transpose) the current character with the previous one |
|
||
| ~SPC x t e~ | swap (transpose) the current sexp with the previous one |
|
||
| ~SPC x t l~ | swap (transpose) the current line with the previous one |
|
||
| ~SPC x t p~ | swap (transpose) the current paragraph with the previous one |
|
||
| ~SPC x t s~ | swap (transpose) the current sentence with the previous one |
|
||
| ~SPC x t w~ | swap (transpose) the current word with the previous one |
|
||
| ~SPC x u~ | set the selected text to lower case |
|
||
| ~SPC x U~ | set the selected text to upper case |
|
||
| ~SPC x w c~ | count the number of occurrences per word in the select region |
|
||
| ~SPC x w d~ | show dictionary entry of word from wordnik.com |
|
||
| ~SPC x TAB~ | indent or dedent a region rigidly |
|
||
|
||
*** Text insertion commands
|
||
Text insertion commands (start with ~i~):
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------------------------|
|
||
| ~SPC i l l~ | insert lorem-ipsum list |
|
||
| ~SPC i l p~ | insert lorem-ipsum paragraph |
|
||
| ~SPC i l s~ | insert lorem-ipsum sentence |
|
||
| ~SPC i p 1~ | insert simple password |
|
||
| ~SPC i p 2~ | insert stronger password |
|
||
| ~SPC i p 3~ | insert password for paranoids |
|
||
| ~SPC i p p~ | insert a phonetically easy password |
|
||
| ~SPC i p n~ | insert a numerical password |
|
||
| ~SPC i u~ | Search for Unicode characters and insert them into the active buffer. |
|
||
| ~SPC i U 1~ | insert UUIDv1 (use universal argument to insert with CID format) |
|
||
| ~SPC i U 4~ | insert UUIDv4 (use universal argument to insert with CID format) |
|
||
| ~SPC i U U~ | insert UUIDv4 (use universal argument to insert with CID format) |
|
||
*Hint:* You can change the length of the inserted password with a numerical
|
||
prefix argument, for instance ~SPC U 24 SPC i p p~ will insert a password
|
||
with 24 characters.
|
||
|
||
*** Smartparens Strict mode
|
||
[[https://github.com/Fuco1/smartparens][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=.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-smartparens-strict-mode t)
|
||
#+END_SRC
|
||
|
||
*** Zooming
|
||
**** Text
|
||
The font size of the current buffer can be adjusted with the commands:
|
||
|
||
| Key binding | Description |
|
||
|-------------+--------------------------------------------------------------------------------|
|
||
| ~SPC z x +~ | scale up the font and initiate the font scaling transient state |
|
||
| ~SPC z x =~ | scale up the font and initiate the font scaling transient state |
|
||
| ~SPC z x -~ | scale down the font and initiate the font scaling transient state |
|
||
| ~SPC z x 0~ | reset the font size (no scaling) and initiate the font scaling transient state |
|
||
|
||
In the transient state:
|
||
|
||
| Key binding | Description |
|
||
|-------------+------------------------|
|
||
| ~+~ | increase the font size |
|
||
| ~=~ | increase the font size |
|
||
| ~-~ | decrease the font size |
|
||
| ~0~ | reset the font size |
|
||
|
||
Note that /only/ the text of the current buffer is scaled, the other buffers,
|
||
the mode-line and the minibuffer are not affected. To zoom the whole content of
|
||
a frame use the =zoom frame= bindings (see next section).
|
||
|
||
**** Frame
|
||
You can zoom in and out the whole content of the frame with the commands:
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------------------------------|
|
||
| ~SPC z f +~ | zoom in the frame content and initiate the frame scaling transient state |
|
||
| ~SPC z f =~ | zoom in the frame content and initiate the frame scaling transient state |
|
||
| ~SPC z f -~ | zoom out the frame content and initiate the frame scaling transient state |
|
||
| ~SPC z f 0~ | reset the frame content size and initiate the frame scaling transient state |
|
||
| ~+~ | zoom in |
|
||
| ~=~ | zoom in |
|
||
| ~-~ | zoom out |
|
||
| ~0~ | reset zoom |
|
||
|
||
*** Increase/Decrease numbers
|
||
Spacemacs uses [[https://github.com/cofi/evil-numbers][evil-numbers]] to easily increase or decrease numbers.
|
||
|
||
| Key binding | Description |
|
||
|-------------+---------------------------------------------------------------------|
|
||
| ~SPC n +~ | increase the number under point by one and initiate transient state |
|
||
| ~SPC n -~ | decrease the number under point by one and initiate transient state |
|
||
|
||
In the transient state:
|
||
|
||
| Key binding | Description |
|
||
|-------------+----------------------------------------|
|
||
| ~+~ | increase the number under point by one |
|
||
| ~-~ | decrease the number under point by one |
|
||
*Tips:* you can increase or decrease a value by more that once by using a prefix
|
||
argument (i.e. ~10 SPC n +~ will add 10 to the number under point).
|
||
|
||
*** Spell checking
|
||
Spell checking is enabled by including the [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Bcheckers/spell-checking/README.org][spell
|
||
checking]] layer in your dotfile.
|
||
|
||
Key bindings are listed in the layer documentation.
|
||
|
||
*** Region selection
|
||
Vi =Visual= modes are all supported by =evil=.
|
||
|
||
**** Expand-region
|
||
Spacemacs adds another =Visual= mode via the [[https://github.com/magnars/expand-region.el][expand-region]] mode.
|
||
|
||
| Key binding | Description |
|
||
|-------------+------------------------------------------|
|
||
| ~SPC v~ | initiate expand-region mode then... |
|
||
| ~v~ | expand the region by one semantic unit |
|
||
| ~V~ | contract the region by one semantic unit |
|
||
| ~r~ | reset the region to initial selection |
|
||
| ~ESC~ | leave expand-region mode |
|
||
|
||
**** Indent text object
|
||
With [[https://github.com/TheBB/evil-indent-plus][evil-indent-plus]] the following text objects are available:
|
||
- ~ii~ - Inner Indentation: the surrounding textblock with the same indentation
|
||
- ~iI~ - Above and Indentation: ~ii~ + the line above with a different indentation
|
||
- ~iJ~ - Above, Below and Indentation+: ~iI~ + the line below with a different indentation
|
||
- There are also ~a~ variants that include whitespace. Example (=|= indicates point):
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(while (not done)
|
||
(messa|ge "All work and no play makes Jack a dull boy."))
|
||
(1+ 41)
|
||
#+END_SRC
|
||
|
||
- ~vii~ will select the line with message
|
||
- ~viI~ will select the whole while loop
|
||
- ~viJ~ will select the whole fragment
|
||
|
||
*** Region narrowing
|
||
The displayed text of a buffer can be narrowed with the commands (start with
|
||
~n~):
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------------------------------|
|
||
| ~SPC n f~ | narrow the buffer to the current function |
|
||
| ~SPC n p~ | narrow the buffer to the visible page |
|
||
| ~SPC n r~ | narrow the buffer to the selected text |
|
||
| ~SPC n w~ | widen, i.e. show the whole buffer again |
|
||
|
||
*** Replacing text with iedit
|
||
Spacemacs uses the powerful [[https://github.com/tsdh/iedit][iedit]] mode through [[https://github.com/syl20bnr/evil-iedit-state][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 [[https://github.com/magnars/expand-region.el][expand-region]] for quick
|
||
editing of the currently selected text by pressing ~e~.
|
||
|
||
**** iedit states key bindings
|
||
***** State transitions
|
||
|
||
| Key binding | From | To |
|
||
|-------------+------------------+--------|
|
||
| ~SPC s e~ | normal or visual | iedit |
|
||
| ~e~ | expand-region | iedit |
|
||
| ~ESC~ | iedit | normal |
|
||
| ~C-g~ | iedit | normal |
|
||
| ~fd~ | iedit | normal |
|
||
| ~ESC~ | iedit-insert | iedit |
|
||
| ~C-g~ | iedit-insert | normal |
|
||
| ~fd~ | iedit-insert | normal |
|
||
|
||
To sum-up, in =iedit-insert state= you have to press ESC twice to go back to the
|
||
=normal state=. You can also at any time press ~C-g~ or ~fd~ to return to =normal
|
||
state=.
|
||
*Note*: evil commands which switch to =insert state= will switch in
|
||
=iedit-insert state=.
|
||
|
||
***** In iedit state
|
||
=iedit state= inherits from =normal state=, the following key bindings are
|
||
specific to =iedit state=.
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------------------------------------------|
|
||
| ~ESC~ | go back to =normal state= |
|
||
| ~TAB~ | toggle current occurrence |
|
||
| ~0~ | go to the beginning of the current occurrence |
|
||
| ~$~ | go to the end of the current occurrence |
|
||
| ~#~ | prefix all occurrences with an increasing number (SPC u to choose the starting number). |
|
||
| ~A~ | go to the end of the current occurrence and switch to =iedit-insert state= |
|
||
| ~D~ | delete the occurrences |
|
||
| ~F~ | restrict the scope to the function |
|
||
| ~gg~ | go to first occurrence |
|
||
| ~G~ | go to last occurrence |
|
||
| ~I~ | go to the beginning of the current occurrence and switch to =iedit-insert state= |
|
||
| ~J~ | increase the editing scope by one line below |
|
||
| ~K~ | increase the editing scope by one line above |
|
||
| ~L~ | restrict the scope to the current line |
|
||
| ~n~ | go to next occurrence |
|
||
| ~N~ | go to previous occurrence |
|
||
| ~p~ | replace occurrences with last yanked (copied) text |
|
||
| ~S~ | (substitute) delete the occurrences and switch to =iedit-insert state= |
|
||
| ~V~ | toggle visibility of lines with no occurrence |
|
||
| ~U~ | Up-case the occurrences |
|
||
| ~C-U~ | down-case the occurrences |
|
||
*Note*: ~0~, ~$~, ~A~ and ~I~ have the default Vim behavior when used outside of
|
||
an ~occurrence~.
|
||
|
||
***** In iedit-insert state
|
||
|
||
| Key binding | Description |
|
||
|-------------+---------------------------|
|
||
| ~ESC~ | go back to =iedit state= |
|
||
| ~C-g~ | go back to =normal state= |
|
||
|
||
**** Examples
|
||
- manual selection of several words then replace: ~v w w SPC s e S "toto" ESC ESC~
|
||
- append text to a word on two lines: ~v i w SPC s e J i "toto" ESC ESC~
|
||
- substitute symbol /with expand-region/: ~SPC v v e S "toto" ESC ESC~
|
||
- replace symbol with yanked (copied) text /with expand region/: ~SPC v e p ESC ESC~
|
||
|
||
*** Replacing text in several files
|
||
If you have =rg=, =ag=, =pt= or =ack= installed, replacing an occurrence of text
|
||
in several files can be performed via [[https://github.com/syohex/emacs-helm-ag][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 =rg=, =pt= and =ack=
|
||
as well (but not with =grep=).
|
||
|
||
*** Renaming files in a directory
|
||
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
|
||
|
||
*** Commenting
|
||
Comments are handled by [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commenter]], it’s bound to the following keys.
|
||
|
||
| Key binding | Description |
|
||
|-------------+---------------------------|
|
||
| ~SPC ;~ | comment operator |
|
||
| ~SPC c h~ | hide/show comments |
|
||
| ~SPC c l~ | comment lines |
|
||
| ~SPC c L~ | invert comment lines |
|
||
| ~SPC c p~ | comment paragraphs |
|
||
| ~SPC c P~ | invert comment paragraphs |
|
||
| ~SPC c t~ | comment to line |
|
||
| ~SPC c T~ | invert comment to line |
|
||
| ~SPC c y~ | comment and yank |
|
||
| ~SPC c Y~ | invert comment and yank |
|
||
*Tips:* To comment efficiently a block of line use the combo ~SPC ; SPC j l~
|
||
|
||
*** Regular expressions
|
||
Spacemacs uses the packages [[https://github.com/joddie/pcre2el][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
|
||
|
||
| Key binding | Function |
|
||
|---------------+----------------------------------------------------------------------------------------|
|
||
| ~SPC x r /~ | Explain the regexp around point with =rx= |
|
||
| ~SPC x r '~ | Generate strings given by a regexp given this list is finite |
|
||
| ~SPC x r t~ | Replace regexp around point by the =rx= form or vice versa |
|
||
| ~SPC x r x~ | Convert regexp around point in =rx= form and display the result in the minibuffer |
|
||
| ~SPC x r c~ | Convert regexp around point to the other form and display the result in the minibuffer |
|
||
| ~SPC x r e /~ | Explain Emacs Lisp regexp |
|
||
| ~SPC x r e '~ | Generate strings from Emacs Lisp regexp |
|
||
| ~SPC x r e p~ | Convert Emacs Lisp regexp to PCRE |
|
||
| ~SPC x r e t~ | Replace Emacs Lisp regexp by =rx= form or vice versa |
|
||
| ~SPC x r e x~ | Convert Emacs Lisp regexp to =rx= form |
|
||
| ~SPC x r p /~ | Explain PCRE regexp |
|
||
| ~SPC x r p '~ | Generate strings from PCRE regexp |
|
||
| ~SPC x r p e~ | Convert PCRE regexp to Emacs Lisp |
|
||
| ~SPC x r p x~ | Convert PCRE to =rx= form |
|
||
|
||
*** Deleting files
|
||
Deletion is configured to send deleted files to system trash.
|
||
|
||
On OS X the =trash= program is required. It can be installed with [[https://brew.sh/][homebrew]] with
|
||
the following command:
|
||
|
||
#+BEGIN_SRC sh
|
||
$ brew install trash
|
||
#+END_SRC
|
||
|
||
To disable the trash you can set the variable =delete-by-moving-to-trash= to
|
||
=nil= in your =~/.spacemacs=.
|
||
|
||
*** Editing Lisp code
|
||
Editing of lisp code is provided by [[https://github.com/syl20bnr/evil-lisp-state][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.
|
||
|
||
**** Lisp Key bindings
|
||
***** Lisp state key bindings
|
||
These commands automatically switch to =lisp state=.
|
||
|
||
| Key binding | Function |
|
||
|-------------+---------------------------------------------------------------------|
|
||
| ~SPC k %~ | evil jump item |
|
||
| ~SPC k :~ | ex command |
|
||
| ~SPC k (~ | insert expression before (same level as current one) |
|
||
| ~SPC k )~ | insert expression after (same level as current one) |
|
||
| ~SPC k $~ | go to the end of current sexp |
|
||
| ~SPC k ` k~ | hybrid version of push sexp (can be used in non lisp dialects) |
|
||
| ~SPC k ` p~ | hybrid version of push sexp (can be used in non lisp dialects) |
|
||
| ~SPC k ` s~ | hybrid version of slurp sexp (can be used in non lisp dialects) |
|
||
| ~SPC k ` t~ | hybrid version of transpose sexp (can be used in non lisp dialects) |
|
||
| ~SPC k 0~ | go to the beginning of current sexp |
|
||
| ~SPC k a~ | absorb expression |
|
||
| ~SPC k b~ | forward barf expression |
|
||
| ~SPC k B~ | backward barf expression |
|
||
| ~SPC k c~ | convolute expression |
|
||
| ~SPC k ds~ | delete symbol |
|
||
| ~SPC k Ds~ | backward delete symbol |
|
||
| ~SPC k dw~ | delete word |
|
||
| ~SPC k Dw~ | backward delete word |
|
||
| ~SPC k dx~ | delete expression |
|
||
| ~SPC k Dx~ | backward delete expression |
|
||
| ~SPC k e~ | unwrap current expression and kill all symbols after point |
|
||
| ~SPC k E~ | unwrap current expression and kill all symbols before point |
|
||
| ~SPC k h~ | previous symbol |
|
||
| ~SPC k H~ | go to previous sexp |
|
||
| ~SPC k i~ | switch to =insert state= |
|
||
| ~SPC k I~ | go to beginning of current expression and switch to =insert state= |
|
||
| ~SPC k j~ | next closing parenthesis |
|
||
| ~SPC k J~ | join expression |
|
||
| ~SPC k k~ | previous opening parenthesis |
|
||
| ~SPC k l~ | next symbol |
|
||
| ~SPC k L~ | go to next sexp |
|
||
| ~SPC k p~ | paste after |
|
||
| ~SPC k P~ | paste before |
|
||
| ~SPC k r~ | raise expression (replace parent expression by current one) |
|
||
| ~SPC k s~ | forward slurp expression |
|
||
| ~SPC k S~ | backward slurp expression |
|
||
| ~SPC k t~ | transpose expression |
|
||
| ~SPC k u~ | undo |
|
||
| ~SPC k U~ | got to parent sexp backward |
|
||
| ~SPC k C-r~ | redo |
|
||
| ~SPC k v~ | switch to =visual state= |
|
||
| ~SPC k V~ | switch to =visual line state= |
|
||
| ~SPC k C-v~ | switch to =visual block state= |
|
||
| ~SPC k w~ | wrap expression with parenthesis |
|
||
| ~SPC k W~ | unwrap expression |
|
||
| ~SPC k y~ | copy expression |
|
||
|
||
***** Emacs lisp specific key bindings
|
||
|
||
| Key binding | Function |
|
||
|-------------+--------------------------------------------|
|
||
| ~SPC m e $~ | go to end of line and evaluate last sexp |
|
||
| ~SPC m e b~ | evaluate buffer |
|
||
| ~SPC m e c~ | evaluate current form (a =def= or a =set=) |
|
||
| ~SPC m e e~ | evaluate last sexp |
|
||
| ~SPC m e f~ | evaluate current defun |
|
||
| ~SPC m e l~ | go to end of line and evaluate last sexp |
|
||
| ~SPC m e r~ | evaluate region |
|
||
|
||
| Key binding | Function |
|
||
|-------------+----------------------------------------------------|
|
||
| ~SPC m g g~ | go to definition |
|
||
| ~SPC m g G~ | go to definition in another window |
|
||
| ~SPC m h h~ | describe elisp thing at point (show documentation) |
|
||
| ~SPC m t b~ | execute buffer tests |
|
||
| ~SPC m t q~ | ask for test function to execute |
|
||
|
||
*** Mouse usage
|
||
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
|
||
|
||
** Managing projects
|
||
Projects in Spacemacs are managed with [[https://github.com/bbatsov/projectile][projectile]]. In =projectile= projects
|
||
are defined implicitly, for instance the root of a project is found when a
|
||
=.git= repository or =.projectile= file is encountered in the file tree.
|
||
|
||
To search in a project see [[#searching-in-a-project][project searching]].
|
||
=projectile= commands start with p:
|
||
|
||
| Key binding | Description |
|
||
|-------------+------------------------------------------------------------------------------------------|
|
||
| ~SPC p '~ | open a shell in project’s root (with the =shell= layer) |
|
||
| ~SPC p !~ | run shell command in project’s root |
|
||
| ~SPC p &~ | run async shell command in project’s root |
|
||
| ~SPC p %~ | replace a regexp |
|
||
| ~SPC p a~ | toggle between implementation and test |
|
||
| ~SPC p b~ | switch to project buffer |
|
||
| ~SPC p c~ | compile project using =projectile= |
|
||
| ~SPC p d~ | find directory |
|
||
| ~SPC p D~ | open project root in =dired= |
|
||
| ~SPC p e~ | edit dir-locals.el |
|
||
| ~SPC p f~ | find file |
|
||
| ~SPC p F~ | find file based on path around point |
|
||
| ~SPC p g~ | find tags |
|
||
| ~SPC p G~ | regenerate the project’s =etags= / =gtags= |
|
||
| ~SPC p h~ | find file |
|
||
| ~SPC p I~ | invalidate the projectile cache |
|
||
| ~SPC p k~ | kill all project buffers |
|
||
| ~SPC p o~ | run =multi-occur= |
|
||
| ~SPC p p~ | switch project |
|
||
| ~SPC p r~ | open a recent file |
|
||
| ~SPC p R~ | replace a string |
|
||
| ~SPC p t~ | open =Treemacs= and add current =projectile= root to its list of projects |
|
||
| ~SPC p T~ | test project |
|
||
| ~SPC p v~ | open project root in =vc-dir= or =magit= |
|
||
| ~SPC /~ | search in project with the best search tool available |
|
||
| ~SPC s p~ | see [[#searching-in-a-project][searching in a project]] |
|
||
| ~SPC s a p~ | run =ag= |
|
||
| ~SPC s g p~ | run =grep= |
|
||
| ~SPC s k p~ | run =ack= |
|
||
| ~SPC s t p~ | run =pt= |
|
||
| ~SPC s r p~ | run =rg= |
|
||
| ~SPC f y C~ | show and copy current file path relative to the project root with line and column number |
|
||
| ~SPC f y D~ | show and copy current directory path relative to the project root |
|
||
| ~SPC f y L~ | show and copy current file path relative to the project root with line number |
|
||
| ~SPC f y Y~ | show and copy current file path relative to the project root |
|
||
*Note for Windows Users*: To enable fast indexing the GNU ~find~ or
|
||
Cygwin ~find~ must be in your ~PATH~.
|
||
|
||
** Registers
|
||
Access commands to the various registers start with =r=:
|
||
|
||
| Key binding | Description |
|
||
|-------------+------------------------------------|
|
||
| ~SPC r e~ | show evil yank and named registers |
|
||
| ~SPC r m~ | show marks register |
|
||
| ~SPC r r~ | show helm register |
|
||
| ~SPC r y~ | show kill ring |
|
||
|
||
** Errors handling
|
||
Spacemacs uses [[https://github.com/flycheck/flycheck][Flycheck]] to gives error feedback on the fly. The checks are
|
||
only performed at save time by default.
|
||
|
||
Errors management commands (start with ~e~):
|
||
|
||
| Key binding | Description |
|
||
|-------------+-----------------------------------------------------------------------|
|
||
| ~SPC t s~ | toggle flycheck |
|
||
| ~SPC e c~ | clear all errors |
|
||
| ~SPC e h~ | describe a flycheck checker |
|
||
| ~SPC e l~ | toggle the display of the =flycheck= list of errors/warnings |
|
||
| ~SPC e n~ | go to the next error |
|
||
| ~SPC e p~ | go to the previous error |
|
||
| ~SPC e y~ | copy each error at cursor position into kill ring |
|
||
| ~SPC e v~ | verify flycheck setup (useful to debug 3rd party tools configuration) |
|
||
| ~SPC e .~ | error transient state |
|
||
|
||
The next/previous error bindings and the error transient state can be used to
|
||
browse errors from flycheck as well as errors from compilation buffers, and
|
||
indeed anything that supports Emacs’ =next-error= API. This includes for example
|
||
search results that have been saved to a separate buffer.
|
||
|
||
*** Error transient state
|
||
The following key bindings are active in the error transient state:
|
||
|
||
| Key binding | Description |
|
||
|-------------+---------------------------|
|
||
| ~n~ | jump to next error |
|
||
| ~N~ or ~p~ | jump to previous error |
|
||
| ~z~ | recenter buffer in window |
|
||
|
||
*** Custom fringe bitmaps
|
||
|
||
| Symbol | Description |
|
||
|--------------------------+-------------|
|
||
| [[file:img/dot-error.png]] | Error |
|
||
| [[file:img/dot-warning.png]] | warning |
|
||
| [[file:img/dot-info.png]] | Info |
|
||
|
||
** Compiling
|
||
Spacemacs binds a few commands to support compiling a project.
|
||
|
||
| Key binding | Description |
|
||
|-------------+--------------------------------|
|
||
| ~SPC c c~ | use =helm-make= via projectile |
|
||
| ~SPC c C~ | compile |
|
||
| ~SPC c d~ | close compilation window |
|
||
| ~SPC c k~ | kill compilation |
|
||
| ~SPC c m~ | =helm-make= |
|
||
| ~SPC c r~ | recompile |
|
||
|
||
* EditorConfig
|
||
Spacemacs has support for [[http://editorconfig.org/][EditorConfig]], a configuration file to “define and
|
||
maintain consistent coding styles between different editors and IDEs.”
|
||
|
||
To enable this feature, [[https://github.com/editorconfig/editorconfig-core-c/blob/master/INSTALL.md][install the editorconfig command]].
|
||
|
||
To customize your editorconfig experience, read [[https://github.com/editorconfig/editorconfig-emacs/blob/master/README.md#customize][the editorconfig-emacs package’s
|
||
documentation]].
|
||
|
||
* Emacs Server
|
||
Spacemacs starts a server at launch. This server is killed whenever you close
|
||
your Emacs windows.
|
||
|
||
** Connecting to the Emacs server
|
||
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 set Emacs server socket by setting =dotspacemacs-server-socket-dir=,
|
||
then pass its location as =-s ~/.emacs.d/server/server= additionally.
|
||
|
||
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=:
|
||
|
||
#+BEGIN_SRC sh-mode
|
||
export EDITOR="emacsclient -c"
|
||
#+END_SRC
|
||
|
||
Note that if you’re on OS X, you may have to refer to the emacsclient that comes
|
||
with your GUI Emacs, e.g.:
|
||
|
||
#+BEGIN_SRC sh-mode
|
||
export EDITOR="/Applications/Emacs.app/Contents/MacOS/bin/emacsclient -c"
|
||
#+END_SRC
|
||
|
||
Tip: Remember to use ~:wq~ or ~C-x #~ after you are done editing the file in
|
||
Emacs.
|
||
|
||
You can set the location of the Emacs server socket by setting =dotspacemacs-server-socket-dir= in your =~./spacemacs=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-server-socket-dir "~/.emacs/server")
|
||
#+END_SRC
|
||
|
||
See [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html][Emacs as a Server]] in the official Emacs manual for more details.
|
||
|
||
** Keeping the server alive
|
||
It is possible to keep the server alive when you close Emacs by setting the
|
||
variable =dotspacemacs-persistent-server= to =t= in your =~/.spacemacs=.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-persistent-server t)
|
||
#+END_SRC
|
||
|
||
When this variable is set to =t=, the only way to quit Emacs /and/ kill the
|
||
server is to use the following bindings:
|
||
|
||
| Key binding | Description |
|
||
|-------------+--------------------------------------------------------------------------|
|
||
| ~SPC q q~ | Quit Emacs and kill the server, prompt for changed buffers to save |
|
||
| ~SPC q Q~ | Quit Emacs and kill the server, lose all unsaved changes. |
|
||
| ~SPC q r~ | Restart both Emacs and the server, prompting to save any changed buffers |
|
||
| ~SPC q s~ | Save the buffers, quit Emacs and kill the server |
|
||
| ~SPC q f~ | Kill the current frame |
|
||
| ~SPC q t~ | Restart Emacs and debug with --with-timed-requires |
|
||
| ~SPC q T~ | Restart Emacs and debug with --adv-timers |
|
||
|
||
** Disabling the Emacs server
|
||
You can disable the built-in server by setting the variable
|
||
=dotspacemacs-enable-server= to =nil= in your =~/.spacemacs=.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq-default dotspacemacs-enable-server nil)
|
||
#+END_SRC
|
||
|
||
* Troubleshoot
|
||
** Loading fails
|
||
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
|
||
[[https://github.com/syl20bnr/spacemacs/issues][Github issue]] with the backtrace.
|
||
|
||
** Upgrading/Downgrading Emacs version
|
||
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~.
|
||
|
||
* Achievements
|
||
** Issues
|
||
|
||
| Achievements | Account |
|
||
|--------------------------------+--------------|
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/100][100th issue (PR)]] | [[https://github.com/danielwuz][danielwuz]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/issues/200][200th issue (question)]] | [[https://github.com/justrajdeep][justrajdeep]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/300][300th issue (PR)]] | [[https://github.com/danielwuz][danielwuz]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/400][400th issue (PR)]] | [[https://github.com/CestDiego][CestDiego]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/500][500th issue (PR)]] | [[https://github.com/bjarkevad][bjarkevad]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/600][600th issue (PR)]] | [[https://github.com/bjarkevad][bjarkevad]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/700][700th issue (enhancement)]] | [[https://github.com/jcpetkovich][jcpetkovich]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/800][800th issue (PR)]] | [[https://github.com/laat][ryansroberts]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/900][900th issue (PR)]] | [[https://github.com/jcpetkovich][jcpetkovich]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/1000][1000th issue (PR)]] | [[https://github.com/tuhdo][tuhdo]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/2000][2000th issue (PR)]] | [[https://github.com/IvanMalison][IvanMalison]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/issues/3000][3000th issue (bug)]] | [[https://github.com/malchmih][malchmih]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/issues/4000][4000th issue (bug)]] | [[https://github.com/icymist][icymist]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/issues/5000][5000th issue (too many issues)]] | [[https://github.com/justbur][justbur]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/6000][6000th issue (PR)]] | [[https://github.com/d12frosted][d12frosted]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/7000][7000th issue (PR)]] | [[https://github.com/deb0ch][deb0ch]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/issues/8000][8000th issue (bug)]] | [[https://github.com/jonbash][jonbash]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/issues/9000][9000th issue (bug)]] | [[https://github.com/shaunpatel][shaunpatel]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/10000][10000th issue (PR)]] | [[https://github.com/nikital][nikital]] |
|
||
|
||
** Merged Pull Requests
|
||
|
||
| Achievements | Account |
|
||
|---------------------+----------------|
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/228][100th pull request]] | [[https://github.com/bru][bru]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/418][200th pull request]] | [[https://github.com/smt][smt]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/617][300th pull request]] | [[https://github.com/BrianHicks][BrianHicks]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/806][400th pull request]] | [[https://github.com/cpaulik][cpaulik]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/993][500th pull request]] | [[https://github.com/tuhdo][tuhdo]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/1205][600th pull request]] | [[https://github.com/trishume][trishume]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/1995][1000th pull request]] | [[https://github.com/justbur][justbur]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/4089][2000th pull request]] | [[https://github.com/channingwalton][channingwalton]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/6338][3000th pull request]] | [[https://github.com/darkfeline][darkfeline]] |
|
||
|
||
** Stars, forks and watchers
|
||
|
||
| Achievements | Account |
|
||
|----------------------------+-----------------|
|
||
| 100th watcher | [[https://github.com/adouzzy][adouzzy]] |
|
||
| 100th fork | [[https://github.com/balajisivaraman][balajisivaraman]] |
|
||
| 200th fork | [[https://github.com/alcol80][alcol80]] |
|
||
| 300th fork | [[https://github.com/mlopes][mlopes]] |
|
||
| 2000th fork | [[https://github.com/Gameguykiler][Gameguykiler]] |
|
||
| 100th star | [[https://github.com/Jackneill][Jackneill]] |
|
||
| 200th star | [[https://github.com/jb55][jb55]] |
|
||
| 400th star | [[https://github.com/dbohdan][dbohdan]] |
|
||
| 600th star | [[https://github.com/laat][laat]] |
|
||
| 700th star | [[https://github.com/kendall][kendall]] |
|
||
| 800th star | [[https://github.com/urso][urso]] |
|
||
| 900th star | [[https://github.com/luisgerhorst][luisgerhorst]] |
|
||
| 1000th star! | [[https://github.com/rashly][rashly]] |
|
||
| 2000th star!! | [[https://github.com/stshine][stshine]] |
|
||
| 3000th star!!! | [[https://github.com/TheBB][TheBB]] |
|
||
| 4000th star!!!! | [[https://github.com/nixmaniack][nixmaniack]] |
|
||
| 5000th star!!!!! | [[https://github.com/StreakyCobra][StreakyCobra]] |
|
||
| 6000th star!!!!!! | [[https://github.com/NJBS][NJBS]] |
|
||
| 7000th star!!!!!!! | [[https://github.com/mukhali][mukhali]] |
|
||
| 8000th star!!!!!!!! | [[https://github.com/shsteven][shsteven]] |
|
||
| 9000th star!!!!!!!!! | [[https://github.com/deb0ch][deb0ch]] |
|
||
| 10000th star :star: | [[https://github.com/colt365][colt365]] |
|
||
| 15000th star :star: :star: | [[https://github.com/missingfaktor][missingfaktor]] |
|
||
|
||
** Gitter chat
|
||
|
||
| Achievements | Account |
|
||
|---------------------------------+-------------|
|
||
| First joiner on the Gitter Chat | [[https://github.com/trishume][trishume]] |
|
||
| 1000th joiner | [[https://github.com/gabrielpoca][gabrielpoca]] |
|
||
|
||
** First times
|
||
|
||
| Achievements | Account |
|
||
|---------------------------------+--------------|
|
||
| [[https://github.com/syl20bnr/spacemacs/pull/19][First contribution]] | [[https://github.com/trishume][trishume]] |
|
||
| [[https://github.com/syl20bnr/spacemacs/commit/e802027d75d0c0aed55539b0da2dfa0df94dfd39][First contributed layer]] | [[https://github.com/trishume][trishume]] |
|
||
| [[http://oli.me.uk/2014/11/06/spacemacs-emacs-vim/][First blog article on Spacemacs]] | Wolfy87 |
|
||
| [[https://github.com/syl20bnr/spacemacs/commit/7b44a56263049482ed540ed6815a295633ffe9d1][First contributed banner]] | [[https://github.com/chrisbarrett][chrisbarrett]] |
|
||
|
||
** Special Mentions
|
||
|
||
| Reason | Account |
|
||
|---------------------------------------------------------------------+-----------------|
|
||
| Autumnal Cleanup 2015 ([[https://github.com/syl20bnr/spacemacs/wiki/Autumnal-Cleanup-2015][wiki]]) | [[https://github.com/StreakyCobra][StreakyCobra]] |
|
||
| Test and debug tools | [[https://github.com/justbur][justbur]] |
|
||
| Integration of Ivy | [[https://github.com/justbur][justbur]] |
|
||
| Transient States | [[https://github.com/justbur][justbur]] |
|
||
| Integration of Persp-mode | [[https://github.com/CestDiego][CestDiego]] |
|
||
| Cleanest PR ([[https://github.com/syl20bnr/spacemacs/pull/5545][PR #5545]]) | [[https://github.com/JAremko][JAremko]] |
|
||
| Documentation tools and GitHub support | [[https://github.com/JAremko][JAremko]] |
|
||
| Code navigation improvement (jump handlers, generalized next error) | [[https://github.com/TheBB][TheBB]] |
|
||
| Better support for GUI using an Emacs daemon (after-display macro) | [[https://github.com/travisbhartwell][travisbhartwell]] |
|
||
|
||
** Special Titles
|
||
|
||
| Achievements | Account |
|
||
|-------------------------------------------------+---------------|
|
||
| The Gunner (18 PRs in a row) | [[https://github.com/ralesi][ralesi]] |
|
||
| The Saint (unlocked the holy-mode) | [[https://github.com/trishume][trishume]] |
|
||
| The Artist ([[https://github.com/nashamri/spacemacs-logo][logo]] and [[https://github.com/nashamri/spacemacs-theme][theme]]) | [[https://github.com/nashamri][nashamri]] |
|
||
| The Meme Master (doge banner) | [[https://github.com/chrisbarrett][chrisbarrett]] |
|
||
| The Helm captain ([[https://tuhdo.github.io/helm-intro.html][helm guide]]) | [[https://github.com/tuhdo][tuhdo]] |
|
||
| The Master of the Keys ([[https://github.com/justbur/emacs-which-key][which-key]] and [[https://github.com/justbur/emacs-bind-map][bind-map]]) | [[https://github.com/justbur][justbur]] |
|
||
| The PR Patrol Officer | [[https://github.com/robbyoconnor][robbyoconnor]] |
|
||
| The Expert in Latin Language ([[https://github.com/syl20bnr/spacemacs/pull/4043][PR]]) | [[https://github.com/vijaykiran][vijaykiran]] |
|
||
| The Tiler ([[https://github.com/syl20bnr/spacemacs/pull/4068][eyebrowse integration]]) | [[https://github.com/bmag][bmag]] |
|
||
| The Geometer ([[https://github.com/TheBB/spaceline][spaceline]]) | [[https://github.com/TheBB][TheBB]] |
|
||
| The Librarian (doc-fmt tool and space-doc mode) | [[https://github.com/JAremko][JAremko]] |
|
||
| The Orgonaut ([[https://github.com/syl20bnr/spacemacs/issues/9476][fixed most of the Org READMEs]]) | [[https://github.com/smile13241324][smile13241324]] |
|
||
| The Ticketmaster | [[https://github.com/StreakyCobra][StreakyCobra]] |
|
||
| The ASCII Scribe | [[https://github.com/JAremko][JAremko]] |
|
||
|
||
* Thank you
|
||
Thank you Richard for this great piece of software.
|
||
|
||
Thank you to all the contributors and the whole Emacs community from core
|
||
developers to elisp hackers!
|