2797 lines
146 KiB
Org Mode
2797 lines
146 KiB
Org Mode
#+TITLE: Spacemacs documentation
|
|
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../css/readtheorg.css" />
|
|
|
|
* Spacemacs documentation :TOC_4_org:noexport:
|
|
- [[Core Pillars][Core Pillars]]
|
|
- [[Mnemonic][Mnemonic]]
|
|
- [[Discoverable][Discoverable]]
|
|
- [[Consistent][Consistent]]
|
|
- [[Crowd-Configured][Crowd-Configured]]
|
|
- [[Highlighted feature][Highlighted feature]]
|
|
- [[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]]
|
|
- [[Packages][Packages]]
|
|
- [[Within a layer][Within a layer]]
|
|
- [[Declaration][Declaration]]
|
|
- [[Initialization][Initialization]]
|
|
- [[Exclusion][Exclusion]]
|
|
- [[Without a layer][Without a layer]]
|
|
- [[Packages synchronization (Vundle like feature)][Packages synchronization (Vundle like feature)]]
|
|
- [[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]]
|
|
- [[Installation][Installation]]
|
|
- [[Alternative setup][Alternative setup]]
|
|
- [[Synchronization of dotfile changes][Synchronization of dotfile changes]]
|
|
- [[Testing][Testing]]
|
|
- [[Content][Content]]
|
|
- [[Using configuration layers][Using configuration layers]]
|
|
- [[Setting configuration layers variables][Setting configuration layers variables]]
|
|
- [[Excluding packages][Excluding packages]]
|
|
- [[Hooks][Hooks]]
|
|
- [[Binding keys][Binding keys]]
|
|
- [[Custom variables][Custom variables]]
|
|
- [[Main principles][Main principles]]
|
|
- [[Editing Styles][Editing Styles]]
|
|
- [[Vim][Vim]]
|
|
- [[Emacs][Emacs]]
|
|
- [[Hybrid][Hybrid]]
|
|
- [[Evilified modes][Evilified modes]]
|
|
- [[States][States]]
|
|
- [[Evil leader][Evil leader]]
|
|
- [[Universal argument][Universal argument]]
|
|
- [[Micro-states][Micro-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]]
|
|
- [[Spacemacs UI][Spacemacs UI]]
|
|
- [[Graphical UI][Graphical UI]]
|
|
- [[Color themes][Color themes]]
|
|
- [[Font][Font]]
|
|
- [[Graphical UI Toggles][Graphical UI Toggles]]
|
|
- [[Global line numbers][Global line numbers]]
|
|
- [[Mouse usage][Mouse usage]]
|
|
- [[Mode-line][Mode-line]]
|
|
- [[Powerline font installation for terminal-mode users][Powerline font installation for terminal-mode users]]
|
|
- [[Flycheck integration][Flycheck integration]]
|
|
- [[Anzu integration][Anzu integration]]
|
|
- [[Battery status integration][Battery status integration]]
|
|
- [[Powerline separators][Powerline separators]]
|
|
- [[Minor Modes][Minor Modes]]
|
|
- [[Customizing the mode-line][Customizing the mode-line]]
|
|
- [[Commands][Commands]]
|
|
- [[Vim key bindings][Vim key bindings]]
|
|
- [[Escaping][Escaping]]
|
|
- [[Executing Vim and Emacs ex/M-x commands][Executing Vim and Emacs ex/M-x commands]]
|
|
- [[Leader key][Leader key]]
|
|
- [[Additional text objects][Additional text objects]]
|
|
- [[Reserved prefix command for user][Reserved prefix command for user]]
|
|
- [[Helm][Helm]]
|
|
- [[C-z and Tab switch][C-z and Tab switch]]
|
|
- [[Helm focus][Helm focus]]
|
|
- [[Helm micro-state][Helm micro-state]]
|
|
- [[Discovering][Discovering]]
|
|
- [[Key bindings][Key bindings]]
|
|
- [[Which-key][Which-key]]
|
|
- [[Helm describe key bindings][Helm 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][Toggles]]
|
|
- [[Navigating][Navigating]]
|
|
- [[Point/Cursor][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 micro-state][Window manipulation micro-state]]
|
|
- [[Golden ratio][Golden ratio]]
|
|
- [[Buffers and Files][Buffers and Files]]
|
|
- [[Buffers manipulation key bindings][Buffers manipulation key bindings]]
|
|
- [[Buffers manipulation micro-state][Buffers manipulation micro-state]]
|
|
- [[Special Buffers][Special Buffers]]
|
|
- [[Files manipulations key bindings][Files manipulations key bindings]]
|
|
- [[Emacs and Spacemacs files][Emacs and Spacemacs files]]
|
|
- [[Browsing files with Helm][Browsing files with Helm]]
|
|
- [[Ido][Ido]]
|
|
- [[Ido micro-state][Ido micro-state]]
|
|
- [[NeoTree file tree][NeoTree file tree]]
|
|
- [[NeoTree navigation][NeoTree navigation]]
|
|
- [[Opening files with NeoTree][Opening files with NeoTree]]
|
|
- [[Other NeoTree key bindings][Other NeoTree key bindings]]
|
|
- [[NeoTree mode-line][NeoTree mode-line]]
|
|
- [[NeoTree Source Control Integration][NeoTree Source Control Integration]]
|
|
- [[NeoTree Theme][NeoTree Theme]]
|
|
- [[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 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]]
|
|
- [[Helm-swoop][Helm-swoop]]
|
|
- [[Editing][Editing]]
|
|
- [[Paste text][Paste text]]
|
|
- [[Paste Micro-state][Paste Micro-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]]
|
|
- [[Increase/Decrease 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]]
|
|
- [[Commenting][Commenting]]
|
|
- [[Deleting files][Deleting files]]
|
|
- [[Editing Lisp code][Editing Lisp code]]
|
|
- [[Lisp Key Bindings][Lisp Key Bindings]]
|
|
- [[Managing projects][Managing projects]]
|
|
- [[Registers][Registers]]
|
|
- [[Errors handling][Errors handling]]
|
|
- [[Compiling][Compiling]]
|
|
- [[Modes][Modes]]
|
|
- [[Major Mode leader key][Major Mode leader key]]
|
|
- [[Helm][Helm]]
|
|
- [[Emacs Server][Emacs Server]]
|
|
- [[Connecting to the Emacs server][Connecting to the Emacs server]]
|
|
- [[Keeping the server alive][Keeping the server alive]]
|
|
- [[Troubleshoot][Troubleshoot]]
|
|
- [[Loading fails][Loading fails]]
|
|
- [[Upgrading/Downgrading 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]]
|
|
- [[Specials][Specials]]
|
|
- [[Thank you][Thank you]]
|
|
|
|
* Core Pillars
|
|
Four core pillars: Mnemonic, Discoverable, Consistent and "Crowd-Configured".
|
|
|
|
If any of these core pillars is 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 feature
|
|
- *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*, keep 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 your improvements and new configuration layers.
|
|
|
|
- *Very active and helpful community* on =Gitter= and =IRC=
|
|
(via Gitter IRC bridge)
|
|
|
|
* Screenshots
|
|
|
|
/Python/ [[file:img/spacemacs-python.png]]
|
|
|
|
*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 [[./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 [[http://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
|
|
*lower the risk of .emacs bankruptcy*.
|
|
|
|
* 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 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.
|
|
|
|
Update Button:
|
|
[[file:img/powerline-update.png]]
|
|
|
|
*Note*: If you use the =develop= branch of Spacemacs, you must update 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 --rebase
|
|
#+END_SRC
|
|
|
|
|
|
** 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 next to the =[Update
|
|
Packages]= link 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]].
|
|
|
|
** 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
|
|
|
|
** Structure
|
|
Configuration is organized in layers. Each layer has the following structure:
|
|
|
|
#+BEGIN_EXAMPLE
|
|
[layer_name]
|
|
|__ [local]
|
|
| |__ [package 1]
|
|
| | ...
|
|
| |__ [package n]
|
|
|__ config.el
|
|
|__ funcs.el
|
|
|__ keybindings.el
|
|
|__ packages.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 |
|
|
|
|
=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
|
|
*** Within 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.
|
|
|
|
Example:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(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]].
|
|
|
|
**** Initialization
|
|
To initialize an extension or a package =xxx=, define a function with this
|
|
format in or =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 without any configuration associated to it. A good
|
|
example is some niche language where you are only interested 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.
|
|
|
|
Example to install =llvm-mode= and =dts-mode=:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(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]].
|
|
|
|
** Types of configuration layers
|
|
There are three types of configuration layers:
|
|
- core (this is the Spacemacs layer)
|
|
- 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]].
|
|
|
|
** Example: Themes Megapack example
|
|
This is a simple =contrib= configuration layer listing a bunch of themes, you
|
|
can find it [[../layers/themes-megapack][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
|
|
|
|
You have now installed around 100 themes you are free to try with ~SPC T h~
|
|
(helm-themes).
|
|
|
|
** Managing private configuration layers
|
|
Spacemacs 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 into an external Git
|
|
repository. It is especially a good practice to store them in your =dotfiles=
|
|
repository if you have one. Put also your =~/.spacemacs= file in it.
|
|
|
|
Then you are free to symlink your layers into =~/emacs.d/private= /or/ let them
|
|
anywhere you want and reference the parent directory in the variable
|
|
=dotspacemacs-configuration-layer-path= of your =~/.spacemacs=.
|
|
|
|
Note that you could also have a dedicated repository for all your private layers
|
|
and then directly clone this repository in =~/.emacs.d/private=.
|
|
|
|
*** 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 [[file: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.
|
|
|
|
** 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.
|
|
|
|
*** 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=.
|
|
|
|
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.
|
|
|
|
** 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~).
|
|
|
|
** Testing
|
|
You can use the command =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
|
|
*** 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]]:
|
|
|
|
#+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
|
|
done by setting the list =dotspacemacs-configuration-layer-path= in your
|
|
=~/.spacemacs=:
|
|
|
|
#+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
|
|
support. 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
|
|
(defun dotspacemacs/layers ()
|
|
;; List of configuration layers to load.
|
|
(setq-default dotspacemacs-configuration-layers '(auto-completion
|
|
(git :variables
|
|
git-magit-status-fullscreen t)
|
|
smex)))
|
|
#+END_SRC
|
|
|
|
*** 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. All the orphan dependencies are as well delete
|
|
automatically.
|
|
|
|
*** Hooks
|
|
Three special functions of 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.
|
|
|
|
*** 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
|
|
** Editing Styles
|
|
*** Vim
|
|
Spacemacs behaves like in Vim using [[https://gitorious.org/evil/pages/Home][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.
|
|
|
|
*** 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 dynamically
|
|
switch between evil and holy mode using ~SPC t E h~ and ~M-m t E h~.
|
|
|
|
*** Hybrid
|
|
The hybrid editing style is like the Vim style except that insert state
|
|
has all the Emacs key bindings available like in emacs state. The insert state
|
|
in hybrid mode is called the hybrid state and you have to map your key bindings
|
|
in =evil-hybrid-state-map= keymap instead of =evil-insert-state-map=.
|
|
|
|
Hybrid mode can be enabled by setting =dotspacemacs-editing-style= to =hybrid=.
|
|
To switch between evil and hybrid mode use ~SPC t E y~ and ~M-m t E y~.
|
|
|
|
The default state in hybrid mode can be changed by setting the variable
|
|
=hybrid-mode-default-state= to a state value, the default is =normal=, set it
|
|
to =hybrid= to start in hybrid insert state instead of normal state.
|
|
|
|
** Evilified modes
|
|
Some buffers (such as Magit, for using git from within Emacs), are not for
|
|
editing text, and provide their own keybindings for certain operations. These
|
|
often conflict with Vim bindings. To make such buffers behave Vim-like 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.
|
|
|
|
** States
|
|
Spacemacs has 10 states:
|
|
|
|
| State | 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.
|
|
|
|
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
|
|
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]].
|
|
|
|
So 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 with =helm=: ~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 change the universal argument binding
|
|
to ~SPC u~.
|
|
|
|
*Note*: ~SPC u~ is not working before =helm-M-x= (~SPC :~). Instead, call
|
|
=helm-M-x= first, select the command you want to run, and press ~C-u~ before
|
|
pressing ~RETURN~. For instance: ~SPC : org-reload C-u RET~
|
|
|
|
** Micro-states
|
|
Spacemacs defines a wide variety of =micro-states= (temporary overlay maps)
|
|
where it makes sense. This prevents one from doing repetitive and tedious
|
|
presses on the ~SPC~ key.
|
|
|
|
When a =micro-state= is active, a documentation is displayed in the minibuffer.
|
|
Additional information may as well be displayed in the minibuffer.
|
|
|
|
Auto-highlight-symbol micro-state:
|
|
[[file:img/spacemacs-ahs-micro-state.png]]
|
|
|
|
[[Text][Text scale micro-state]]:
|
|
[[file:img/spacemacs-scale-micro-state.png]]
|
|
|
|
* 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).
|
|
- 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.
|
|
|
|
** 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]]: 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:
|
|
- ~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=
|
|
- =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= function or
|
|
your =~/.spacemacs=):
|
|
|
|
#+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/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/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/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/bling/evil-jumper][evil-jumper]] | jump list emulation |
|
|
| [[https://github.com/jaypei/emacs-neotree][NeoTree]] | mimic [[https://github.com/scrooloose/nerdtree][NERD Tree]] |
|
|
|
|
* Spacemacs UI
|
|
Spacemacs has unique UI elements to make the Emacs experience even more
|
|
enjoyable:
|
|
- dedicated startup page with a mode aimed at easily managing Spacemacs
|
|
- dedicated helm source via =helm-spacemacs-help=
|
|
- a [[https://github.com/justbur/emacs-which-key][which-key]] buffer
|
|
|
|
** Graphical UI
|
|
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
|
|
|
|
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 aspect 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=
|
|
|
|
It is possible to define your default themes in your =~/.spacemacs= with the
|
|
variable =dotspacemacs-themes=. For instance, to specify =solarized-light=,
|
|
=leuven= and =zenburn=:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq-default dotspacemacs-themes '(solarized-light leuven zenburn))
|
|
#+END_SRC
|
|
|
|
| Key Binding | Description |
|
|
|-------------+-------------------------------------------------------|
|
|
| ~SPC T n~ | switch to next theme listed in =dotspacemacs-themes=. |
|
|
| ~SPC T h~ | select a theme using a =helm= buffer. |
|
|
|
|
You can see samples of all included themes in this [[http://themegallery.robdor.com][theme gallery]] from [[http://www.twitter.com/robmerrell][Rob Merrell]].
|
|
|
|
*Note*:
|
|
- 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]].
|
|
|
|
*Hint*: If you are an =Org= user, [[https://github.com/fniessen/emacs-leuven-theme][leuven-theme]] is amazing ;-)
|
|
|
|
*** 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.
|
|
|
|
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
|
|
:powerline-scale 1.1))
|
|
#+END_SRC
|
|
|
|
The properties should be pretty straightforward, it is possible to set any valid
|
|
property of a [[http://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).
|
|
|
|
The special property =:powerline-scale= is Spacemacs specific and it is for
|
|
quick tweaking of the mode-line height in order to avoid crappy rendering of the
|
|
separators like on the following screenshot (default value is 1.1).
|
|
|
|
/Ugly separators/
|
|
|
|
#+CAPTION: ugly-separators
|
|
|
|
[[file:img/crappy-powerline-separators.png]]
|
|
|
|
*** Graphical UI Toggles
|
|
Some graphical UI indicators can be toggled on and off (toggles start with ~t~
|
|
and ~T~):
|
|
|
|
| Key Binding | Description |
|
|
|-------------+-------------------------------------------------------------------|
|
|
| ~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 i~ | toggle indentation guide at point |
|
|
| ~SPC t l~ | toggle truncate lines |
|
|
| ~SPC t L~ | toggle visual lines |
|
|
| ~SPC t n~ | toggle line numbers |
|
|
|
|
| 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 micro-state |
|
|
|
|
*Note*: These toggles are all available via the =helm-spacemacs-help= interface
|
|
(press ~SPC f e h~ to display the =helm-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 something different than =nil=.
|
|
|
|
#+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
|
|
|
|
*** 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
|
|
|
|
*** Mode-line
|
|
The mode line is a heavily customized [[https://github.com/milkypostman/powerline][powerline]] with the following capabilities:
|
|
- 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 t~ | toggle the mode line itself |
|
|
| ~SPC t m v~ | toggle the version control info |
|
|
| ~SPC t m V~ | toggle the new version lighter |
|
|
|
|
**** Powerline font installation for terminal-mode users
|
|
Users who run Emacs in terminal mode may need to install the [[https://github.com/powerline/fonts][Powerline patched
|
|
fonts]] and configure their terminal clients to use them to make the Powerline
|
|
separators render correctly.
|
|
|
|
**** 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.
|
|
|
|
#+CAPTION: powerline-wave
|
|
|
|
[[file:img/powerline-wave.png]]
|
|
|
|
**** Anzu integration
|
|
[[https://github.com/syohex/emacs-anzu][Anzu]] shows the number of occurrence when performing a search. Spacemacs
|
|
integrates nicely the Anzu status by displaying it temporarily when ~n~ or ~N~
|
|
are being pressed. See the =5/6= segment on the screenshot below.
|
|
|
|
#+CAPTION: powerline-anzu
|
|
|
|
[[file:img/powerline-anzu.png]]
|
|
|
|
**** 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 the these colors may vary depending on your theme.
|
|
|
|
**** Powerline separators
|
|
It is possible to easily customize the =powerline separator= by setting the
|
|
=powerline-default-separator= variable in your =~./spacemacs=. For instance if
|
|
you want to set back the separator to the well-known =arrow= separator add the
|
|
following snippet to your configuration file:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(defun dotspacemacs/user-config ()
|
|
"This is were you can ultimately override default Spacemacs configuration.
|
|
This function is called at the very end of Spacemacs initialization."
|
|
(setq powerline-default-separator 'arrow))
|
|
#+END_SRC
|
|
|
|
To save you the time to try all the possible separators provided by the
|
|
powerline, here is an exhaustive set of screenshots:
|
|
|
|
| Separator | Screenshot |
|
|
|--------------+-----------------------------------|
|
|
| =alternate= | [[file:img/powerline-alternate.png]] |
|
|
| =arrow= | [[file:img/powerline-arrow.png]] |
|
|
| =arrow-fade= | [[file:img/powerline-arrow-fade.png]] |
|
|
| =bar= | [[file:img/powerline-bar.png]] |
|
|
| =box= | [[file:img/powerline-box.png]] |
|
|
| =brace= | [[file:img/powerline-brace.png]] |
|
|
| =butt= | [[file:img/powerline-butt.png]] |
|
|
| =chamfer= | [[file:img/powerline-chamfer.png]] |
|
|
| =contour= | [[file:img/powerline-contour.png]] |
|
|
| =curve= | [[file:img/powerline-curve.png]] |
|
|
| =rounded= | [[file:img/powerline-rounded.png]] |
|
|
| =roundstub= | [[file:img/powerline-roundstub.png]] |
|
|
| =slant= | [[file:img/powerline-slant.png]] |
|
|
| =wave= | [[file:img/powerline-wave.png]] |
|
|
| =zigzag= | [[file:img/powerline-zigzag.png]] |
|
|
| =nil= | [[file:img/powerline-nil.png]] |
|
|
|
|
**** Minor Modes
|
|
Spacemacs uses [[http://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.
|
|
|
|
| Key Binding | Unicode | ASCII | Mode |
|
|
|-------------+---------+-------+---------------------------------------------|
|
|
| ~SPC t -~ | =⊝= | - | [[http://emacswiki.org/emacs/centered-cursor-mode.el][centered-cursor]] mode |
|
|
| ~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~ | | | fill-column-indicator mode |
|
|
| ~SPC t F~ | =Ⓕ= | F | auto-fill 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~ | =ⓟ= | | global smartparens |
|
|
| ~SPC t s~ | =ⓢ= | s | syntax checking (flycheck) |
|
|
| ~SPC t S~ | =Ⓢ= | S | enabled in [[../layers/spell-checking][spell checking layer]] (flyspell) |
|
|
| ~SPC t w~ | =ⓦ= | w | whitespace mode |
|
|
| ~SPC t C-w~ | =Ⓦ= | W | global whitespace |
|
|
| ~SPC t y~ | =ⓨ= | y | [[https://github.com/capitaomorte/yasnippet][yasnippet]] mode |
|
|
|
|
**** Customizing the mode-line
|
|
Spacemacs uses [[https://github.com/TheBB/spaceline][Spaceline]] to provide its mode-line. It consists of a number of
|
|
/segments/ arranged on the left and right sides. These are defined in the
|
|
variables =spaceline-left= and =spaceline-right=. Segments can be defined using
|
|
=spaceline-define-segment=, and added to the appropriate location in the left or
|
|
right hand side variables.
|
|
|
|
Please see the Spaceline documentation for more information.
|
|
|
|
* 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 : 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=.
|
|
|
|
*** Additional text objects
|
|
Additional text objects are defined in Spacemacs:
|
|
|
|
| Object | Description |
|
|
|---------+----------------------------|
|
|
| ~a~ | an argument |
|
|
| ~g~ | the entire buffer |
|
|
| ~$~ | 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.
|
|
|
|
** Helm
|
|
Spacemacs is powered by [[https://github.com/emacs-helm/helm][Helm]] which is an incremental completion and selection
|
|
narrowing framework.
|
|
|
|
=Helm= is the central control tower of Spacemacs, it is used to manage
|
|
buffers, projects, search results, configuration layers, toggles and more...
|
|
|
|
Mastering =Helm= will make you a Spacemacs power user. Do not hesitate to read
|
|
the [[https://github.com/emacs-helm/helm/wiki][Helm documentation wiki]].
|
|
|
|
*** C-z and Tab switch
|
|
The command bound to ~C-z~ is much more useful than the one bound to Tab, so it
|
|
makes sense to swap them. It's also recommended [[http://tuhdo.github.io/helm-intro.html][here]].
|
|
|
|
*** Helm focus
|
|
If you find yourself unable to return focus to Helm (after a careless
|
|
mouse-click for example), use ~SPC w b~ to return focus to the minibuffer.
|
|
|
|
*** Helm micro-state
|
|
Spacemacs defines a [[Micro-states][micro-state]] for =Helm= to make it work like [[https://github.com/Shougo/unite.vim][Vim's Unite]]
|
|
plugin.
|
|
|
|
Initiate the micro-state with ~M-SPC~ or ~s-M-SPC~ while in a =Helm= buffer.
|
|
|
|
| Key Binding | Description |
|
|
|----------------------+--------------------------------------------------|
|
|
| ~M-SPC~ or ~s-M-SPC~ | initiate the micro-state |
|
|
| ~q~ | quit micro-state |
|
|
| ~TAB~ | switch to actions page and leave the micro-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 |
|
|
|
|
** 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 second).
|
|
|
|
**** Helm describe key bindings
|
|
It is possible to search for specific key bindings by pressing ~SPC ?~.
|
|
|
|
To narrow the list to some key bindings using the leader key 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 b~ | describe bindings in a =helm= buffer |
|
|
| ~SPC h d c~ | describe current character under point |
|
|
| ~SPC h d d~ | describe current expression 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 |
|
|
| ~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 using =helm= |
|
|
| ~SPC h i~ | search in info pages with the symbol at point |
|
|
| ~SPC h k~ | show top-level bindings with =which-key= |
|
|
| ~SPC h m~ | search available man pages |
|
|
| ~SPC h n~ | browse emacs news |
|
|
|
|
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 |
|
|
|
|
*** Available layers
|
|
All layers can be easily discovered via =helm-spacemacs-help= accessible with
|
|
~SPC f e h~.
|
|
|
|
The following helm actions are available:
|
|
- default: open the layer =README.org=
|
|
- 2nd: open the layer =packages.el=
|
|
|
|
**** Available packages in Spacemacs
|
|
=helm-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 helm actions are available on packages:
|
|
- 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
|
|
=helm-spacemacs-help= is also a central place to discover the available toggles.
|
|
To display only the toggles source press ~C-l~ (or in [[Helm micro-state][Helm micro-state]] you can
|
|
press just ~l~).
|
|
|
|
The following helm actions are available on packages:
|
|
- default: toggle on/off
|
|
|
|
*Tips* Use ~SPC h l~ to resume the last helm session. It is handy to quickly
|
|
toggle on and off a toggle.
|
|
|
|
** 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 t)
|
|
#+END_SRC
|
|
|
|
*** 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 j~ | initiate avy jump char |
|
|
| ~SPC j w~ | initiate avy jump word |
|
|
| ~SPC j l~ | initiate avy jump line |
|
|
| ~SPC j u~ | go back to the previous location (before the jump) |
|
|
|
|
**** 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.
|
|
|
|
| KeyBindings | 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 |
|
|
| ~[ 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~ | jump to a bookmark |
|
|
| ~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 the function under the point |
|
|
| ~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 a character in the buffer (works as an evil motion) |
|
|
| ~SPC j J~ | jump to a suite of two 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 u~ | undo a jump (go back to previous location) |
|
|
| ~SPC j U~ | jump to a URL in the current buffer |
|
|
| ~SPC j v~ | jump to the definition/declaration of the variable under the point |
|
|
| ~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 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 |
|
|
| ~SPC 0~ | go to window number 0 |
|
|
|
|
Windows manipulation commands (start with ~w~):
|
|
|
|
| Key Binding | Description |
|
|
|------------------------+-----------------------------------------------------------------------------|
|
|
| ~SPC w =~ | balance split windows |
|
|
| ~SPC w b~ | force the focus back to the minibuffer (usefull with =helm= popups) |
|
|
| ~SPC w c~ | close a window |
|
|
| ~SPC w C~ | delete another window using [[https://github.com/abo-abo/ace-window][ace-delete-window]] |
|
|
| ~SPC w d~ | toggle window dedication (dedicated window cannot be reused by a mode) |
|
|
| ~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~ | maximize/minimize a window, when maximized the buffer is centered |
|
|
| ~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 clockwise |
|
|
| ~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 SPC~ | select window using [[https://github.com/abo-abo/ace-window][ace-window]] |
|
|
|
|
**** Window manipulation micro-state
|
|
A convenient window manipulation micro-state allows to perform most of the
|
|
actions listed above. The micro-state allows additional actions as well like
|
|
window resizing.
|
|
|
|
| Key Binding | Description |
|
|
|---------------+---------------------------------------------------------------|
|
|
| ~SPC w .~ | initiate micro-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 |
|
|
| ~c~ | close window |
|
|
| ~C~ | close 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 |
|
|
| ~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~ | horizontal split and focus new window |
|
|
| ~w~ | focus other window |
|
|
| Any other key | leave the micro-state |
|
|
|
|
**** 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
|
|
Since =helm= is used everywhere, by default Spacemacs uses =helm= to open files.
|
|
|
|
Some users prefer the =ido= way to navigate the file system because it can
|
|
remember the last selected directories and buffers and ~RET~ is used to open
|
|
directories instead of ~TAB~ or ~C-z~ in =helm=. It is possible to use =ido=
|
|
instead of =helm= by setting the variable =dotspacemacs-use-ido= to =t= in your
|
|
dotfile.
|
|
|
|
**** 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 using =helm= |
|
|
| ~SPC b d~ | kill the current buffer (does not delete the visited file) |
|
|
| ~SPC b e~ | erase the content of the buffer (ask for confirmation) |
|
|
| ~SPC b h~ | open =*spacemacs*= home buffer |
|
|
| ~SPC b k~ | kill a buffer |
|
|
| ~SPC b K~ | kill all buffers except the current one |
|
|
| ~SPC b C-k~ | kill all buffers matching the regexp |
|
|
| ~SPC b m h~ | move a buffer to the left |
|
|
| ~SPC b m j~ | move a buffer to the bottom |
|
|
| ~SPC b m k~ | move a buffer to the top |
|
|
| ~SPC b m l~ | move a buffer to the right |
|
|
| ~SPC b M~ | swap windows using [[https://github.com/abo-abo/ace-window][ace-swap-window]] |
|
|
| ~SPC b n~ | switch to next buffer avoiding special buffers |
|
|
| ~SPC b p~ | switch to previous buffer avoiding special buffers |
|
|
| ~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 w~ | toggle read-only (writable state) |
|
|
| ~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 |
|
|
|
|
**** Buffers manipulation micro-state
|
|
A convenient buffer manipulation micro-state allows to quickly cycles through
|
|
the opened buffer and kill them.
|
|
|
|
| Key Binding | Description |
|
|
|---------------+-----------------------------------------------|
|
|
| ~SPC b .~ | initiate micro-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 micro-state |
|
|
|
|
**** Special Buffers
|
|
Unlike vim, emacs creates many buffers that most people do not need to see. Some
|
|
examples are =*Messages*= and =*Compile-Log*=. 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 [[file:FAQ.org::Change%20special%20buffer%20rules?][special buffer howto]].
|
|
|
|
**** Files manipulations key bindings
|
|
Files manipulation commands (start with ~f~):
|
|
|
|
| Key Binding | Description |
|
|
|-------------+---------------------------------------------------------------------------------------------------------------------------------|
|
|
| ~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 with =helm= (or =ido=) |
|
|
| ~SPC f F~ | try to open the file under point =helm= |
|
|
| ~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=), using =helm= (or =ivy=) |
|
|
| ~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 with =helm= |
|
|
| ~SPC f t~ | toggle file tree side bar using [[https://github.com/jaypei/emacs-neotree][NeoTree]] |
|
|
| ~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~ | show current file absolute path in the minibuffer |
|
|
|
|
**** 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 c~ | open =ido= in the =contrib= folder |
|
|
| ~SPC f e d~ | open the spacemacs dotfile (=~/.spacemacs=) |
|
|
| ~SPC f e D~ | open =ediff= buffer of =~/.spacemacs= and =.spacemacs.template= |
|
|
| ~SPC f e f~ | discover the =FAQ= using =helm= |
|
|
| ~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 v~ | display and copy the spacemacs version |
|
|
|
|
**** Browsing files with Helm
|
|
In =vim= and =hybrid= styles, Spacemacs remap the navigation in Helm find-files
|
|
to keep finger on the home row.
|
|
|
|
| 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-<return>~ | open a =dired buffer= |
|
|
| ~M-<return>~ | open a =dired buffer= in terminal |
|
|
| ~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 micro-state
|
|
Spacemacs defines a [[Micro-states][micro-state]] for =ido=.
|
|
|
|
Initiate the micro-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 micro-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 micro-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
|
|
file tree with [[https://github.com/jaypei/emacs-neotree][NeoTree]].
|
|
|
|
To toggle the =NeoTree= buffer press ~SPC f t~ or ~SPC p t~ (the latter open
|
|
NeoTree with the root set to the projectile project root).
|
|
|
|
The NeoTree window always has the number =0= so it does not shift the current
|
|
number of the other windows. To select the NeoTree window you then use ~SPC 0~.
|
|
|
|
VCS integration is supported, the file color will change depending on its
|
|
current state. With default =spacemacs-dark= theme:
|
|
- green: new file
|
|
- purple: modified file
|
|
|
|
**** NeoTree navigation
|
|
Navigation is centered on the ~hjkl~ with the hope to provide a fast navigation
|
|
experience like in [[http://ranger.nongnu.org/][ranger]]:
|
|
|
|
| Key Binding | Description |
|
|
|--------------+------------------------------------------------------------------------|
|
|
| ~h~ | collapse expanded directory or go to parent node |
|
|
| ~H~ | previous sibling |
|
|
| ~j~ | next file or directory |
|
|
| ~J~ | next expanded directory on level down |
|
|
| ~k~ | previous file or directory |
|
|
| ~K~ | parent directory, when reaching the root change it to parent directory |
|
|
| ~l~ or ~RET~ | expand directory |
|
|
| ~L~ | next sibling |
|
|
| ~R~ | make a directory the root directory |
|
|
|
|
*Note*: The point is automatically set to the first letter of a node for a
|
|
smoother experience.
|
|
|
|
**** Opening files with NeoTree
|
|
By default a file is opened in the last active window. It is possible to choose
|
|
window number where to open a file by using a numeric argument, for instance ~2
|
|
l~ or ~2 RET~ will open the current file in window 2. It is also possible to
|
|
open the file in a split window with ~|~ and ~-~:
|
|
|
|
| Key Binding | Description |
|
|
|------------------+-------------------------------------------|
|
|
| ~l~ or ~RET~ | open file in last active window |
|
|
| ~# l~ or ~# RET~ | open file in window number =#= |
|
|
| ~¦~ | open file in an vertically split window |
|
|
| ~-~ | open file in an horizontally split window |
|
|
|
|
**** Other NeoTree key bindings
|
|
| Key Binding | Description |
|
|
|-------------+---------------------------------|
|
|
| ~TAB~ | toggle stretching of the buffer |
|
|
| ~c~ | create a node |
|
|
| ~d~ | delete a node |
|
|
| ~gr~ | refresh |
|
|
| ~s~ | toggle showing of hidden files |
|
|
| ~q~ or ~fd~ | hide =NeoTree= buffer |
|
|
| ~r~ | rename a node |
|
|
|
|
**** NeoTree mode-line
|
|
The mode-line has the following format =[x/y] d (D:a, F:b)= where:
|
|
- =x= is the index of the current selected file or directory
|
|
- =y= the total number of items (file and directory) in the current directory
|
|
- =d= the name of the current directory
|
|
- =a= the number of directories in the current directory
|
|
- =b= the number of files in the current directory
|
|
|
|
**** NeoTree Source Control Integration
|
|
If you would like NeoTree to show source control information, you can use the
|
|
setting =neo-vc-integration=. It is a list containing the possible values:
|
|
|
|
| Setting | Description |
|
|
|---------+---------------------------------------------------------------------------|
|
|
| =face= | Show information by changing the color of the file/directory name. |
|
|
| =char= | Show information with a character to the left of the file/directory name. |
|
|
|
|
The default is =nil= (do not show source control information), which is recommended.
|
|
|
|
For example,
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq neo-vc-integration 'face)
|
|
#+END_SRC
|
|
|
|
*Note*: At this time, it is not recommended to set this to anything other
|
|
than =nil=. Otherwise, it will become very slow with larger source trees.
|
|
See https://github.com/jaypei/emacs-neotree/issues/126 for more information.
|
|
|
|
**** NeoTree Theme
|
|
You can change the NeoTree theme by using the setting =neo-theme=. Possible
|
|
values are:
|
|
|
|
| Setting | Description |
|
|
|-----------+------------------------------------------------------------------|
|
|
| =classic= | Use an icon to display items - only suitable for gui mode. |
|
|
| =ascii= | The simplest style, it will use =x=, =-= to display fold status. |
|
|
| =arrow= | Use unicode arrows to display fold status. |
|
|
| =nerd= | Use the NERDTree indentation mode and arrows. |
|
|
|
|
The default is =classic=.
|
|
|
|
Use =nerd= if you want it to look most like NERDTree in VIM. For example:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq neo-theme 'nerd)
|
|
#+END_SRC
|
|
|
|
*** Bookmarks
|
|
Bookmarks can be set anywhere in a file. Bookmarks are persistent. They are very
|
|
useful to jump to/open a known project. Spacemacs uses =helm-bookmarks= to
|
|
manage them.
|
|
|
|
Open an =helm= window with the current bookmarks by pressing: ~SPC f b~
|
|
|
|
Then in the =helm-bookmarks= buffer:
|
|
|
|
| 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-inteval= 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:
|
|
- ack
|
|
- grep
|
|
- [[https://github.com/ggreer/the_silver_searcher][ag]]
|
|
- [[https://github.com/monochromegane/the_platinum_searcher][pt]]
|
|
|
|
The search commands in Spacemacs are organized under the ~SPC s~ prefix with the
|
|
next key is the tool to use and the last key is the scope. For instance ~SPC s a
|
|
b~ will search in all opened buffers using =ag=.
|
|
|
|
If the last key (determining the scope) is uppercase then the current region or
|
|
symbol under point is used as default input for the search. For instance ~SPC s
|
|
a B~ will search with symbol under point (if there is no active region).
|
|
|
|
If the tool key is omitted then a default tool will be automatically selected
|
|
for the search. This tool corresponds to the first tool found on the system of
|
|
the list =dotspacemacs-search-tools=, the default order is =ag=, =pt=, =ack=
|
|
then =grep=. For instance ~SPC s b~ will search in the opened buffers using =pt=
|
|
if =ag= has not been found on the system.
|
|
|
|
The tool keys are:
|
|
|
|
| Tool | Key |
|
|
|------+-----|
|
|
| ag | a |
|
|
| grep | g |
|
|
| ack | k |
|
|
| 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*:
|
|
- =ag= and =pt= are optimized to be used in a source control repository but
|
|
they can be used in an arbitrary directory as well.
|
|
- It is also possible to search in several directories at once by marking
|
|
them in the helm buffer.
|
|
|
|
*Beware* if you use =pt=, [[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 =helm= buffer, convert a =helm= search buffer into 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 reached with =helm-ag= |
|
|
| Prefix argument | will ask for file extensions |
|
|
|
|
**** 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 |
|
|
|
|
**** 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 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 t f~ | =pt= |
|
|
| ~SPC s t F~ | =pt= 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 |
|
|
|
|
*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. |
|
|
| ~SPC s w w~ | Get Wikipedia suggestions in emacs. Opens Wikipedia page 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 micro-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 micro-state on current symbol and jump forwards |
|
|
| ~#~ | initiate navigation micro-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 |
|
|
|
|
In 'Spacemacs' highlight symbol micro-state:
|
|
|
|
| Key Binding | Description |
|
|
|---------------+---------------------------------------------------------------|
|
|
| ~e~ | edit occurrences (*) |
|
|
| ~n~ | go to next occurrence |
|
|
| ~N~ | 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) |
|
|
| Any other key | leave the navigation micro-state |
|
|
|
|
(*) using [[https://github.com/tsdh/iedit][iedit]] or the default implementation
|
|
of =auto-highlight-symbol=
|
|
|
|
The micro-state text in minibuffer display the following information:
|
|
|
|
#+BEGIN_EXAMPLE
|
|
<M> [6/11]* press (n/N) to navigate, (e) to edit, (r) to change range or (R)
|
|
for reset
|
|
#+END_EXAMPLE
|
|
|
|
Where =<M> [x/y]*= is:
|
|
- M: the current range mode
|
|
- =<B>=: whole buffer range
|
|
- =<D>=: current display range
|
|
- =<F>=: current function range
|
|
- =x=: the index of the current highlighted occurrence
|
|
- =y=: the total number of occurrences
|
|
- =*=: appears if there is at least one occurrence which is not currently visible.
|
|
|
|
*** 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 [[Region selection][expand-region]] bindings.
|
|
|
|
*Note*: If the current state is not the =visual state= then pressing ~*~ uses
|
|
auto-highlight-symbol and its micro-state.
|
|
|
|
*** Listing symbols by semantic
|
|
Use =helm-semantic-or-imenu= command from =Helm= to quickly navigate between the
|
|
symbols in a buffer.
|
|
|
|
To list all the symbols of a buffer press: ~SPC s j~
|
|
|
|
*** Helm-swoop
|
|
This is very similar to =moccur=, it displays a =helm= buffer with all the
|
|
occurrences of the word under point. You can then change the search query in
|
|
real-time and navigate between them easily.
|
|
|
|
You can even edit the occurrences directly in the =helm= buffer and apply the
|
|
modifications to the buffer.
|
|
|
|
| Key Binding | Description |
|
|
|-------------+--------------------------------|
|
|
| ~SPC s s~ | execute =helm-swoop= |
|
|
| ~SPC s S~ | execute =helm-multi-swoop= |
|
|
| ~SPC s C-s~ | execute =helm-multi-swoop-all= |
|
|
|
|
** Editing
|
|
*** Paste text
|
|
**** Paste Micro-state
|
|
The paste micro-state can be enabled by settings the variable
|
|
=dotspacemacs-enable-paste-micro-state= to =t=. By default it is disabled.
|
|
|
|
When the micro-state is enabled, pressing ~p~ again will replace the pasted text
|
|
with the previous 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 ~p~ again will replace =bar= with =foo=.
|
|
|
|
| Key Binding | Description |
|
|
|---------------+---------------------------------------------------------------------------|
|
|
| ~p~ or ~P~ | paste the text before or after point and initiate the =paste= micro-state |
|
|
| ~p~ | in micro-state: replace paste text with the previously copied one |
|
|
| ~P~ | in micro-state: replace paste text with the next copied one |
|
|
| ~.~ | paste the same text and leave the micro-state |
|
|
| Any other key | leave the micro-state |
|
|
|
|
**** 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 o~ | use avy to select a link in the buffer and open it |
|
|
| ~SPC x u~ | set the selected text to lower case |
|
|
| ~SPC x U~ | set the selected text to upper case |
|
|
| ~SPC x a a~ | align region (or guessed section) 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 . (for numeric tables) |
|
|
| ~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 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 micro-state) |
|
|
| ~SPC x K~ | move up a line of text (enter micro-state) |
|
|
| ~SPC x l s~ | sort lines |
|
|
| ~SPC x l u~ | uniquify lines |
|
|
| ~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 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 u~ | Search for Unicode characters and insert them into the active buffer. |
|
|
| ~SPC i l l~ | insert lorem-ipsum list |
|
|
| ~SPC i l p~ | insert lorem-ipsum paragraph |
|
|
| ~SPC i l s~ | insert lorem-ipsum sentence |
|
|
|
|
*** 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 micro-state |
|
|
| ~SPC z x =~ | scale up the font and initiate the font scaling micro-state |
|
|
| ~SPC z x -~ | scale down the font and initiate the font scaling micro-state |
|
|
| ~SPC z x 0~ | reset the font size (no scaling) and initiate the font scaling micro-state |
|
|
| ~+~ | increase the font size |
|
|
| ~=~ | increase the font size |
|
|
| ~-~ | decrease the font size |
|
|
| ~0~ | reset the font size |
|
|
| Any other key | leave the font scaling micro-state |
|
|
|
|
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 micro-state |
|
|
| ~SPC z f =~ | zoom in the frame content and initiate the frame scaling micro-state |
|
|
| ~SPC z f -~ | zoom out the frame content and initiate the frame scaling micro-state |
|
|
| ~SPC z f 0~ | reset the frame content size and initiate the frame scaling micro-state |
|
|
| ~+~ | zoom in |
|
|
| ~=~ | zoom in |
|
|
| ~-~ | zoom out |
|
|
| ~0~ | reset zoom |
|
|
| Any other key | leave the zoom frame micro-state |
|
|
|
|
*** Increase/Decrease numbers
|
|
Spacemacs uses [[https://github.com/cofi/evil-numbers][evil-numbers]] to easily increase or increase numbers.
|
|
|
|
| Key Binding | Description |
|
|
|-------------+-----------------------------------------------------------------|
|
|
| ~SPC n +~ | increase the number under point by one and initiate micro-state |
|
|
| ~SPC n -~ | decrease the number under point by one and initiate micro-state |
|
|
|
|
In micro-state:
|
|
|
|
| Key Binding | Description |
|
|
|---------------+----------------------------------------|
|
|
| ~+~ | increase the number under point by one |
|
|
| ~-~ | decrease the number under point by one |
|
|
| Any other key | leave the micro-state |
|
|
|
|
*Tips:* you can increase or decrease a value by more that once by using a prefix
|
|
argument (ie. ~10 SPC n +~ will add 10 to the number under point).
|
|
|
|
*** Spell checking
|
|
Spell checking is enabled by including the [[../layers/spell-checking][spell
|
|
checking]] layer in your dotfile.
|
|
|
|
Keybindings 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/cofi/evil-indent-textobject][evil-indent-textobject]] the following action can be performed in =normal
|
|
state=:
|
|
- ~ii~ - Inner Indentation: the surrounding textblock with the same indentation
|
|
- ~ai~ - Above and Indentation: ~ii~ + the line above with a different indentation
|
|
- ~aI~ - Above and Indentation+: ~ai~ + the line below with a different indentation
|
|
|
|
Example (=|= is the 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
|
|
- ~vai~ will select the whole while loop
|
|
- ~vaI~ 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
|
|
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 =ack= and =pt= as
|
|
well.
|
|
|
|
*** 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 |
|
|
|
|
*Tips:* To comment efficiently a block of line use the combo ~SPC ; SPC y~
|
|
|
|
*** 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 [[http:www.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 parenthesis then slurping 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 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 |
|
|
|
|
** 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.
|
|
|
|
=Helm= is used whenever it is possible.
|
|
|
|
To search in a project see [[Searching in a project][project searching]].
|
|
|
|
=projectile= commands start with p:
|
|
|
|
| Key Binding | Description |
|
|
|-------------+-------------------------------------------------------|
|
|
| ~SPC p !~ | run shell command in root |
|
|
| ~SPC p &~ | run async shell command in 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 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~.
|
|
|
|
** 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 v~ | verify flycheck setup (useful to debug 3rd party tools configuration) |
|
|
|
|
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 k~ | kill compilation |
|
|
| ~SPC c m~ | =helm-make= |
|
|
| ~SPC c r~ | recompile |
|
|
| ~SPC c q~ | close compilation window |
|
|
|
|
** Modes
|
|
*** 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
|
|
|
|
*** Helm
|
|
Spacemacs add =hjkl= navigation to =helm= buffers:
|
|
|
|
| Key Binding | Description |
|
|
|-------------+------------------------------|
|
|
| ~C-h~ | go to next source |
|
|
| ~C-H~ | describe key (replace ~C-h~) |
|
|
| ~C-j~ | go to previous candidate |
|
|
| ~C-k~ | go to next candidate |
|
|
| ~C-l~ | same as ~return~ |
|
|
|
|
** 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 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.
|
|
|
|
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:
|
|
|
|
| Keybinding | 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 z~ | Kill the current frame |
|
|
|
|
** 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 the case 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 : 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/pull/3000][3000th issue (issue)]] | [[https://github.com/malchmih][malchmih]] |
|
|
| [[https://github.com/syl20bnr/spacemacs/pull/4000][4000th issue (issue)]] | [[https://github.com/icymist][icymist]] |
|
|
|
|
** 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]] |
|
|
|
|
** 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]] |
|
|
| 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]] |
|
|
|
|
** 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 contribution layer]] | [[https://github.com/trishume][trishume]] |
|
|
| [[http://oli.me.uk/2014/11/06/spacemacs-emacs-vim/][First blog article on Spacemacs]] | [[https://github.com/Wolfy87][Wolfy87]] |
|
|
| [[https://github.com/syl20bnr/spacemacs/commit/7b44a56263049482ed540ed6815a295633ffe9d1][First contributed banner]] | [[https://github.com/chrisbarrett][chrisbarrett]] |
|
|
|
|
** Specials
|
|
| 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 ([[http://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]] |
|
|
|
|
* Thank you
|
|
[[Using configuration layers][Jokes aside]], 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!
|