diff --git a/core/core-spacemacs-buffer.el b/core/core-spacemacs-buffer.el index f0e46d0d4..dcc158cba 100644 --- a/core/core-spacemacs-buffer.el +++ b/core/core-spacemacs-buffer.el @@ -420,7 +420,7 @@ HPADDING is the horizontal spacing betwee the content line and the frame border. :help-echo "Open the Spacemacs documentation in your browser." :mouse-face 'highlight :follow-link "\C-m" - "https://github.com/syl20bnr/spacemacs/blob/master/doc/DOCUMENTATION.md") + "https://github.com/syl20bnr/spacemacs/blob/master/doc/DOCUMENTATION.org") (insert " ") (widget-create 'url-link :tag (propertize "Gitter Chat" 'face 'font-lock-keyword-face) diff --git a/doc/DOCUMENTATION.md b/doc/DOCUMENTATION.md deleted file mode 100644 index af4d2a22b..000000000 --- a/doc/DOCUMENTATION.md +++ /dev/null @@ -1,2689 +0,0 @@ - -**Table of Contents** - -- [Spacemacs Documentation](#spacemacs-documentation) -- [Core Pillars](#core-pillars) - - [Mnemonic](#mnemonic) - - [Discoverability](#discoverability) - - [Consistency](#consistency) - - [Crowd-Configured](#crowd-configured) -- [Goals](#goals) -- [Screenshots](#screenshots) -- [Who can benefit from this ?](#who-can-benefit-from-this-) -- [Update and Rollback](#update-and-rollback) - - [Update Spacemacs repository](#update-spacemacs-repository) - - [Update packages](#update-packages) -- [Configuration layers](#configuration-layers) - - [Structure](#structure) - - [Extensions and Packages](#extensions-and-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) -- [Dotfile Configuration](#dotfile-configuration) - - [Installation](#installation) - - [Synchronization of dotfile changes](#synchronization-of-dotfile-changes) - - [Content](#content) - - [Using configuration layers](#using-configuration-layers) - - [Setting configuration layers variables](#setting-configuration-layers-variables) - - [Excluding packages](#excluding-packages) - - [Hooks](#hooks) - - [Custom variables](#custom-variables) -- [Main principles](#main-principles) - - [Evil](#evil) - - [Holy](#holy) - - [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) - - [Mouse usage](#mouse-usage) - - [Mode-line](#mode-line) - - [Flycheck integration](#flycheck-integration) - - [Anzu integration](#anzu-integration) - - [Battery status integration](#battery-status-integration) - - [Powerline separators](#powerline-separators) - - [Minor Modes](#minor-modes) -- [Commands](#commands) - - [Vim key bindings](#vim-key-bindings) - - [Escaping](#escaping) - - [Executing Vim and Emacs ex/M-x commands](#executing-vim-and-emacs-exm-x-commands) - - [Leader key](#leader-key) - - [Reserved prefix command for user](#reserved-prefix-command-for-user) - - [Helm](#helm) - - [C-z and Tab switch](#c-z-and-tab-switch) - - [Helm micro-state](#helm-micro-state) - - [Discovering](#discovering) - - [Key bindings](#key-bindings) - - [Guide-key](#guide-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](#pointcursor) - - [Smooth scrolling](#smooth-scrolling) - - [Vim motions with ace-jump mode](#vim-motions-with-ace-jump-mode) - - [ace-link mode](#ace-link-mode) - - [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 manipulation micro-state](#buffers-manipulation-manipulation-micro-state) - - [Special Buffers](#special-buffers) - - [Files manipulations key bindings](#files-manipulations-key-bindings) - - [Emacs and Spacemacs files](#emacs-and-spacemacs-files) - - [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) - - [Bookmarks](#bookmarks) - - [DocView mode](#docview-mode) - - [Searching](#searching) - - [With an external tool](#with-an-external-tool) - - [Searching in an arbitrary directory](#searching-in-an-arbitrary-directory) - - [Searching in a project](#searching-in-a-project) - - [Searching the web](#searching-the-web) - - [Persistent highlighting](#persistent-highlighting) - - [Stacking highlights](#stacking-highlights) - - [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) - - [Smartparens Strict mode](#smartparens-strict-mode) - - [Zooming](#zooming) - - [Text](#text) - - [Frame](#frame) - - [Increase/Decrease numbers](#increasedecrease-numbers) - - [Spell checking](#spell-checking) - - [Region selection](#region-selection) - - [Expand-region](#expand-region) - - [Indent text object](#indent-text-object) - - [Region narrowing](#region-narrowing) - - [Line formatting](#line-formatting) - - [Replacing text with iedit](#replacing-text-with-iedit) - - [iedit states key bindings](#iedit-states-key-bindings) - - [State transitions](#state-transitions) - - [In iedit state](#in-iedit-state) - - [In iedit-insert state](#in-iedit-insert-state) - - [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) - - [Lisp state key bindings](#lisp-state-key-bindings) - - [Emacs lisp specific key bindings](#emacs-lisp-specific-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) - - [Python](#python) - - [JavaScript](#javascript) - - [HTML and CSS](#html-and-css) -- [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) - - [I have no file ~/.spacemacs](#i-have-no-file-spacemacs) -- [Achievements](#achievements) - - [Issues](#issues) - - [Merged Pull Requests](#merged-pull-requests) - - [Stars, forks and watchers](#stars-forks-and-watchers) - - [Specials](#specials) -- [Thank you](#thank-you) - - -# Spacemacs Documentation - - -# Core Pillars - -Four core pillars: Mnemonic, Discoverability, Consistency, "Crowd-Configured". - -If any of these core pillars is violated open an issue and we'll fix it. - -## Mnemonic - -`Spacemacs` organizes key bindings by mnemonic namespaces as much as possible. -If you are looking for commands to operate on your buffer, they are right under -SPC b, if you want to operate on your project, then it is -SPC p, etc... - -## Discoverability - -`Spacemacs` comes with a dedicated major mode `spacemacs-mode`. Its goal is to -give useful feedbacks and easily perform maintenance tasks. - -It also comes with dedicated [helm][helm-link] sources to quickly find layers, packages -and more. - -[guide-key][] is enabled by default, it will display all the available key -bindings in a dedicated popup buffer. - -## Consistency - -Similar functionalities should have the same key binding no matter which major -is currently active. For instance if you are looking for the definition of a -function, the binding is SPC m g g, `m` for `major mode` and `g g` -for `go to thing at point`. No matter what is the major mode it is the same -binding to perform this action. - -This is also true for the documentation, each configuration layer comes with -an associated `README.md` file with the same base layout. - -The consistency core pillar is supported by a convention file: -[CONVENTIONS.md][] - -## Crowd-Configured - -By defining an very light structure called `configuration layer` which is easy -to understand, `Spacemacs` makes it easy to contribute additional support. - -The conventions in [CONVENTIONS.md][] make it easy to get the spacemacs way -and keep consistency even if there are a lot of contributions. - -`Crowd-configuration` is the most powerful pillar of `Spacemacs`. Anybody can -submit upstream improvements to configuration layers or a whole new one. Any -user can easily and directly use this layer by adding it to a list in a -dotfile. It is even possible to exclude _any_ unwanted packages. - -# Goals - -- **Bring the power of modal editing** to the powerful Emacs editing platform. - -- Integrate nicely with `Evil` states (`Vim` modes): `Spacemacs` tries to -**keep your fingers on the home row** as much as possible, no matter the mode -you are in. - -- **Crowd-configured**: Contribute easily your improvements and new -configuration layers. - -- **Minimalistic and nice graphical UI**, keep your available screen space for -what matters: your text files. - -- **Mnemonic and consistent key bindings** which should be easier to learn -and remember and be the same in all major modes. - -- **Fast boot time**, everything is lazy-loaded. - -- **Lower the risk of RSI** by heavily using the space bar instead of modifiers. - -- Hopefully, if it's not already the case: - -Ɛ>Ɛ>Ɛ> **make you love modal editing!** <3<3<3 - -# Screenshots - -_Startup_ -![spacemacs_startup](img/spacemacs-startup.png) - -_Python_ -![spacemacs_python](img/spacemacs-python.png) - -_Terminal (urxvt)_ -![spacemacs_urxvt](img/spacemacs-urxvt.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` is first intended to be used by **Vim users** who want to go to the -next level by using Emacs. There is a [guide][vim-migration] for these users to -supplement the documentation. - -It is also a good fit for people wanting to **lower the [risk of RSI][RSI]** -induced by the default Emacs key bindings (this is an assumption, there is no -official studies to prove this). - -Emacs users wanting to learn **a different way to edit files** or wanting to -learn Vim key bindings. - -As a side note, if you are a programmer and you don't know Vim key bindings -yet, I deeply recommend you to learn the basics as recommended in -[Sacha Chua's one-page guide][sacha_guide] about how to learn Emacs. - -# Update and Rollback - -For now it is still needed to update the `Spacemacs` repository manually. - -## Update Spacemacs repository - -Close Emacs and update the git repository: - - ```sh - git pull --rebase - git submodule sync; git submodule update - ``` - -**Note** It is recommended to update the packages first, see next session. - -## Update packages - -To update `Spacemacs` press RET (enter) or click on the link -`[Update]` in the startup page under the banner then restart Emacs. - -If anything goes wrong you should be able to rollback the update by pressing -RET or clicking on the `[Rollback]` link next to the `[Update]` -link and choose a rollback slot (sorted by date). - -# Configuration layers - -## Structure - -Configuration is organized in layers. Each layer has the following structure: - -``` -[layer_name] - |__ [extensions] - | |__ [mode 1] - | | ... - | |__ [mode n] - |__ config.el - |__ extensions.el - |__ funcs.el - |__ keybindings.el - |__ packages.el - -[] = directory -``` - -Where: - - File | Usage -------------------|----------------------------------------------------------- -config.el | Emacs built-in configuration or mandatory configuration -extensions.el | The list of extensions to load and the functions to initialize them -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, and `Extensions` are generally elisp code from git submodules. - -## Extensions and Packages - -### Within a layer - -#### Declaration - -`Extensions` and `Packages` are declared in variables `-pre-extensions`, -`-post-extensions` and `-packages` where `` is the layer -name. `Pre-Extensions` are loaded before `Packages` and `Post-Extensions` are -loaded after `Packages`. - -They are processed in alphabetical order so sometimes you'll have to use -some `eval-after-load` black magic. - -Example: - -```elisp -(setq -packages - '( - package1 - package2 - ... - ) -``` - -#### Initialization - -To initialize an extension or a package `xxx`, define a function with this -format in `extensions.el` or `packages.el`: - -```elisp -(defun /init-xxx () - ...body -) -``` - -It is common to define the body with the [use-package][use-package] macro. - -#### Exclusion - -It is possible to exclude some packages from `Spacemacs` in 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 -`-excluded-packages`. - -Example: - -```elisp -(setq -excluded-packages - '( - package1 - package2 - ... - ) -``` - -### Without a layer - -Sometimes a layer can be an unnecessary overhead, this is the case if you just -want yo 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/config` function. - -Example to install `llvm-mode` and `dts-mode`: - -```elisp -(setq dotspacemacs-additional-packages - '( - llvm-mode - dts-mode - ) -``` - -## Packages synchronization (Vundle like feature) - -`Spacemacs` features a synchronization engine for the ELPA packages. It means -that `Spacemacs` will auto-install the new packages in `-packages` lists -_and_ auto-delete orphan packages in your `elpa` directory. - -It effectively makes `Spacemacs` behave like [Vundle][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 `contrib` 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 [CONTRIBUTE.md][]. - -## Example: Themes Megapack example - -This is a simple `contrib` configuration layer listing a bunch of themes, -you can find it [here][themes-megapack]. - -To install it, just add `themes-megapack` to your `~/.spacemacs` like so: - -```elisp -(setq-default dotspacemacs-configuration-layers '(themes-megapack)) -``` - -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`. - -# Dotfile Configuration - -User configuration can be stored in your `~/.spacemacs` file. - -## Installation - -`~/.spacemacs` is an optional file. If you want to use it you have to copy it -manually from the template file `~/.emacs.d/core/templates/.spacemacs.template` - -```sh -$ cp ~/.emacs.d/core/templates/.spacemacs.template ~/.spacemacs -``` - -## Synchronization of dotfile changes - -To apply the modifications made in `~/.spacemacs` press SPC f e R. -It will re-execute the `Spacemacs` initialization process. - -**Note:** A synchronization re-execute the functions `dotspacemacs/init` and -`dotspacemacs/config`. Depending on the content of this functions you may -encounter some unwanted side effects. For instance if you use a toggle in -`dotspacemac/config` to enable some behavior, this behavior will be turned off -whenever the dotfile is re-synchronize. To avoid these side-effects it is -recommended to use `setq` expressions instead of toggle functions. -It is also possible to _skip_ the execution of `dotspacemacs/config` with the -universal argument (SPC u 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 [RMS](#thank-you): -```elisp -(setq-default dotspacemacs-configuration-layers '(rms)) -``` -If this layer does not exist you can still try another one in -[the `contrib` directory](../contrib). - -Configuration layers are expected to be stored in `~/.emacs.d/private` or -`~/.emacs.d/contrib`. 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`: - -```elisp -(setq-default dotspacemacs-configuration-layer-path '("~/.myconfig/")) -``` - -### Setting configuration layers variables - -Some configuration layers have configuration variables to enable specific -support. For instance the [git layer][] has several configuration variables, -they can be set directly in the `dotspacemacs-configuration-layers` like this: - -```elisp -;; List of configuration layers to load. -dotspacemacs-configuration-layers '(auto-completion - (git :variables - git-magit-status-fullscreen t) - smex) -``` - -### Excluding packages - -You can exclude packages you don't want to install with the variable -`dotspacemacs-excluded-packages`, this variable can exclude both packages and -extensions (see [Configuration layers](#configuration-layers) for more info -on packages and extensions). - -For instance to disable the `rainbow-delimiters` package: -```elisp -(setq-default dotspacemacs-excluded-packages '(rainbow-delimiters)) -``` - -When you exclude a package, `Spacemacs` will automatically delete it for you -the next time you launch Emacs. All the orphan dependencies are as well -delete automatically. - -### Hooks - -Two 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. -- `dotspacemacs/config` is triggered at the very end of `Spacemacs` loading. - -### 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 - -## Evil - -`Spacemacs` uses the [evil][evil] mode to emulate Vim key bindings. It is a -very complete emulation, maybe the most advanced. In fact, Evil is much more -than just a Vim emulation. It has more states than Vim for instance. - -## Holy - -Thanks to the new holy-mode Spacemacs can now be used by Vim users or Emacs -users by setting the `dotspacemacs-editing-style` variable to `’vim` or `’emacs` -in the dotfile. In Emacs style the leader is available as `M-m`. It is possible -to dynamically switch between evil and holy modes using `SPC P tab`. - -### States - -`Spacemacs` has 9 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 -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 [info](#editing-lisp-code)) -iedit | red | exclusive to `Spacemacs`, used to navigate between multiple regions of text using `iedit` (more [info](#replacing-text-with-iedit)) -iedit-insert | red | exclusive to `Spacemacs`, used to replace multiple regions of text using `iedit` (more [info](#replacing-text-with-iedit)) - -Note: Technically speaking there are also the `operator` and `replace` evil -states. - -## Evil leader - -`Spacemacs` heavily uses the [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 [RSI][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 s - -## 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. - -## 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](#auto-highlight-and-edition-of-symbols): -![spacemacs_ahs_micro_state](img/spacemacs-ahs-micro-state.png) - -[Text scale micro-state](#change-font-size): -![spacemacs_scale_micro_state](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). - -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 [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/config` function or -your `~/.spacemacs`): - -```elisp -(evil-define-key 'visual evil-surround-mode-map "s" 'evil-substitute) -(evil-define-key 'visual evil-surround-mode-map "S" 'evil-surround-region) -``` - -# Evil plugins - -`Spacemacs` ships with the following evil plugins: - - Mode | Description -----------------------------------------|-------------------------------------- -[evil-leader][] | vim leader that bring a new layer of keys in normal mode -[evil-indent-textobject][] | add text object based on indentation level -[evil-visualstar][] | search for current selection with `*` -[evil-exchange][] | port of [vim-exchange][] -[evil-surround][] | port of [vim-surround][] -[evil-matchit][] | port of [matchit.vim][] -[evil-nerd-commenter][] | port of [nerdcommenter][] -[evil-search-highlight-persist][] | emulation of hlsearch behavior -[evil-numbers][] | like C-a/C-x in vim -[evil-args][] | motions and text objects for arguments -[evil-jumper][] | jump list emulation -[NeoTree][neotree] | mimic [NERD Tree][nerdtree] - -# 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` - - a [guide-key][] buffer - -## Graphical UI - -`Spacemacs` has a minimalistic and distraction free graphical UI: -- custom [powerline][powerline] mode-line -[with color feedback](#flycheck-integration) according to current - [Flycheck][flycheck] status - - unicode symbols for minor mode lighters which appear in the mode-line - - [custom fringe bitmaps](#errors-handling) and error feedbacks for - [Flycheck][flycheck] - - [custom fringe bitmaps](../contrib/git/README.md#git-gutter-bitmaps) for - git gutter (available in [git layer][]) - -### Color themes - -By default, `Spacemacs` uses the theme [solarized-light][solarized-theme]. - -It is possible to define your default themes in your `~/.spacemacs` with -the variable `dotspacemacs-themes`. For instance, to specify `leuven` and -`zenburn` (high contrast theme and low contrast theme): - -```elisp -(setq-default dotspacemacs-themes '(leuven zenburn)) -``` - - Key Binding | Description ----------------------|------------------------------------------------------------ -SPC T n | switch to next theme listed in `dotspacemacs-themes`. -SPC T h | select a theme using a `helm` buffer. - -**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. - -**Hint** If you are an `Org` user, [leuven-theme][] is amazing ;-) - -### Font - -The default font used by `Spacemacs` is [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: - -```elisp -(setq-default dotspacemacs-default-font '("Source Code Pro" - :size 13 - :weight normal - :width normal - :powerline-scale 1.1)) -``` - -The properties should be pretty straightforward, it is possible to set any -valid property of a [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_ - -![ugly-separators](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 ~ | display `~` in the fringe on empty lines -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 | show the absolute line numbers - - Key Binding | Description -------------------------|------------------------------------------------------------ -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 - -**Note** These toggles are all available via the `helm-spacemacs` interface -(press SPC f e h to display the `helm-spacemacs` buffer). - -### 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 [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 -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 f | toggle the flycheck info (available in `syntax-checking` layer) -SPC t m m | toggle the minor mode lighters -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 new version lighter - -#### Flycheck integration - -When [Flycheck][flycheck] minor mode is enabled, a new element appears showing -the number of errors, warnings and info. - -![powerline-wave](img/powerline-wave.png) - -#### Anzu integration - -[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. - -![powerline-anzu](img/powerline-anzu.png) - -#### Battery status integration - -[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: - -```elisp -(defun dotspacemacs/config () - "This is were you can ultimately override default Spacemacs configuration. -This function is called at the very end of Spacemacs initialization." - (setq powerline-default-separator 'arrow) -) -``` - -To save you the time to try all the possible separators provided by the -powerline, here is an exhaustive set of screenshots: - - Separator | Screenshot -------------------|------------------------------------------------------------ -`alternate` | ![powerline-alternate](img/powerline-alternate.png) -`arrow` | ![powerline-arrow](img/powerline-arrow.png) -`arrow-fade` | ![powerline-arrow-fade](img/powerline-arrow-fade.png) -`bar` | ![powerline-bar](img/powerline-bar.png) -`box` | ![powerline-box](img/powerline-box.png) -`brace` | ![powerline-brace](img/powerline-brace.png) -`butt` | ![powerline-butt](img/powerline-butt.png) -`chamfer` | ![powerline-chamfer](img/powerline-chamfer.png) -`contour` | ![powerline-contour](img/powerline-contour.png) -`curve` | ![powerline-curve](img/powerline-curve.png) -`rounded` | ![powerline-rounded](img/powerline-rounded.png) -`roundstub` | ![powerline-roundstub](img/powerline-roundstub.png) -`slant` | ![powerline-slant](img/powerline-slant.png) -`wave` | ![powerline-wave](img/powerline-wave.png) -`zigzag` | ![powerline-zigzag](img/powerline-zigzag.png) -`nil` | ![powerline-nil](img/powerline-nil.png) - -#### Minor Modes - -`Spacemacs` uses [diminish][diminish] mode to reduce the size of minor mode -indicators: - -The minor mode area can be toggled on and off with: - - 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 glocal. The global version of the -toggle can be reached using the `control` key. - -Key Binding | Unicode | ASCII | Mode ----------------------|:-----------:|:----------:|---------------------------------------------------- -SPC t - | `⊝` | - | [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 | [evil-org][evil-org-mode] mode -SPC t c | | | fill-column-indicator mode -SPC t F | `Ⓕ` | F | auto-fill mode -SPC t g | `ⓖ` | g | [golden-ratio][] mode -SPC t k | `Ⓖ` | G | guide-key mode -SPC t i | `ⓘ` | i | indentation guide -SPC t C-i | | | global indentation guide -SPC t I | `Ⓘ` | I | aggressive indent mode -SPC t p | `ⓟ` | p | [smartparens][sp] mode -SPC t C-p | | | global smartparens -SPC t s | `ⓢ` | s | syntax checking (flycheck) -SPC t S | `Ⓢ` | S | spell checking (flyspell) -SPC t w | `ⓦ` | w | whitespace mode -SPC t C-w | | | global whitespace -SPC t y | `ⓨ` | y | [yasnippet][yasnippet] mode - -# 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 - [evil tutor][] lessons by pressing SPC h T at any time. - -### Escaping - -`Spacemacs` uses [evil-escape][] to easily switch between `insert state` and -`normal state` by quickly pressing the fd keys. - -The choice of `fd` was made to be able to use the same sequence to escape from -"everything" in Emacs: -- escape from all evil states to normal state -- escape from evil-lisp-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 -- 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 s work again). - -This sequence can be customized in your `~/.spacemacs`. Example to set it -to `jj` (it is important set the variable in `dotspacemacs/init`): - -```elisp -(defun dotspacemacs/init () - (setq-default evil-escape-key-sequence "jj")) -``` - -**Note:** Although `jj` or `jk` are popular choices of vim users, these key -sequences are not optimal for `Spacemacs`. Indeed it is very easy in -`visual state` to press quickly `jj` and inadvertently escape to `normal state`. - -**Important Note** One caveat of `evil-escape` is that you must not use it -while recording macros. Use `escape` key instead. - -### Executing Vim and Emacs ex/M-x commands - - Command | Key Binding -:---------------:|------------------------------------------------------------------ -Vim (ex-command) | `:` -Emacs (M-x) | SPC : - -The command key `:` can be easily changed with the variable -`dotspacemacs-command-key` of your `~/.spacemacs`. Note that is will change both -`:` and `SPC :` bindings to keep the symmetry between Vim and Emacs. A good -key can be `,` for example. - -### 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`. - -## Reserved prefix command for user - -SPC o is reserved for the user. Setting key bindings behind -` o` is **guaranteed** to never conflict with `Spacemacs` defaults key -bindings. - -**Example:** -Put `(evil-leader/set-key "oc" 'org-capture)` inside `dotspacemacs/config` -in your `~/.spacemacs` file, to be able to use SPC o c to run -org mode capture. - -## Helm - -`Spacemacs` is powered by [Helm][helm-link] 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 [Helm documentation wiki][helm-doc]. - -### 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 [here][tuhdo-tuto]. - -### Helm micro-state - -`Spacemacs` defines a [micro-state](#micro-states) for `Helm` to make it -work like [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 or leave the 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 -q | quit micro-state -t | mark current candidate -T | mark all candidates -v | execute persistent action - -## Discovering - -### Key bindings - -#### Guide-key - -An 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 [guide-key][] buffer will be displayed quickly after the key -has been pressed. You can change the delay by setting the variable -`dotspacemacs-guide-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 f | describe a function -SPC h d k | describe a key -SPC h d m | describe current modes -SPC h d p | describe a package -SPC h d t | describe a theme -SPC h d v | describe a variable - -Other help key bindings - -Key Binding | Description ----------------------|------------------------------------------------------------------ -SPC h i | search in info pages with the symbol at point -SPC h m | search available man pages - -### Available layers - -All layers can be easily discovered via `helm-spacemacs` accessible with -SPC f e h. - -The following helm actions are available: -- default: open the layer `README.md` -- 2nd: open the layer `packages.el` -- 3nd: open the layer `extensions.el` - -#### Available packages in Spacemacs - -`helm-spacemacs` 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]` link on the -`Spacemacs` startup page instead. - -`Spacemacs` proposes to use [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 ----------------------|------------------------------------------------------------ -/ | 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` 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 quickly up (10 lines at a time) -`L` | move quickly down (10 lines at a time) -SPC j h | go to the beginning of line (and set a mark at the previous location in the line) -SPC j l | go to the end of line (and set a mark at the previous location in the line) -SPC z z | lock the cursor at the center of the screen - -#### 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`: - -```elisp -(setq-default dotspacemacs-smooth-scrolling t) -``` - -### Vim motions with ace-jump mode - -`Spacemacs` uses the `evil` integration of [ace-jump mode][ace-jump] which -enables the invocation of `ace-jump-mode` during motions. - -It is useful for deleting visually a set of lines, try the following sequence -in a buffer containing some text: - - d l - -Key Binding | Description ----------------------|------------------------------------------------------------------ -SPC SPC | initiate ace jump word mode -SPC l | initiate ace jump line mode -SPC ` | go back to the previous location (before the jump) - -Hint: you may change to char mode by `C-c C-c` in word mode. - -#### ace-link mode - -Similar to `ace-jump-mode`, [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` - -### 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 ` 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 [ace-delete-window][ace-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 W | select window using [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 [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: - - 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 return 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 (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 the current 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 [ace-swap-window][ace-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 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 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 [special buffer howto][]. - -#### Files manipulations key bindings - -Files manipulation commands (start with `f`): - -Key Binding | Description -------------------------------------------|---------------------------------------------------------------- -SPC f D | delete a file and the associated buffer (ask for confirmation) -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 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 [NeoTree][neotree] -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 h | discover `Spacemacs` layers and packages using `helm` -SPC f e i | open the all mighty `init.el` -SPC f e R | resync the dotfile with spacemacs -SPC f e s | open `ido` in the `spacemacs` layer folder -SPC f e v | display and copy the spacemacs version - -### Ido - -`Spacemacs` displays the `ido` minibuffer vertically thanks to the -[ido-vertical-mode][ido-vertical-mode]. - -Basic `ido` operations can be done with `Ctrl` key: - -Key Binding | Description -------------------------|---------------------------------------------------------------- -C-\ | open a `dired buffer` -M-\ | 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 | next history element -C-S-k | previous history element -C-S-l | go to next directory -C-S-nC-S-pM-SPC or s-M-SPC -while in a `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 [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. - -#### NeoTree navigation - -Navigation is centered on the `hjkl` with the hope to provide a fast navigation -experience like in [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 the windows 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 2 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 -g | 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 - -### Bookmarks - -Bookmarks can be set anywhere in a file. Bookmarks are persistent. They are very -useful to jump to/open a known project. `Spacemacs` used `helm-bookmarks` to -manage them. - -Open an `helm` window with the current bookmarks by pressing: - - h b - -Then in the `helm-bookmarks` buffer: - -Key Binding | Description --------------------|---------------------------------------------------------------- -CTRL+d | delete the selected bookmark -CTRL+e | edit the selected bookmark -CTRL+f | toggle filename location -CTRL+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 - -## Searching - - -### With an external tool - -`Spacemacs` can be interfaced with different search utilities: -- ack -- grep -- [ag][] -- [pt][] - -**Note** `ag` and `pt` are optimized to be used in a source control repository -but they can be used in an arbitrary directory as well. - -By default Spacemacs will look for the first installed tool in the list -`("ag", "pt", "ack", "grep")`. This list can be changed in the dotfile with -the variable `dotspacemacs-search-tools`. - -**Beware** if you use `pt`, [TCL parser tools][tcl] also install a command line -tool called `pt`. - -#### Searching in an arbitrary directory - -To use these utilities in one or several arbitrary directories: - -Key Binding | Description ---------------------------|--------------------------------------------- -SPC s / | execute the first found utility (by default `ag`, `pt`, `ack` and `grep`) -SPC s a | `ag` -SPC s g | `grep` -SPC s G | `grep` defaults to symbol at point -SPC s k | `ack` -SPC s p | `pt` -SPC s L | open stored search buffer (stored with F3 in helm search buffer) - -**Note** Use the universal argument to change the search list of -SPC s / to `ack` and `grep` (does not look for `ag` or `pt`). - -**Note** It is also possible to search in several directories at once by -marking them in the helm buffer. - -**Pro Tip** Use F3 in the helm search buffer to save the list of - results to a buffer. - -#### Searching in a project - -To use these utilities in a project using `projectile`: - -Key Binding | Description ---------------------------|--------------------------------------------- -SPC / | execute the first found utility (by default `ag`, `pt`, `ack` and `grep`) -SPC p s a | `ag` -SPC p s A | `ag` with symbol at point as default text -SPC p s g | `grep` defaults to current region then symbol at point -SPC p s k | `ack` -SPC p s K | `ack` with symbol at point as default text -SPC p s p | `pt` -SPC p s P | `pt` with symbol at point as default text - -**Pro Tip** Use SPC h l to bring back the last helm session. - - -#### 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`. - -### Stacking highlights - -With [hl-anything][] it is possible to highlight all occurrences of the word -under point. The highlights can be stacked. - -Key Binding | Description ------------------------|---------------------------------------------------------------- -SPC h c | clear the highlightings -SPC h g c | clear the highlightings globally (all opened buffers) -SPC h h | highlight all occurrence of the word at point -SPC h g h | highlight all occurrence of the word at point globally (all opened buffers) -SPC h n | next highlighted occurrence -SPC h N | previous highlighted occurrence -SPC h p | toggle auto-highlight of the enclosing parenthesis -SPC h r | restore saved highlights in the current buffer -SPC h s | save current highlights - -### Highlight current symbol - -`Spacemacs` supports highlighting of the current symbol on demand (provided by -the [auto-highlight-symbol][auto-highlight] 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 b | go to the last searched occurrence of the last highlighted symbol -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 R | change range to default (`whole buffer`) - -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 [iedit][] or the default implementation of `auto-highlight-symbol` - -The micro-state text in minibuffer display the following information: - - [6/11]* press (n/N) to navigate, (e) to edit, (r) to change range or (R) for reset - -Where ` [x/y]*` is: -- M: the current range mode - - ``: whole buffer range - - ``: current display range - - ``: 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 [evil-visualstar][] you can search for the next occurrence of the current -selection. - -It is pretty useful combined with the [expand-region](#region-selection) -bindings. - -_Note:_ If the current state is not the `visual state` then pressing `*` uses -[auto-highlight-symbol](#auto-highlight-symbols) 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: - - s l - -### 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/config` function. - -### Text manipulation commands - -Text related commands (start with `x`): - - Key Binding | Description ------------------------|------------------------------------------------------------ -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 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 | move down a line of text (enter micro-state) -SPC x K | move up a line of text (enter micro-state) -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 words in the selection region -SPC x w C | count the number of occurrences per word in the select region - -### Smartparens Strict mode - -[Smartparens][sp] 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`. - -```elisp -(setq-default dotspacemacs-smartparens-strict-mode t) -``` - -### 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 down the font and initiate the font scaling micro-state -SPC z x = | reset the font size (no scaling) and initiate the font scaling micro-state -+ | increase the font size -- | decrease the font size -= | 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 -SPC z f - | zoom out the frame content -SPC z f = | reset the frame content size -+ | zoom in -- | zoom out -= | reset zoom -Any other key | leave the zoom frame micro-state - -### Increase/Decrease numbers - -`Spacemacs` uses [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 commands start with `S`: - - Key Binding | Description ----------------------|------------------------------------------------------------ -SPC S c | list of corrections in a `helm` buffer -SPC S d | change dictionary language -SPC S n | go to the next spell check error - - -### Region selection - -Vi `Visual` modes are all supported by `evil`. - -#### Expand-region - -`Spacemacs` adds another `Visual` mode via the [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 [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): - -```elisp -(while (not done) - (messa|ge "All work and no play makes Jack a dull boy.")) -(1+ 41) -``` - -- 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 - -### Line formatting - -`Spacemacs` performs `go to the line below point and indent it` with -SPC j k. -You may repeat this operation with `evil-repeat` if you need to indent many lines. - -Line formatting commands start with `j`: - - Key Binding | Description ----------------------------|------------------------------------------------------------ -J | join the current line with the next line -SPC j j | same as SPC j k but will split the current line at point -SPC J | split a quoted string or s-expression in place -SPC j J | split a quoted string or s-expression and auto-indent -SPC j k | go to next line and indent it using auto-indent rules - -Used together these key bindings are very powerful to quickly reformat the code. - -### Replacing text with iedit - -`Spacemacs` uses the powerful [iedit][] mode through [evil-iedit-state][] to -quickly edit multiple occurrences of a symbol or selection. - -`evil-iedit-state` defines two new evil states: -- `iedit state` -- `iedit-insert state` - -The color code for these states is `red`. - -`evil-iedit-state` has also a nice integration with [expand-region][] for quick -edition of the current 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 edition scope by one line below -K | increase the edition 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 -[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 [evil-nerd-commenter][], it's bound to the following keys. - - Key Binding | Description ----------------------|------------------------------------------------------------ -SPC ; | comment operator -SPC c i | comment invert -SPC c l | comment lines -SPC c p | comment paragraphs -SPC c r | comment region -SPC c t | comment to line -SPC c y | comment and yank - -**Tips:** To comment efficiently a block of line use the combo: - - ; l - -### 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 -[homebrew][] with the following command: - -```sh -$ brew install trash -``` - -To disable the trash you can set the variable `delete-by-moving-to-trash` -to `nil` in your `~/.spacemacs`. - -### Editing Lisp code - -Edition of lisp code is provided by [evil-lisp-state][]. - -Commands will set the current state to `lisp state` where -different commands combo can be repeated without pressing on -SPC m. - -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 n -- to wrap a symbol in parenthesis then slurping two times: SPC k w 2 n - -**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 kill 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 | forwared 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 [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 [project searching](#searching-in-a-project). - -`projectile` commands start with p: - - Key Binding | Description ----------------------|------------------------------------------------------------ -SPC / | search in project with the best search tool available -SPC p ! | run shell command in root -SPC p & | run async shell command in root -SPC p s a | run `ag` -SPC p s k | run `ack` -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 s g | run `grep` -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 | regenerate the project's [e|g]tags -SPC p r | replace a string -SPC p s | see [search in project](#searching-in-a-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 - -## 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 [Flycheck][flycheck] to gives error feedback on the fly. -The checks are only performed at save time by default. - -Errors management commands (star with `e`): - - Key Binding | Description ----------------------|------------------------------------------------------------ -SPC e c | clear all errors -SPC e f | toggle flycheck -SPC e l | display the `flycheck` list of errors/warnings -SPC e n | go to the next error -SPC e p | go to the previous error - -Custom fringe bitmaps: - - Symbol | Description -:----------------------------------:|------------ -![dot-error](img/dot-error.png) | Error -![dot-warning](img/dot-warning.png) | warning -![dot-info](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 r | recompile - -## 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: - -```elisp -(setq-default dotspacemacs-major-mode-leader-key "") -``` - -### Helm - -`Spacemacs` add `hjkl` navigation to `helm` buffers: - - Key Binding | Description -------------------|------------------------------------------------------------ -CTRL+h | go to previous page -CTRL+j | go to previous item -CTRL+k | go to next item -CTRL+l | go to next page - -### Python - -Writing python code with spacemacs is supported by python contribution. Please -see [python contribution][python-contrib] documentation for detail. - -### JavaScript - -More featured JavaScript support is provided by the javascript -contribution. Please see [javascript contribution][javascript-contrib] -documentation for detail. - -### HTML and CSS - -HTML contribution provides support for editing HTML, CSS, Scss and Less -files. Please see [html contribution][html-contrib] documentation for detail. - -# 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, use -`export EDITOR="emacsclient -c"` in your shell configuration. - -Note that if you're on OS X, you may have to refer to the emacsclient that comes -with your GUI Emacs, e.g. `export -EDITOR="/Applications/Emacs.app/Contents/MacOS/bin/emacsclient -c"`. - -Tip: Remember to use `:wq` or `C-x #` after you are done editing the file -in Emacs. - -See [Emacs as a Server][] in the official Emacs manual for more details. - -## 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`. - -```elisp -(setq-default dotspacemacs-persistent-server t) -``` - -When this variable is set to `t`, the only way to quit Emacs _and_ kill the -server is to use the following bindings: - - Key Binding | Description --------------------|------------------------------------------------------------ -SPC q q | Quit Emacs and kill the server, prompt for changed buffers to save -SPC q Q | Quit Emacs and kill the server, lose all unsaved changes. -SPC q 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 [Github issue][issues] with the backtrace. - -### I have no file ~/.spacemacs - -You have to manually copy the `~/.emacs.d/core/templates/.spacemacs.template` -file to `~/.spacemacs` - -# Achievements - -## Issues - -Achievements | Account ------------------------------------------------------|------------------------ -[100th issue (PR)][100th-issue] | [danielwuz][] -[200th issue (question)][200th-issue] | [justrajdeep][] -[300th issue (PR)][300th-issue] | [danielwuz][] -[400th issue (PR)][400th-issue] | [CestDiego][] -[500th issue (PR)][500th-issue] | [bjarkevad][] -[600th issue (PR)][600th-issue] | [bjarkevad][] -[700th issue (enhancement)][700th-issue] | [jcpetkovich][] -[800th issue (PR)][800th-issue] | [ryansroberts][] -[900th issue (PR)][900th-issue] | [jcpetkovich][] -[1000th issue (PR)][1000th-issue] | [tuhdo][] - -## Merged Pull Requests - -Achievements | Account ------------------------------------------------------|------------------------ -[100th pull request][100th-PR] | [bru][] -[200th pull request][200th-PR] | [smt][] -[300th pull request][300th-PR] | [BrianHicks][] -[400th pull request][400th-PR] | [cpaulik][] -[500th pull request][500th-PR] | [tuhdo][] -[600th pull request][600th-PR] | [trishume][] - -## Stars, forks and watchers - -Achievements | Account ------------------------------------------------------|------------------------ -100th watcher | [adouzzy][] -100th fork | [balajisivaraman][] -200th fork | [alcol80][] -300th fork | [mlopes][] -100th star | [Jackneill][] -200th star | [jb55][] -400th star | [dbohdan][] -600th star | [laat][] -700th star | [kendall][] -800th star | [urso][] -900th star | [luisgerhorst][] -1000th star! | [rashly][] - -## Specials - -Achievements | Account ------------------------------------------------------|------------------------ -[First contribution][1st-contrib] | [trishume][] -[First contribution layer][1st-clayer] | [trishume][] -[First blog article on Spacemacs][1st-article] | [Wolfy87][] -[First contributed banner][1st-cbanner] | [chrisbarrett][] -The Gunner (made 18 PRs in a row) | [ralesi][] -The Saint (unlocked the holy-mode) | [trishume][] -The Artist (made the spacemacs logo) | [nashamri][] -The Meme Master (made the doge banner) | [chrisbarrett][] -The Helm captain (see [here][tuhdo-tuto]) | [tuhdo][] - -# Thank you - -[Jokes aside](#using-configuration-layers), 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! - -[CONVENTIONS.md]: ./CONVENTIONS.md -[evil]: https://gitorious.org/evil/pages/Home -[evil-leader]: https://github.com/cofi/evil-leader -[RSI]: http://en.wikipedia.org/wiki/Repetitive_strain_injury -[vim-migration]: ./VIMUSERS.org -[sacha_guide]: http://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand-drawn-one-pager-for-beginners/ -[use-package]: https://github.com/jwiegley/use-package -[keychords]: http://www.emacswiki.org/emacs/KeyChord -[centered-cursor]: http://www.emacswiki.org/emacs/centered-cursor-mode.el -[ace-jump]: https://github.com/winterTTr/ace-jump-mode -[ace-link]: https://github.com/abo-abo/ace-link -[ace-window]: https://github.com/abo-abo/ace-window -[helm-link]: https://github.com/emacs-helm/helm -[helm-doc]: https://github.com/emacs-helm/helm/wiki -[helm-ag]: https://github.com/syohex/emacs-helm-ag -[popwin]: http://www.emacswiki.org/emacs/PopWin -[golden-ratio]: https://github.com/roman/golden-ratio.el -[solarized-theme]: https://github.com/bbatsov/solarized-emacs -[powerline]: https://github.com/milkypostman/powerline -[font-spec]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Low_002dLevel-Font.html -[diminish]: http://www.emacswiki.org/emacs/DiminishedModes -[auto-complete]: https://github.com/auto-complete -[auto-highlight]: https://github.com/emacsmirror/auto-highlight-symbol -[e-project]: https://github.com/jrockway/eproject -[projectile]: https://github.com/bbatsov/projectile -[sp]: https://github.com/Fuco1/smartparens -[ag]: https://github.com/ggreer/the_silver_searcher -[pt]: https://github.com/monochromegane/the_platinum_searcher -[tcl]: https://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/apps/pt.html -[flycheck]: https://github.com/flycheck -[yasnippet]: https://github.com/capitaomorte/yasnippet -[expand-region]: https://github.com/magnars/expand-region.el -[multiple-cursors]: https://github.com/magnars/multiple-cursors.el -[hswoop]: https://github.com/ShingoFukuyama/helm-swoop -[hcss]: https://github.com/ShingoFukuyama/helm-css-scss -[hyas]: https://github.com/emacs-helm/helm-c-yasnippet -[hthemes]: https://github.com/syohex/emacs-helm-themes -[projectile]: https://github.com/bbatsov/projectile -[hdescbinds]: https://github.com/emacs-helm/helm-descbinds -[iedit]: https://github.com/tsdh/iedit -[evil-iedit-state]: https://github.com/syl20bnr/evil-iedit-state -[evil-indent-textobject]: https://github.com/cofi/evil-indent-textobject -[evil-visualstar]: https://github.com/bling/evil-visualstar -[evil-exchange]: https://github.com/Dewdrops/evil-exchange -[evil-surround]: https://github.com/timcharper/evil-surround -[camelcasemotion.vim]: http://www.vim.org/scripts/script.php?script_id=1905 -[vim-exchange]: https://github.com/tommcdo/vim-exchange -[vim-surround]: https://github.com/tpope/vim-surround -[evil-nerd-commenter]: https://github.com/redguardtoo/evil-nerd-commenter -[nerdcommenter]: https://github.com/scrooloose/nerdcommenter -[evil-matchit]: https://github.com/redguardtoo/evil-matchit -[matchit.vim]: http://www.vim.org/scripts/script.php?script_id=39 -[source code pro]: https://github.com/adobe-fonts/source-code-pro -[evil-escape]: https://github.com/syl20bnr/evil-escape -[evil-args]: https://github.com/wcsmith/evil-args -[evil-jumper]: https://github.com/bling/evil-jumper -[evil-numbers]: https://github.com/cofi/evil-numbers -[evil-lisp-state]: https://github.com/syl20bnr/evil-lisp-state -[Vim's Unite]: https://github.com/Shougo/unite.vim -[git-gutter]: https://github.com/syohex/emacs-git-gutter-fringe -[nose]: https://github.com/nose-devs/nose/ -[nose.el]: https://github.com/syl20bnr/nose.el -[pylookup]: https://github.com/tsgates/pylookup -[jedi]: https://github.com/tkf/emacs-jedi -[ess-R-object-popup]: https://github.com/myuhe/ess-R-object-popup.el -[ess-R-data-view]: https://github.com/myuhe/ess-R-data-view.el -[leuven-theme]: https://github.com/fniessen/emacs-leuven-theme -[monokai-theme]: https://github.com/oneKelvinSmith/monokai-emacs -[zenburn-theme]: https://github.com/bbatsov/zenburn-emacs -[ido-vertical-mode]: https://github.com/gempesaw/ido-vertical-mode.el -[issues]: https://github.com/syl20bnr/spacemacs/issues -[vundle]: https://github.com/gmarik/Vundle.vim -[anzu]: https://github.com/syohex/emacs-anzu -[javascript-contrib]: ../contrib/!lang/javascript -[themes-megapack]: ../contrib/themes-megapack -[git layer]: ../contrib/!tools/git -[python-contrib]: ../contrib/!lang/python -[html-contrib]: ../contrib/lang/html -[guide-key]: https://github.com/kai2nenobu/guide-key -[guide-key-tip]: https://github.com/aki2o/guide-key-tip -[gitter]: https://gitter.im/syl20bnr/spacemacs -[CONTRIBUTE.md]: ./CONTRIBUTE.md -[special buffer howto]: ./HOWTOs.md#change-special-buffer-rules -[neotree]: https://github.com/jaypei/emacs-neotree -[nerdtree]: https://github.com/scrooloose/nerdtree -[anaconda-mode]: https://github.com/proofit404/anaconda-mode -[1st-contrib]: https://github.com/syl20bnr/spacemacs/pull/19 -[1st-clayer]: https://github.com/syl20bnr/spacemacs/commit/e802027d75d0c0aed55539b0da2dfa0df94dfd39 -[1st-article]: http://oli.me.uk/2014/11/06/spacemacs-emacs-vim/ -[1st-cbanner]: https://github.com/syl20bnr/spacemacs/commit/7b44a56263049482ed540ed6815a295633ffe9d1 -[100th-issue]: https://github.com/syl20bnr/spacemacs/pull/100 -[200th-issue]: https://github.com/syl20bnr/spacemacs/issues/200 -[300th-issue]: https://github.com/syl20bnr/spacemacs/pull/300 -[400th-issue]: https://github.com/syl20bnr/spacemacs/pull/400 -[500th-issue]: https://github.com/syl20bnr/spacemacs/pull/500 -[600th-issue]: https://github.com/syl20bnr/spacemacs/pull/600 -[700th-issue]: https://github.com/syl20bnr/spacemacs/pull/700 -[800th-issue]: https://github.com/syl20bnr/spacemacs/pull/800 -[900th-issue]: https://github.com/syl20bnr/spacemacs/pull/900 -[1000th-issue]: https://github.com/syl20bnr/spacemacs/pull/1000 -[100th-PR]: https://github.com/syl20bnr/spacemacs/pull/228 -[200th-PR]: https://github.com/syl20bnr/spacemacs/pull/418 -[300th-PR]: https://github.com/syl20bnr/spacemacs/pull/617 -[400th-PR]: https://github.com/syl20bnr/spacemacs/pull/806 -[500th-PR]: https://github.com/syl20bnr/spacemacs/pull/993 -[600th-PR]: https://github.com/syl20bnr/spacemacs/pull/1205 -[trishume]:https://github.com/trishume -[nashamri]: https://github.com/nashamri -[Wolfy87]:https://github.com/Wolfy87 -[danielwuz]:https://github.com/danielwuz -[CestDiego]:https://github.com/CestDiego -[bjarkevad]:https://github.com/bjarkevad -[jcpetkovich]:https://github.com/jcpetkovich -[tuhdo]:https://github.com/tuhdo -[tuhdo-tuto]:http://tuhdo.github.io/helm-intro.html -[BrianHicks]:https://github.com/BrianHicks -[cpaulik]: https://github.com/cpaulik -[chrisbarrett]:https://github.com/chrisbarrett -[justrajdeep]:https://github.com/justrajdeep -[dbohdan]:https://github.com/dbohdan -[laat]:https://github.com/laat -[ryansroberts]:https://github.com/laat -[kendall]:https://github.com/kendall -[urso]:https://github.com/urso -[luisgerhorst]:https://github.com/luisgerhorst -[rashly]:https://github.com/rashly -[bru]:https://github.com/bru -[smt]:https://github.com/smt -[ralesi]:https://github.com/ralesi -[alcol80]:https://github.com/alcol80 -[adouzzy]:https://github.com/adouzzy -[mlopes]:https://github.com/mlopes -[balajisivaraman]:https://github.com/balajisivaraman -[Jackneill]:https://github.com/Jackneill -[jb55]:https://github.com/jb55 -[use-package]: https://github.com/jwiegley/use-package -[Paradox]: https://github.com/Bruce-Connor/paradox -[fancy-battery]: https://github.com/lunaryorn/fancy-battery.el -[MacType]: https://code.google.com/p/mactype/ -[Emacs as a Server]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html diff --git a/doc/DOCUMENTATION.org b/doc/DOCUMENTATION.org new file mode 100644 index 000000000..de34097e9 --- /dev/null +++ b/doc/DOCUMENTATION.org @@ -0,0 +1,2481 @@ +* Table of Contents :TOC@4: + - [[#spacemacs-documentation][Spacemacs Documentation]] + - [[#core-pillars][Core Pillars]] + - [[#mnemonic][Mnemonic]] + - [[#discoverability][Discoverability]] + - [[#consistency][Consistency]] + - [[#crowd-configured][Crowd-Configured]] + - [[#goals][Goals]] + - [[#screenshots][Screenshots]] + - [[#who-can-benefit-from-this][Who can benefit from this?]] + - [[#update-and-rollback][Update and Rollback]] + - [[#update-spacemacs-repository][Update Spacemacs repository]] + - [[#update-packages][Update packages]] + - [[#configuration-layers][Configuration layers]] + - [[#structure][Structure]] + - [[#extensions-and-packages][Extensions and 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]] + - [[#dotfile-configuration][Dotfile Configuration]] + - [[#installation][Installation]] + - [[#synchronization-of-dotfile-changes][Synchronization of dotfile changes]] + - [[#content][Content]] + - [[#using-configuration-layers][Using configuration layers]] + - [[#setting-configuration-layers-variables][Setting configuration layers variables]] + - [[#excluding-packages][Excluding packages]] + - [[#hooks][Hooks]] + - [[#custom-variables][Custom variables]] + - [[#main-principles][Main principles]] + - [[#evil][Evil]] + - [[#holy][Holy]] + - [[#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]] + - [[#mouse-usage][Mouse usage]] + - [[#mode-line][Mode-line]] + - [[#flycheck-integration][Flycheck integration]] + - [[#anzu-integration][Anzu integration]] + - [[#battery-status-integration][Battery status integration]] + - [[#powerline-separators][Powerline separators]] + - [[#minor-modes][Minor Modes]] + - [[#commands][Commands]] + - [[#vim-key-bindings][Vim key bindings]] + - [[#escaping][Escaping]] + - [[#executing-vim-and-emacs-exm-x-commands][Executing Vim and Emacs ex/M-x commands]] + - [[#leader-key][Leader key]] + - [[#reserved-prefix-command-for-user][Reserved prefix command for user]] + - [[#helm][Helm]] + - [[#c-z-and-tab-switch][C-z and Tab switch]] + - [[#helm-micro-state][Helm micro-state]] + - [[#discovering][Discovering]] + - [[#key-bindings][Key bindings]] + - [[#guide-key][Guide-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]] + - [[#pointcursor][Point/Cursor]] + - [[#smooth-scrolling][Smooth scrolling]] + - [[#vim-motions-with-ace-jump-mode][Vim motions with ace-jump mode]] + - [[#ace-link-mode][ace-link mode]] + - [[#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-manipulation-micro-state][Buffers manipulation manipulation micro-state]] + - [[#special-buffers][Special Buffers]] + - [[#files-manipulations-key-bindings][Files manipulations key bindings]] + - [[#emacs-and-spacemacs-files][Emacs and Spacemacs files]] + - [[#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]] + - [[#bookmarks][Bookmarks]] + - [[#docview-mode][DocView mode]] + - [[#searching][Searching]] + - [[#with-an-external-tool][With an external tool]] + - [[#searching-in-an-arbitrary-directory][Searching in an arbitrary directory]] + - [[#searching-in-a-project][Searching in a project]] + - [[#searching-the-web][Searching the web]] + - [[#persistent-highlighting][Persistent highlighting]] + - [[#stacking-highlights][Stacking highlights]] + - [[#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]] + - [[#smartparens-strict-mode][Smartparens Strict mode]] + - [[#zooming][Zooming]] + - [[#text][Text]] + - [[#frame][Frame]] + - [[#increasedecrease-numbers][Increase/Decrease numbers]] + - [[#spell-checking][Spell checking]] + - [[#region-selection][Region selection]] + - [[#expand-region][Expand-region]] + - [[#indent-text-object][Indent text object]] + - [[#region-narrowing][Region narrowing]] + - [[#line-formatting][Line formatting]] + - [[#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]] + - [[#python][Python]] + - [[#javascript][JavaScript]] + - [[#html-and-css][HTML and CSS]] + - [[#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]] + - [[#i-have-no-file-spacemacs][I have no file ~/.spacemacs]] + - [[#achievements][Achievements]] + - [[#issues][Issues]] + - [[#merged-pull-requests][Merged Pull Requests]] + - [[#stars-forks-and-watchers][Stars, forks and watchers]] + - [[#specials][Specials]] + - [[#thank-you][Thank you]] + +* Spacemacs Documentation + +* Core Pillars + +Four core pillars: Mnemonic, Discoverability, Consistency, "Crowd-Configured". + +If any of these core pillars is violated open an issue and we'll fix it. + +** Mnemonic + +=Spacemacs= organizes key bindings by mnemonic namespaces as much as possible. If +you are looking for commands to operate on your buffer, they are right under ~SPC +b~, if you want to operate on your project, then it is ~SPC p~, etc... + +** Discoverability + +=Spacemacs= comes with a dedicated major mode =spacemacs-mode=. Its goal is to give +useful feedbacks and easily perform maintenance tasks. + +It also comes with dedicated [[https://github.com/emacs-helm/helm][helm]] sources to quickly find layers, packages and +more. + +[[https://github.com/kai2nenobu/guide-key][guide-key]] is enabled by default, it will display all the available key bindings +in a dedicated popup buffer. + +** Consistency + +Similar functionalities should have the same key binding no matter which major +is currently active. For instance if you are looking for the definition of a +function, the binding is ~SPC m g g~, =m= for =major mode= and =g g= for =go to thing at +point=. No matter what is the major mode it is the same binding to perform this +action. + +This is also true for the documentation, each configuration layer comes with an +associated =README.org= file with the same base layout. + +The consistency core pillar is supported by a convention file: [[file:CONVENTIONS.org][CONVENTIONS.org]] + +** Crowd-Configured + +By defining an very light structure called =configuration layer= which is easy to +understand, =Spacemacs= makes it easy to contribute additional support. + +The conventions in [[file:CONVENTIONS.org][CONVENTIONS.org]] make it easy to get the spacemacs way and +keep consistency even if there are a lot of contributions. + +=Crowd-configuration= is the most powerful pillar of =Spacemacs=. Anybody can submit +upstream improvements to configuration layers or a whole new one. Any user can +easily and directly use this layer by adding it to a list in a dotfile. It is +even possible to exclude /any/ unwanted packages. + + +* Goals + +- *Bring the power of modal editing* to the powerful Emacs editing platform. + +- Integrate nicely with =Evil= states (=Vim= modes): =Spacemacs= tries to *keep + your fingers on the home row* as much as possible, no matter the mode you are + in. + +- *Crowd-configured*: Contribute easily your improvements and new configuration + layers. + +- *Minimalistic and nice graphical UI*, keep your available screen space for + what matters: your text files. + +- *Mnemonic and consistent key bindings* which should be easier to learn and + remember and be the same in all major modes. + +- *Fast boot time*, everything is lazy-loaded. + +- *Lower the risk of RSI* by heavily using the space bar instead of modifiers. + +- Hopefully, if it's not already the case: + + Ɛ>Ɛ>Ɛ> *make you love modal editing!* <3<3<3 + +* Screenshots + +/Startup/ [[file:img/spacemacs-startup.png]] + +/Python/ [[file:img/spacemacs-python.png]] + +/Terminal (urxvt)/ [[file:img/spacemacs-urxvt.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= is first intended to be used by *Vim users* who want to go to the +next level by using Emacs. There is a [[./VIMUSERS.org][guide]] for these users to supplement the +documentation. + +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 is no official +studies to prove this). + +Emacs users wanting to learn *a different way to edit files* or wanting to learn +Vim key bindings. + +As a side note, if you are a programmer and you don't know Vim key bindings yet, +I deeply recommend you to learn the basics as recommended in [[http://sachachua.com/blog/2013/05/how-to-learn-emacs-a-hand-drawn-one-pager-for-beginners/][Sacha Chua's +one-page guide]] about how to learn Emacs. + +* Update and Rollback + +For now it is still needed to update the =Spacemacs= repository manually. + +** Update Spacemacs repository + +Close Emacs and update the git repository: + +#+begin_src sh + $ git pull --rebase git submodule sync; git submodule update +#+end_src + +*Note* It is recommended to update the packages first, see next session. + +** Update packages + +To update =Spacemacs= press RET (enter) or click on the link =[Update]= in the +startup page under the banner then restart Emacs. + +If anything goes wrong you should be able to rollback the update by pressing +~RET~ or clicking on the =[Rollback]= link next to the =[Update]= link and +choose a rollback slot (sorted by date). + +* Configuration layers + +** Structure + +Configuration is organized in layers. Each layer has the following structure: + +#+BEGIN_EXAMPLE + [layer_name] + |__ [extensions] + | |__ [mode 1] + | | ... + | |__ [mode n] + |__ config.el + |__ extensions.el + |__ funcs.el + |__ keybindings.el + |__ packages.el + + [] = directory +#+END_EXAMPLE + +Where: + + | File | Usage | + |----------------+----------------------------------------------------------------------| + | config.el | Emacs built-in configuration or mandatory configuration | + | extensions.el | The list of extensions to load and the functions to initialize them | + | 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, and =Extensions= are generally elisp code from git submodules. + +** Extensions and Packages + +*** Within a layer + +**** Declaration + +=Extensions= and =Packages= are declared in variables =-pre-extensions=, +=-post-extensions= and =-packages= where == is the layer +name. =Pre-Extensions= are loaded before =Packages= and =Post-Extensions= are +loaded after =Packages=. + +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 -packages '(package1 package2 ...) +#+end_src + +**** Initialization + +To initialize an extension or a package =xxx=, define a function with this +format in =extensions.el= or =packages.el=: + +#+begin_src emacs-lisp + (defun /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= in 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 +=-excluded-packages=. + +Example: + +#+begin_src emacs-lisp + (setq -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/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 =-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 =contrib= 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 [[./CONTRIBUTE.org][CONTRIBUTE.org]]. + +** Example: Themes Megapack example + +This is a simple =contrib= configuration layer listing a bunch of themes, you +can find it [[../contrib/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=. + +* Dotfile Configuration + +User configuration can be stored in your =~/.spacemacs= file. + +** Installation + +=~/.spacemacs= is an optional file. If you want to use it you have to copy it +manually from the template file =~/.emacs.d/core/templates/.spacemacs.template= + +#+begin_src sh + $ cp ~/.emacs.d/core/templates/.spacemacs.template ~/.spacemacs +#+end_src + +** 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-execute the functions =dotspacemacs/init= and +=dotspacemacs/config=. Depending on the content of this functions you may +encounter some unwanted side effects. For instance if you use a toggle in +=dotspacemac/config= to enable some behavior, this behavior will be turned off +whenever the dotfile is re-synchronize. To avoid these side-effects it is +recommended to use =setq= expressions instead of toggle functions. It is also +possible to /skip/ the execution of =dotspacemacs/config= with the universal +argument (~SPC u 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 [[../contrib][the =contrib= +directory]]. + +Configuration layers are expected to be stored in =~/.emacs.d/private= or +=~/.emacs.d/contrib=. 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 [[../contrib/!tools/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=, this variable can exclude both packages and +extensions (see [[#configuration-layers][Configuration layers]] for more info on packages and extensions). + +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 + +Two 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. + - =dotspacemacs/config= is triggered at the very end of =Spacemacs= loading. + +*** 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 + +** Evil + +=Spacemacs= uses the [[https://gitorious.org/evil/pages/Home][evil]] mode package to emulate Vim key bindings. It is a very +complete emulation, maybe the most advanced. In fact, Evil is much more than +just a Vim emulation. It has more states than Vim for instance. + +** Holy + +Thanks to the new holy-mode Spacemacs can now be used by Vim users or Emacs +users by setting the =dotspacemacs-editing-style= variable to ='vim= or ='emacs= +in the dotfile. In Emacs style the leader is available as ~M-m~. It is possible +to dynamically switch between evil and holy modes using ~SPC P tab~. + +*** States + +=Spacemacs= has 9 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 | +| 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 are also the =operator= and =replace= evil +states. + +** 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~. + +** 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-and-edition-of-symbols][Auto-highlight-symbol micro-state]]: +[[file:img/spacemacs-ahs-micro-state.png]] + +[[#change-font-size][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). + +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/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= + - a [[https://github.com/kai2nenobu/guide-key][guide-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 + +By default, =Spacemacs= uses the theme [[https://github.com/bbatsov/solarized-emacs][solarized-light]]. + +It is possible to define your default themes in your =~/.spacemacs= with the +variable =dotspacemacs-themes=. For instance, to specify =leuven= and =zenburn= +(high contrast theme and low contrast theme): + +#+begin_src emacs-lisp + (setq-default dotspacemacs-themes '(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. | + +*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. + +*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~~ | display =~= in the fringe on empty lines | +| ~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~ | show the absolute line numbers | + + | Key Binding | Description | + |-------------+------------------------------| + | ~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 | + +*Note* These toggles are all available via the =helm-spacemacs= interface (press +~SPC f e h~ to display the =helm-spacemacs= buffer). + +*** 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 | +| 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 f~ | toggle the flycheck info (available in =syntax-checking= layer) | +| ~SPC t m m~ | toggle the minor mode lighters | +| ~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 new version lighter | + +**** Flycheck integration + +When [[https://github.com/flycheck/flycheck][Flycheck]] minor mode is enabled, a new element appears showing the number of +errors, warnings and info. + +#+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/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 glocal. 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 c~ | =none= | | 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 k~ | =Ⓖ= | G | guide-key mode | +| ~SPC t i~ | =ⓘ= | i | indentation guide | +| ~SPC t C-i~ | =ⓘ= | i | global indentation guide | +| ~SPC t I~ | =Ⓘ= | I | aggressive indent 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 | spell checking (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 | + +* 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 evil states to normal state + - escape from evil-lisp-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 + - 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 s~ work again). + +This sequence can be customized in your =~/.spacemacs=. Example to set it to +~jj~ (it is important set the variable in =dotspacemacs/init=): + +#+begin_src emacs-lisp + (defun dotspacemacs/init () + (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=. + +*Important Note* One caveat of =evil-escape= is that you must not use it while +recording macros. Use =escape= key instead. + +*** Executing Vim and Emacs ex/M-x commands + + | Command | Key Binding | + |------------------+-------------| + | Vim (ex-command) | ~:~ | + | Emacs (M-x) | ~SPC :~ | + +The command key ~:~ can be easily changed with the variable +=dotspacemacs-command-key= of your =~/.spacemacs=. Note that is will change both +~:~ and ~SPC :~ bindings to keep the symmetry between Vim and Emacs. A good key +can be ~,~ for example. + +*** 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=. + +** Reserved prefix command for user + +~SPC o~ is reserved for the user. Setting key bindings behind ~SPC o~ is +*guaranteed* to never conflict with =Spacemacs= defaults key bindings. + +*Example:* Put =(evil-leader/set-key "oc" 'org-capture)= inside +=dotspacemacs/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 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 or leave the 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 | +| ~q~ | quit micro-state | +| ~t~ | mark current candidate | +| ~T~ | mark all candidates | +| ~v~ | execute persistent action | + +** Discovering + +*** Key bindings + +**** Guide-key + +An 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/kai2nenobu/guide-key][guide-key]] buffer will be displayed quickly after the key has been +pressed. You can change the delay by setting the variable +=dotspacemacs-guide-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 f~ | describe a function | +| ~SPC h d k~ | describe a key | +| ~SPC h d m~ | describe current modes | +| ~SPC h d p~ | describe a package | +| ~SPC h d t~ | describe a theme | +| ~SPC h d v~ | describe a variable | + +Other help key bindings: + +| Key Binding | Description | +|-------------+-----------------------------------------------| +| ~SPC h i~ | search in info pages with the symbol at point | +| ~SPC h m~ | search available man pages | + +*** Available layers + +All layers can be easily discovered via =helm-spacemacs= accessible with ~SPC f +e h~. + +The following helm actions are available: + - default: open the layer =README.md= + - 2nd: open the layer =packages.el= + - 3nd: open the layer =extensions.el= + +**** Available packages in Spacemacs + +=helm-spacemacs= 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]= link on the =Spacemacs= startup +page instead. + +=Spacemacs= proposes to use [[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 | +|-------------+-------------------------------------------------------| +| ~/~ | 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= 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 quickly up (10 lines at a time) | +| ~L~ | move quickly down (10 lines at a time) | +| ~SPC j h~ | go to the beginning of line (and set a mark at the previous location in the line) | +| ~SPC j l~ | go to the end of line (and set a mark at the previous location in the line) | +| ~SPC z z~ | 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 ace-jump mode + +=Spacemacs= uses the =evil= integration of [[https://github.com/winterTTr/ace-jump-mode][ace-jump mode]] which enables the +invocation of =ace-jump-mode= during motions. + +It is useful for deleting visually a set of lines, try the following sequence in +a buffer containing some text: ~d SPC l~ + +| Key Binding | Description | +|-------------+----------------------------------------------------| +| ~SPC SPC~ | initiate ace jump word mode | +| ~SPC l~ | initiate ace jump line mode | +| ~SPC `~ | go back to the previous location (before the jump) | + +Hint: you may change to char mode by ~C-c C-c~ in word mode. + +**** ace-link mode + +Similar to =ace-jump-mode=, [[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= | + +*** 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 W~ | 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 return 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 (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 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 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 [[./HOWTOs.org#change-special-buffer-rules][special buffer +howto]]. + +**** Files manipulations key bindings + +Files manipulation commands (start with ~f~): + +| Key Binding | Description | +|-------------+----------------------------------------------------------------| +| ~SPC f D~ | delete a file and the associated buffer (ask for confirmation) | +| ~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 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 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 h~ | discover =Spacemacs= documentation, layers and packages using =helm= | +| ~SPC f e i~ | open the all mighty =init.el= | +| ~SPC f e R~ | resync the dotfile with spacemacs | +| ~SPC f e s~ | open =ido= in the =spacemacs= layer folder | +| ~SPC f e v~ | display and copy the spacemacs version | + +*** 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-~ | open a =dired buffer= | +| ~M-~ | 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~. + +**** 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 | +| ~g~ | 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 + +*** Bookmarks + +Bookmarks can be set anywhere in a file. Bookmarks are persistent. They are very +useful to jump to/open a known project. =Spacemacs= used =helm-bookmarks= to +manage them. + +Open an =helm= window with the current bookmarks by pressing: ~SPC h 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 | + +** Searching + +*** With an external tool + +=Spacemacs= can be interfaced with different search utilities: + - ack + - grep + - [[https://github.com/ggreer/the_silver_searcher][ag]] + - [[https://github.com/monochromegane/the_platinum_searcher][pt]] + +*Note* =ag= and =pt= are optimized to be used in a source control repository but +they can be used in an arbitrary directory as well. + +By default Spacemacs will look for the first installed tool in the list =("ag", +"pt", "ack", "grep")=. This list can be changed in the dotfile with the variable +=dotspacemacs-search-tools=. + +*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=. + +**** Searching in an arbitrary directory + +To use these utilities in one or several arbitrary directories: + +| Key Binding | Description | +|-------------+---------------------------------------------------------------------------| +| ~SPC s /~ | execute the first found utility (by default =ag=, =pt=, =ack= and =grep=) | +| ~SPC s a~ | =ag= | +| ~SPC s g~ | =grep= | +| ~SPC s G~ | =grep= defaults to symbol at point | +| ~SPC s k~ | =ack= | +| ~SPC s p~ | =pt= | +| ~SPC s L~ | open stored search buffer (stored with ~F3~ in helm search buffer) | + +*Note* Use the universal argument to change the search list of ~SPC s /~ to +=ack= and =grep= (does not look for =ag= or =pt=). + +*Note* It is also possible to search in several directories at once by marking +them in the helm buffer. + +*Pro Tip* Use ~F3~ in the helm search buffer to save the list of results to a +buffer. + +**** Searching in a project + +To use these utilities in a project using =projectile=: + +| Key Binding | Description | +|-------------+---------------------------------------------------------------------------| +| ~SPC /~ | execute the first found utility (by default =ag=, =pt=, =ack= and =grep=) | +| ~SPC p s a~ | =ag= | +| ~SPC p s A~ | =ag= with symbol at point as default text | +| ~SPC p s g~ | =grep= defaults to current region then symbol at point | +| ~SPC p s k~ | =ack= | +| ~SPC p s K~ | =ack= with symbol at point as default text | +| ~SPC p s p~ | =pt= | +| ~SPC p s P~ | =pt= with symbol at point as default text | + +*Pro Tip* Use ~SPC h l~ to bring back the last helm session. + +**** 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=. + +*** Stacking highlights + +With [[https://github.com/boyw165/hl-anything][hl-anything]] it is possible to +highlight all occurrences of the word under point. The highlights can be +stacked. + +| Key Binding | Description | +|-------------+-----------------------------------------------------------------------------| +| ~SPC h c~ | clear the highlightings | +| ~SPC h g c~ | clear the highlightings globally (all opened buffers) | +| ~SPC h h~ | highlight all occurrence of the word at point | +| ~SPC h g h~ | highlight all occurrence of the word at point globally (all opened buffers) | +| ~SPC h n~ | next highlighted occurrence | +| ~SPC h N~ | previous highlighted occurrence | +| ~SPC h p~ | toggle auto-highlight of the enclosing parenthesis | +| ~SPC h r~ | restore saved highlights in the current buffer | +| ~SPC h s~ | save current highlights | + +*** Highlight current symbol + +=Spacemacs= supports highlighting of the current symbol on demand (provided by +the [[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 b~ | go to the last searched occurrence of the last highlighted symbol | +| ~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 R~ | change range to default (=whole buffer=) | + +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 + [6/11]* press (n/N) to navigate, (e) to edit, (r) to change range or (R) + for reset +#+END_EXAMPLE + +Where = [x/y]*= is: + - M: the current range mode + - ==: whole buffer range + - ==: current display range + - ==: 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-symbols][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 l~ + +*** 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/config= function. + +*** Text manipulation commands + +Text related commands (start with ~x~): + + | Key Binding | Description | + |-------------+---------------------------------------------------------------| + | ~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 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~ | move down a line of text (enter micro-state) | + | ~SPC x K~ | move up a line of text (enter micro-state) | + | ~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 words in the selection region | + | ~SPC x w C~ | count the number of occurrences per word in the select region | + +*** 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 down the font and initiate the font scaling micro-state | +| ~SPC z x =~ | reset the font size (no scaling) and initiate the font scaling micro-state | +| ~+~ | increase the font size | +| ~-~ | decrease the font size | +| ~=~ | 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 | +| ~SPC z f -~ | zoom out the frame content | +| ~SPC z f =~ | reset the frame content size | +| ~+~ | zoom in | +| ~-~ | zoom out | +| ~=~ | 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 commands start with =S=: + + | Key Binding | Description | + |-------------+----------------------------------------| + | ~SPC S c~ | list of corrections in a =helm= buffer | + | ~SPC S d~ | change dictionary language | + | ~SPC S n~ | go to the next spell check error | + +*** 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 | + +*** Line formatting + +=Spacemacs= performs =go to the line below point and indent it= with ~SPC j k~. +You may repeat this operation with =evil-repeat= if you need to indent many +lines. + +Line formatting commands start with ~j~: + + | Key Binding | Description | + |-------------+----------------------------------------------------------| + | ~J~ | join the current line with the next line | + | ~SPC j j~ | same as SPC j k but will split the current line at point | + | ~SPC J~ | split a quoted string or s-expression in place | + | ~SPC j J~ | split a quoted string or s-expression and auto-indent | + | ~SPC j k~ | go to next line and indent it using auto-indent rules | + +Used together these key bindings are very powerful to quickly reformat code. + +*** 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 +edition of the current 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 edition scope by one line below | +| ~K~ | increase the edition 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 i~ | comment invert | + | ~SPC c l~ | comment lines | + | ~SPC c p~ | comment paragraphs | + | ~SPC c r~ | comment region | + | ~SPC c t~ | comment to line | + | ~SPC c y~ | comment and yank | + +*Tips:* To comment efficiently a block of line use the combo ~SPC ; SPC l~ + +*** 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 + +Edition 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 m~. + +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 n~ + - to wrap a symbol in parenthesis then slurping two times: ~SPC k w 2 n~ + +*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~ | forwared 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 /~ | search in project with the best search tool available | + | ~SPC p !~ | run shell command in root | + | ~SPC p &~ | run async shell command in root | + | ~SPC p s a~ | run =ag= | + | ~SPC p s k~ | run =ack= | + | ~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 s g~ | run =grep= | + | ~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~ | regenerate the project's =etags=/=gtags= | + | ~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 | + +** 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 e c~ | clear all errors | + | ~SPC e f~ | toggle flycheck | + | ~SPC e l~ | display the =flycheck= list of errors/warnings | + | ~SPC e n~ | go to the next error | + | ~SPC e p~ | go to the previous error | + +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 r~ | recompile | + +** 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 "") +#+end_src + +*** Helm + +=Spacemacs= add =hjkl= navigation to =helm= buffers: + + | Key Binding | Description | + |-------------+---------------------| + | ~C-h~ | go to previous page | + | ~C-j~ | go to previous item | + | ~C-k~ | go to next item | + | ~C-l~ | go to next page | + +*** Python + +Writing python code with spacemacs is supported by python contribution. Please +see [[../contrib/!lang/python][python contribution]] documentation for detail. + +*** JavaScript + +More featured JavaScript support is provided by the javascript contribution. +Please see [[../contrib/!lang/javascript][javascript contribution]] documentation for detail. + +*** HTML and CSS + +HTML contribution provides support for editing HTML, CSS, Scss and Less files. +Please see [[../contrib/!lang/html][html contribution]] documentation for detail. + +** 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, use +=export EDITOR="emacsclient -c"= in your shell configuration. + +Note that if you're on OS X, you may have to refer to the emacsclient that comes +with your GUI Emacs, e.g. =export +EDITOR="/Applications/Emacs.app/Contents/MacOS/bin/emacsclient -c"=. + +Tip: Remember to use ~:wq~ or ~C-x #~ after you are done editing the file in +Emacs. + +See [[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 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. + +*** I have no file ~/.spacemacs + +You have to manually copy the =~/.emacs.d/core/templates/.spacemacs.template= +file to =~/.spacemacs= + +* 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]] | + +** 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]] | + +** 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]] | + +** Specials + +| 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]] | +| The Gunner (made 18 PRs in a row) | [[https://github.com/ralesi][ralesi]] | +| The Saint (unlocked the holy-mode) | [[https://github.com/trishume][trishume]] | +| The Artist (made the spacemacs logo) | [[https://github.com/nashamri][nashamri]] | +| The Meme Master (made the doge banner) | [[https://github.com/chrisbarrett][chrisbarrett]] | +| The Helm captain (see [[http://tuhdo.github.io/helm-intro.html][here]]) | [[https://github.com/tuhdo][tuhdo]] | + +* 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! diff --git a/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el b/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el index 0480548fb..0575984c8 100644 --- a/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el +++ b/spacemacs/extensions/helm-spacemacs/helm-spacemacs.el @@ -94,20 +94,20 @@ (when (or (equal file-extension "md") (equal file-extension "org")) (push (f-relative file-path spacemacs-docs-directory) result))) - ;; delete DOCUMENTATION.md to make it the first guide - (delete "DOCUMENTATION.md" result) - (push "DOCUMENTATION.md" result) + ;; delete DOCUMENTATION.org to make it the first guide + (delete "DOCUMENTATION.org" result) + (push "DOCUMENTATION.org" result) ;; give each document an appropriate title (mapcar (lambda (r) (cond - ((string-equal r "CONTRIBUTE.md") + ((string-equal r "CONTRIBUTE.org") `("How to contribute to Spacemacs" . ,r)) - ((string-equal r "CONVENTIONS.md") + ((string-equal r "CONVENTIONS.org") `("Spacemacs conventions" . ,r)) - ((string-equal r "DOCUMENTATION.md") + ((string-equal r "DOCUMENTATION.org") `("Spacemacs starter guide" . ,r)) - ((string-equal r "HOWTOs.md") + ((string-equal r "HOWTOs.org") `("Quick HOW-TOs for Spacemacs" . ,r)) ((string-equal r "VIMUSERS.org") `("Vim users migration guide" . ,r))