From 4f07ff2030aeb3607f78448ed3483462e8e1dd15 Mon Sep 17 00:00:00 2001 From: syl20bnr Date: Thu, 17 Mar 2016 22:03:19 -0400 Subject: [PATCH] First pass to update DOCUMENTATION.org --- doc/DOCUMENTATION.org | 705 ++++++++++++++++++++++-------------------- 1 file changed, 362 insertions(+), 343 deletions(-) diff --git a/doc/DOCUMENTATION.org b/doc/DOCUMENTATION.org index 481f5c40c..664715d9b 100644 --- a/doc/DOCUMENTATION.org +++ b/doc/DOCUMENTATION.org @@ -12,20 +12,20 @@ - [[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]] + - [[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]] - - [[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,12 +262,16 @@ 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 Spacemacs. It is recommended to update the packages first, see the next section. -*** Automatic Updates +*** Automatic Updates Spacemacs will automatically check for a new version every startup. When it detects that a new version is available a arrow will appear in the modeline. Click it to update Spacemacs. You must restart Emacs after updating. @@ -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,29 +336,31 @@ Configuration is organized in layers. Each layer has the following structure: |__ funcs.el |__ keybindings.el |__ packages.el + |__ packages-funcs.el [] = directory #+END_EXAMPLE Where: -| File | Usage | -|----------------+----------------------------------------------------------------------| -| config.el | Emacs built-in configuration or mandatory configuration | -| funcs.el | Various functions and macros (often used in keybindings.el) | -| 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 | +| File | Usage | +|-------------------+----------------------------------------------------------------------------------------| +| 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 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 =-packages= where == 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 =-packages= where == +is the name of the layer. Example: @@ -357,12 +368,20 @@ Example: (setq -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 /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 =-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-=, use =spacemacs/toggle--on= or -=spacemacs/toggle--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-=, use +=spacemacs/toggle--on= or =spacemacs/toggle--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: @@ -963,14 +982,14 @@ and ~T~): | ~SPC t n~ | toggle line numbers | | ~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 | -| ~SPC T m~ | toggle menu bar | -| ~SPC T M~ | toggle frame maximize | -| ~SPC T t~ | toggle tool bar | +| 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 =helm-spacemacs-help= interface @@ -1262,31 +1281,31 @@ plugin. Initiate the transient-state with ~M-SPC~ or ~s-M-SPC~ while in a =Helm= buffer. -| Key Binding | Description | -|----------------------+--------------------------------------------------| +| 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 | -| ~1~ | execute action 0 | -| ~2~ | execute action 1 | -| ~3~ | execute action 2 | -| ~4~ | execute action 3 | -| ~5~ | execute action 4 | -| ~6~ | execute action 5 | -| ~7~ | execute action 6 | -| ~8~ | execute action 7 | -| ~9~ | execute action 8 | -| ~0~ | execute action 9 | -| ~a~ | switch to actions page | -| ~g~ | go to first candidate | -| ~G~ | go to last candidate | -| ~h~ | go to previous source | -| ~j~ | select next candidate | -| ~k~ | select previous candidate | -| ~l~ | go to next source | -| ~t~ | mark current candidate | -| ~T~ | mark all candidates | -| ~v~ | execute persistent action | +| ~1~ | execute action 0 | +| ~2~ | execute action 1 | +| ~3~ | execute action 2 | +| ~4~ | execute action 3 | +| ~5~ | execute action 4 | +| ~6~ | execute action 5 | +| ~7~ | execute action 6 | +| ~8~ | execute action 7 | +| ~9~ | execute action 8 | +| ~0~ | execute action 9 | +| ~a~ | switch to actions page | +| ~g~ | go to first candidate | +| ~G~ | go to last candidate | +| ~h~ | go to previous source | +| ~j~ | select next candidate | +| ~k~ | select previous candidate | +| ~l~ | go to next source | +| ~t~ | mark current candidate | +| ~T~ | mark all candidates | +| ~v~ | execute persistent action | ** Discovering *** Key bindings @@ -1683,11 +1702,11 @@ the opened buffer and kill them. | Key Binding | Description | |---------------+-----------------------------------------------| -| ~SPC b .~ | initiate transient-state | +| ~SPC b .~ | initiate transient-state | | ~K~ | kill current buffer | | ~n~ | go to next buffer (avoid special buffers) | | ~N~ | go to previous buffer (avoid special buffers) | -| Any other key | leave the transient-state | +| Any other key | leave the transient-state | **** Special Buffers Unlike vim, emacs creates many buffers that most people do not need to see. Some @@ -1781,24 +1800,24 @@ 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 | +| 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 | *** NeoTree file tree Spacemacs provides a quick and simple way to navigate in an unknown project @@ -2221,57 +2240,57 @@ adding a major-mode to the variable =spacemacs-indent-sensitive-modes= in your *** 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 . (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 intendation region using default rules | - | ~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 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 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 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 w~ | swap (transpose) the current word with the previous one | - | ~SPC x t l~ | swap (transpose) the current line 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 | +| 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 . (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 intendation region using default rules | +| ~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 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 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 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 w~ | swap (transpose) the current word with the previous one | +| ~SPC x t l~ | swap (transpose) the current line 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 | *** 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 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) | +| 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 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) | *** Smartparens Strict mode [[https://github.com/Fuco1/smartparens][Smartparens]] comes with a strict mode which prevents deletion of parenthesis if @@ -2493,17 +2512,17 @@ It is possible to batch rename files in a directory using =wdired= from an *** 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 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 | +| Key Binding | Description | +|-------------+---------------------------| +| ~SPC ;~ | comment operator | +| ~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 y~ @@ -2617,36 +2636,36 @@ 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 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 f~ | find file | - | ~SPC p F~ | find file based on path around point | - | ~SPC p G~ | regenerate the project's =etags= / =gtags= | - | ~SPC p h~ | find file using =helm= | - | ~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 s~ | see [[Searching in a project][search in project]] | - | ~SPC p t~ | open =NeoTree= in =projectile= root | - | ~SPC p T~ | find test files | - | ~SPC p v~ | open project root in =vc-dir= or =magit= | - | ~SPC p y~ | find tags | - | ~SPC /~ | search in project with the best search tool available | - | ~SPC s a p~ | run =ag= | - | ~SPC s g p~ | run =grep= | - | ~SPC s k p~ | run =ack= | - | ~SPC s t p~ | run =pt= | +| 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 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 f~ | find file | +| ~SPC p F~ | find file based on path around point | +| ~SPC p G~ | regenerate the project's =etags= / =gtags= | +| ~SPC p h~ | find file using =helm= | +| ~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 s~ | see [[Searching in a project][search in project]] | +| ~SPC p t~ | open =NeoTree= in =projectile= root | +| ~SPC p T~ | find test files | +| ~SPC p v~ | open project root in =vc-dir= or =magit= | +| ~SPC p y~ | find tags | +| ~SPC /~ | search in project with the best search tool available | +| ~SPC s a p~ | run =ag= | +| ~SPC s g p~ | run =grep= | +| ~SPC s k p~ | run =ack= | +| ~SPC s t p~ | run =pt= | *Note for Windows Users*: To enable fast indexing the GNU ~find~ or Cygwin ~find~ must be in your ~PATH~. @@ -2667,15 +2686,15 @@ 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 v~ | verify flycheck setup (useful to debug 3rd party tools configuration) | +| 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 v~ | verify flycheck setup (useful to debug 3rd party tools configuration) | Custom fringe bitmaps: