TakeV
/
spacemacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

First pass to update DOCUMENTATION.org

This commit is contained in:
syl20bnr 2016-03-17 22:03:19 -04:00
parent 5585a40db1
commit 4f07ff2030
1 changed files with 362 additions and 343 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

409
doc/DOCUMENTATION.org
View File

@ -19,13 +19,13 @@
- [[Configuration layers][Configuration layers]]
- [[Purpose][Purpose]]
- [[Structure][Structure]]
- [[Packages][Packages]]
- [[Within a layer][Within a layer]]
- [[Configure packages][Configure packages]]
- [[With a layer][With a layer]]
- [[Declaration][Declaration]]
- [[Initialization][Initialization]]
- [[Exclusion][Exclusion]]
- [[Without a layer][Without a layer]]
- [[Packages synchronization (Vundle like feature)][Packages synchronization (Vundle like feature)]]
- [[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]]
@ -35,30 +35,30 @@
- [[Using a personal branch][Using a personal branch]]
- [[Tips for writing layers][Tips for writing layers]]
- [[Dotfile Configuration][Dotfile Configuration]]
- [[Installation][Installation]]
- [[Alternative setup][Alternative setup]]
- [[Dotfile Installation][Dotfile Installation]]
- [[Alternative dotdirectory][Alternative dotdirectory]]
- [[Synchronization of dotfile changes][Synchronization of dotfile changes]]
- [[Testing][Testing]]
- [[Content][Content]]
- [[Testing the dotfile][Testing the dotfile]]
- [[Dotfile Contents][Dotfile Contents]]
- [[Using configuration layers][Using configuration layers]]
- [[Setting configuration layers variables][Setting configuration layers variables]]
- [[Excluding packages][Excluding packages]]
- [[Hooks][Hooks]]
- [[Binding keys][Binding keys]]
- [[Configuration functions][Configuration functions]]
- [[Custom variables][Custom variables]]
- [[Main principles][Main principles]]
- [[Concepts][Concepts]]
- [[Editing Styles][Editing Styles]]
- [[Vim][Vim]]
- [[Emacs][Emacs]]
- [[Hybrid][Hybrid]]
- [[Evilified modes][Evilified modes]]
- [[States][States]]
- [[Evilified modes][Evilified modes]]
- [[Evil leader][Evil leader]]
- [[Universal argument][Universal argument]]
- [[Transient-states][Transient-states]]
- [[Differences between Vim, Evil and Spacemacs][Differences between Vim, Evil and Spacemacs]]
- [[The vim-surround case][The vim-surround case]]
- [[Evil plugins][Evil plugins]]
- [[Binding keys][Binding keys]]
- [[Spacemacs UI][Spacemacs UI]]
- [[Graphical UI][Graphical UI]]
- [[Color themes][Color themes]]
@ -262,6 +262,10 @@ project.
- Emacs users wanting a simple but deep configuration system that greatly
*lower 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
@ -275,7 +279,8 @@ Click it to update Spacemacs. You must restart Emacs after updating.
Update Button:
[[file:img/powerline-update.png]]
*Note*: If you use the =develop= branch of Spacemacs, you must update using git.
*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
@ -284,13 +289,16 @@ 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 --rebase
$ 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
@ -299,20 +307,21 @@ 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 next to the =[Update
Packages]= link and choose a rollback slot (sorted by date). This button uses
the command =configuration-layer/rollback=.
~RET~ or clicking on the =[Rollback Package Update]= link in the startup page
and choose a rollback slot (sorted by date). This button uses the command
=configuration-layer/rollback=.
* Configuration layers
*Note*: This is a very simple overview of how layers work. A more extensive
introduction to writing configuration layers can be found [[file:LAYERS.org][here]].
This section is an overview of layers. A more extensive introduction to writing
configuration layers can be found [[file:LAYERS.org][here]].
** 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. 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:
@ -327,6 +336,7 @@ Configuration is organized in layers. Each layer has the following structure:
|__ funcs.el
|__ keybindings.el
|__ packages.el
|__ packages-funcs.el
[] = directory
#+END_EXAMPLE
@ -334,22 +344,23 @@ Configuration is organized in layers. Each layer has the following structure:
Where:
| File | Usage |
|----------------+----------------------------------------------------------------------|
| config.el | Emacs built-in configuration or mandatory configuration |
| funcs.el | Various functions and macros (often used in keybindings.el) |
|-------------------+----------------------------------------------------------------------------------------|
| config.el | Layer configuration (not related to packages contained in this layer) |
| funcs.el | Various functions and macros (not related to packages contained in this layer) |
| keybindings.el | Emacs built-in key bindings or mandatory key bindings |
| packages.el | The list of packages to install and the functions to initialize them |
| packages.el | The list of packages to install and the configuration functions (init, post-init, ...) |
| packages-funcs.el | Additional functions used in the packages.el |
=Packages= are =ELPA= packages which can be installed from an =ELPA= compliant
repository, local packages in a layer's =local= folder, or packages that can be
installed from an online source using [[https://github.com/quelpa/quelpa][quelpa]].
=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]].
** Packages
*** Within a layer
** Configure packages
*** With a layer
**** Declaration
=Packages= are declared in variables and =<layer>-packages= where =<layer>= is
the layer name. They are processed in alphabetical order so sometimes you'll
have to use some =eval-after-load= black magic.
=Packages= are declared in a variable called =<layer>-packages= where =<layer>=
is the name of the layer.
Example:
@ -357,12 +368,20 @@ Example:
(setq <layer>-packages '(package1 package2 ...)
#+END_SRC
For details on installing local packages using quelpa or in the layer's =local=
folder, see [[file:LAYERS.org::packages.el][LAYERS]].
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 [[file:LAYERS.org::packages.el][LAYERS]].
**** Initialization
To initialize an extension or a package =xxx=, define a function with this
format in or =packages.el=:
format in =packages.el=:
#+BEGIN_SRC emacs-lisp
(defun <layer>/init-xxx () ...body )
@ -386,15 +405,15 @@ Example:
*** Without a layer
Sometimes a layer can be an unnecessary overhead, this is the case if you just
want to install a package without any configuration associated to it. A good
example is some niche language where you are only interested syntax
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= in your dotfile.
If you want to add some configuration for them then consider to create a layer,
or just put the configuration in the =dotspacemacs/user-config= function.
If you want to add some configuration for them then put the configuration in
the =dotspacemacs/user-config= function or consider to create a layer.
Example to install =llvm-mode= and =dts-mode=:
@ -402,27 +421,26 @@ Example to install =llvm-mode= and =dts-mode=:
(setq dotspacemacs-additional-packages '(llvm-mode dts-mode)
#+END_SRC
** Packages synchronization (Vundle like feature)
Spacemacs features a synchronization engine for the ELPA packages. It means
that Spacemacs will auto-install the new packages in =<layer>-packages= lists
/and/ auto-delete orphan packages in your =elpa= directory.
It effectively makes Spacemacs behave like [[https://github.com/gmarik/Vundle.vim][Vundle]].
** 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 packages that are not used is considered to be orphan and is deleted at
the next startup of Emacs.
** Types of configuration layers
There are three types of configuration layers:
- core (this is the Spacemacs layer)
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)
- contrib (in the =layers= directory, those layers are contributions shared
by the community and merged upstream).
** Submitting a configuration layer upstream
If you decide to provide a =contrib= configuration layer, please check the
contribution guidelines in [[file:../CONTRIBUTING.org][CONTRIBUTING]].
If you decide to provide a configuration layer, please check the contribution
guidelines first in [[file:../CONTRIBUTING.org][CONTRIBUTING]].
** Example: Themes Megapack example
This is a simple =contrib= configuration layer listing a bunch of themes, you
can find it [[../layers/themes-megapack][here]].
This is a simple configuration layer listing a bunch of themes which you can
find [[../layers/themes-megapack][here]].
To install it, just add =themes-megapack= to your =~/.spacemacs= like so:
@ -430,8 +448,8 @@ To install it, just add =themes-megapack= to your =~/.spacemacs= like so:
(setq-default dotspacemacs-configuration-layers '(themes-megapack))
#+END_SRC
You have now installed around 100 themes you are free to try with ~SPC T h~
(helm-themes).
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 configuration system is flexible enough to let you manage your
@ -467,60 +485,56 @@ best make them fit with the Spacemacs philosophy and loading strategy.
* Dotfile Configuration
User configuration can be stored in your =~/.spacemacs= file.
** Installation
The very first time Spacemacs starts up, it will prompt you to choose your
editing style. Once you choose a style, the =.spacemacs= file will be created
from a template.
** Dotfile Installation
The very first time Spacemacs starts up, it will ask you several questions
and then install the =.spacemacs= in your =HOME= directory.
*** Alternative setup
Since v0.104 you have the option of using =~/.spacemacs.d/init.el= for your
dotfile instead of =~/.spacemacs=. If you want to use this option, simply move
=~/.spacemacs= to =~/.spacemacs.d/init.el=. =~/.spacemacs= will always take
priority over =~/.spacemacs.d/init.el=, so =~/.spacemacs= must be missing for
=~/.spacemacs.d/init.el= to be used by spacemacs.
If you use this option, everything that applies to =~/.spacemacs= in this guide
will now apply to =~/.spacemacs.d/init.el=.
** 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= and
=dotspacemacs/user-config=. Depending on the content of this 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~).
*Note*: A synchronization re-executes the functions =dotspacemacs/init=,
=dotspacemacs/user-init= and =dotspacemacs/user-config=.
Depending on the content of this 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=).
** Testing
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~.
** Content
** Dotfile Contents
*** Using configuration layers
To use a configuration layer, add it to the =dotspacemacs-configuration-layers=
variable of your =~/.spacemacs=.
For instance to add the configuration layer of [[Thank you][RMS]]:
For instance [[Thank you][RMS]] can add his private configuration layer like this:
#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(rms))
#+END_SRC
If this layer does not exist you can still try another one in [[file:../layers][the =layers=
directory]].
Configuration layers are expected to be stored in =~/.emacs.d/private= or
=~/.emacs.d/layers=. But you are free to keep them somewhere else by declaring
additional paths where Spacemacs can look for configuration layers. This is
@ -533,7 +547,7 @@ done by setting the list =dotspacemacs-configuration-layer-path= in your
*** Setting configuration layers variables
Some configuration layers have configuration variables to enable specific
support. For instance the [[../layers/%2Bsource-control/git][git layer]] has several configuration variables, they
feature. For instance the [[../layers/%2Bsource-control/git][git layer]] has several configuration variables, they
can be set directly in the =dotspacemacs-configuration-layers= like this:
#+BEGIN_SRC emacs-lisp
@ -557,77 +571,30 @@ For instance to disable the =rainbow-delimiters= package:
#+END_SRC
When you exclude a package, Spacemacs will automatically delete it for you the
next time you launch Emacs. All the orphan dependencies are as well delete
next time you launch Emacs. All the orphan dependencies are as well deleted
automatically.
*** Hooks
Three special functions of the =~/.spacemacs= file can be used to perform
configuration at the beginning and end of Spacemacs loading process.
*** Configuration functions
Three special functions in the =~/.spacemacs= file can be used to perform
configuration at the beginning and end of Spacemacs loading process:
- =dotspacemacs/init= is triggered at the very beginning of Spacemacs
loading. You can configure Spacemacs variables here.
- =dotspacemacs/user-init= is also triggered at the very beginning of Spacemacs
loading. User initialization occurs here.
- =dotspacemacs/user-config= is triggered at the very end of Spacemacs
loading. Most user configuration should go here.
*** 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 the global-map uses the function
=global-set-key= as follows (to the command =forward-char= in this case).
#+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 evil-leader package,
which binds keys to the evil-leader keymap. This is where most of the spacemacs
bindings live. There are two related commands from this package which are used
as follows.
#+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 would not be in effect in
=org-mode= for example.
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 ac~ 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.
- =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.
- =dotspacemacs/user-init= is called immediately after =dotspacemacs/init=,
before layer configuration executes. This function is mostly useful for
variables that need to be set before packages are loaded.
- =dotspacemacs/user-config= is called at the very end of Spacemacs
initialization after layers configuration. This is the place where most of
your configurations should be done. Unless it is explicitly specified that a
variable should be set before a package is loaded, you should place you code
here.
*** Custom variables
Custom variables configuration from =M-x customize-group= which are
automatically saved by Emacs are stored at the end of your =~/.spacemacs= file.
* Main principles
* 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
@ -679,11 +646,12 @@ This style can be tweaked to be more like Emacs or more like Vim depending
on the user preferences. The following variable are available to change the
style configuration:
| Variable | Description |
|--------------------------------------+------------------------------------------------------------------------------------------------------------------|
| =hybrid-mode-default-state= | The default state when opening a new buffer, default is =normal=. Set it to =emacs= for a more emacsy style. |
| =hybrid-mode-enable-hjkl-bindings= | If non nil then packages will configure =h j k l= key bindings for navigation. |
| =hybrid-mode-enable-evilified-state= | If non nil buffer are =evilified= when supported, if nil then =emacs= state is enabled in those buffers instead. |
- =hybrid-mode-default-state= The default state when opening a new buffer,
default is =normal=. Set it to =emacs= for a more emacsy style.
- =hybrid-mode-enable-hjkl-bindings= If non nil then packages will configure
=h j k l= key bindings for navigation.
- =hybrid-mode-enable-evilified-state= If non nil buffer are =evilified= when
supported, if nil then =emacs= state is enabled in those buffers instead.
Default configuration is:
@ -697,6 +665,25 @@ Default configuration is:
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 | exclusive to =Evil=, 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 keybindings for
certain operations. These often conflict with Vim bindings. To make such buffers
@ -718,35 +705,16 @@ 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.
** 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 | exclusive to =Evil=, 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.
** Evil leader
Spacemacs heavily uses the [[https://github.com/cofi/evil-leader][evil-leader]] mode which brings the Vim leader key to
the Emacs world.
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~ (space bar, hence the name =spacemacs=). This key is the
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 [[http://en.wikipedia.org/wiki/Repetitive_strain_injury][RSI]].
good choice to lower the risk of [[http://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=.
So with Spacemacs there is no need to remap your keyboard modifiers to attempt
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:
@ -770,13 +738,13 @@ 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, a documentation is displayed in the minibuffer.
Additional information may as well be displayed in the minibuffer.
When a =transient-state= is active, a documentation is displayed in the
minibuffer. Additional information may as well 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]]
* Differences between Vim, Evil and Spacemacs
@ -784,9 +752,6 @@ Auto-highlight-symbol transient-state:
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).
- The ~Y~ key does not yank the whole line. It yanks from the current point to
the end of the line. This is more consistent with the behavior of ~C~ and ~D~
and is also recommended by the vim documentation.
Send a PR to add the differences you found in this section.
@ -795,13 +760,14 @@ 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]]: 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 let me explain why this is
the case:
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=
- this is also true for ~r~ but ~r~ is more useful because it stays 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
@ -818,18 +784,71 @@ Spacemacs ships with the following evil plugins:
| Mode | Description |
|-------------------------------+----------------------------------------------------------|
| [[https://github.com/cofi/evil-leader][evil-leader]] | vim leader that bring a new layer of keys in normal mode |
| [[https://github.com/cofi/evil-indent-textobject][evil-indent-textobject]] | add text object based on indentation level |
| [[https://github.com/bling/evil-visualstar][evil-visualstar]] | search for current selection with ~*~ |
| [[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/timcharper/evil-surround][evil-surround]] | port of [[https://github.com/tpope/vim-surround][vim-surround]] |
| [[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/juanjux/evil-search-highlight-persist][evil-search-highlight-persist]] | emulation of hlsearch behavior |
| [[https://github.com/cofi/evil-numbers][evil-numbers]] | like ~C-a~ and ~C-x~ in vim |
| [[https://github.com/wcsmith/evil-args][evil-args]] | motions and text objects for arguments |
| [[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/jaypei/emacs-neotree][NeoTree]] | mimic [[https://github.com/scrooloose/nerdtree][NERD Tree]] |
* 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.
* Spacemacs UI
Spacemacs has unique UI elements to make the Emacs experience even more
enjoyable:
@ -964,7 +983,7 @@ and ~T~):
| ~SPC t v~ | toggle smooth scrolling |
| 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 |
@ -1263,7 +1282,7 @@ plugin.
Initiate the transient-state with ~M-SPC~ or ~s-M-SPC~ while in a =Helm= buffer.
| Key Binding | Description |
|----------------------+--------------------------------------------------|
|----------------------+------------------------------------------------------|
| ~M-SPC~ or ~s-M-SPC~ | initiate the transient-state |
| ~q~ | quit transient-state |
| ~TAB~ | switch to actions page and leave the transient-state |
@ -1782,7 +1801,7 @@ 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 |