# Spacemacs Starter Kit [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/syl20bnr/spacemacs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ![title](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/title.png) **Quick Install:** git clone --recursive http://github.com/syl20bnr/spacemacs .emacs.d **Table of Contents** - [Spacemacs Starter Kit](#spacemacs-starter-kit) - [Goals](#goals) - [Screenshots](#screenshots) - [Who can benefit from this ?](#who-can-benefit-from-this-) - [Prerequisites](#prerequisites) - [Install](#install) - [Configuration layers](#configuration-layers) - [Structure](#structure) - [Extensions and Packages initialization](#extensions-and-packages-initialization) - [Contributions](#contributions) - [Themes Megapack example](#themes-megapack-example) - [Main principles](#main-principles) - [Evil](#evil) - [States](#states) - [Base States](#base-states) - [Evil leader](#evil-leader) - [Micro-states](#micro-states) - [Tips](#tips) - [Tips for beginners](#tips-for-beginners) - [Tips for advanced users](#tips-for-advanced-users) - [UI tweaks](#ui-tweaks) - [Commands](#commands) - [Return to normal mode](#return-to-normal-mode) - [Executing Vim and Emacs commands](#executing-vim-and-emacs-commands) - [Key bindings help](#key-bindings-help) - [Included Evil plugins](#included-evil-plugins) - [About helm](#about-helm) - [Navigation](#navigation) - [Point/Cursor](#pointcursor) - [Vim motions with ace-jump mode](#vim-motions-with-ace-jump-mode) - [Buffers and Files](#buffers-and-files) - [Bookmarks](#bookmarks) - [Window manipulation](#window-manipulation) - [Golden ratio](#golden-ratio) - [Text manipulation commands](#text-manipulation-commands) - [Change font size](#change-font-size) - [Spell checking](#spell-checking) - [Region selection](#region-selection) - [Region narrowing](#region-narrowing) - [Auto highlight and edition of symbols](#auto-highlight-and-edition-of-symbols) - [Color theme](#color-theme) - [UI elements](#ui-elements) - [Mode-line](#mode-line) - [Toggles](#toggles) - [Minor Modes](#minor-modes) - [Line formatting](#line-formatting) - [Errors handling](#errors-handling) - [Project management](#project-management) - [Working with Git](#working-with-git) - [Magit](#magit) - [Quick guide for recurring use cases in Magit](#quick-guide-for-recurring-use-cases-in-magit) - [Git gutter bitmaps](#git-gutter-bitmaps) - [Modes](#modes) - [Helm](#helm) - [Erlang](#erlang) - [Ledger](#ledger) - [Lisp](#lisp) - [Org](#org) - [Perforce](#perforce) - [Python](#python) - [Inferior REPL process](#inferior-repl-process) - [Testing in Python](#testing-in-python) - [Other Python commands](#other-python-commands) - [R (ESS)](#r-ess) - [Inferior REPL process](#inferior-repl-process) - [Other R commands](#other-r-commands) - [rcirc](#rcirc) - [TODO list](#todo-list) - [Thank you](#thank-you) ## Goals - The main goal of `Spacemacs` is to **bring the power of Vim modal editing to the powerful Emacs editing platform**. - Slick integration with `Evil` states (`Vim` modes) with custom `micro-states` (temporary overlay map): `Spacemacs` tries to **keep your fingers on the home row** as much as possible, no matter the mode you are in. - **Community driven configuration** based on a configuration layer system *(work in progress)*. Contribute your own personal layer upstream and everybody can use it. - **Minimalistic and nice custom 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. - **Fast boot time**, some time has been invested to make 'Spacemacs' quick to load. - **Lower the risk of RSI** by using the space key as much as possible. - Hopefully, if it's not already the case: Ɛ> **make you love modal editing!** <3 ## Screenshots ![spacemacs_startup](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/spacemacs-startup.png) ![spacemacs_python](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/spacemacs-python.png) *Note: Even though screenshots are updated frequently, `Spacemacs` is evolving quickly and the screenshots may not reflect exactly the current state of the project.* ## Who can benefit from this ? `Spacemacs` is first intended to be used by **Vim users** who want to go to the next level by using Emacs. It is also a good fit for people wanting to **lower the [risk of RSI][RSI]** induced by the default Emacs key bindings. People wanting to learn **a different way to edit files** or wanting to learn Vim key bindings (see [Tips for beginners](#tips-for-beginners)). As a note side, 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. ## Prerequisites `Spacemacs` is compatible with Emacs 24.3 and above and should boot on all the major OSes where this version can be installed. Some packages require external tools to work, a list of all dependencies will be provided in this read me. _Stay tuned._ ## Install Backup your current `.emacs.d`, clone the repo _with the submodules_ and you are good to go: cd ~ mv .emacs.d .emacs.bak git clone --recursive http://github.com/syl20bnr/spacemacs .emacs.d ## Configuration layers _This part of Spacemacs is still in beta, the structure can change over time. Refer to commit messages for more information in case of big changes._ ### 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 elisp code from git submodules, they can also be directly stored in this git repository (maybe we call this: site elisp code ??). ### Extensions and Packages initialization `Extensions` and `Packages` are listed 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 `after-eval-load` black magic. 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 ) ``` ## Contributions `Spacemacs` leverages the configuration layers in order to make it possible for you to share your own layer with other `Spacemacs` users. To use a contribution layer, add it to the `dotspacemacs-configuration-layers` variable of your `~/.spacemacs` For instance to add the configuration layer of [RMS](#thank-you) just do: ```elisp (defvar dotspacemacs-configuration-layers '(rms) "List of contribution to load." ) ``` Oh, you don't find this configuration layer ? So sad, well you can try mine: [syl20bnr](https://github.com/syl20bnr/spacemacs/tree/master/contrib/syl20bnr) All pull requests are welcome for all parts of `Spacemacs`. ### Themes Megapack example This is a simple contribution layer listing a bunch of themes. To install it, just add `themes-megapack` to your `~/.spacemacs`. You have now installed around 100 themes you are free to try with ` h t` (helm-themes). ## 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. #### States `Spacemacs` has 6 states: - **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** (red) - exclusive to `Evil`, using this state is like using a regular Emacs without Vim - **Lisp** (pink) - exclusive to `Spacemacs`, used to navigate Lisp code and modify it #### Base States _(I apologize in advance for the number of repetition of the word `state` in this section, but I encourage you to read again this section until you correctly grasp the concept of `base state` since it is an important concept in `Spacemacs`)_ `Spacemacs` has a notion of `base state`. A `base state` is the state you are when leaving the `insert state`. The typical `base state` in Vim is the `normal state` and it is the only one. `Spacemacs` has more than one base state, here is the list: - normal - lisp This allows a coder of Lisp to completely replace the `normal state` by the `lisp state`. Indeed, once you fire up the `lisp state` you can just go back and forth between the `insert state` and the `lisp state`. Of course there is a rule to break this in order to be able to go back to the `normal state`. It is pretty simple: *When in a `base state`, `ESC` or `fd` will always set you back to the `normal state`.* So to go back to the `normal state` while in `lisp state` just hit `ESC` or `fd`. ### 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, this is why 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: ` f s` - Save all opened buffers: ` f S` - Open (switch) to a buffer with `helm`: ` b s` ### Micro-states `Spacemacs` defines a wide variety of `micro-states` (temporary overlay maps) where it makes sense. This prevent from 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](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/spacemacs-ahs-micro-state.png) [Text scale micro-state](#change-font-size): ![spacemacs_scale_micro_state](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/spacemacs-scale-micro-state.png) ## Tips ### Tips for beginners 1) If you came here with a pure Emacs background, here is a useful tips to get you started. As you may have notice, raw Emacs behavior is indeed available in Evil via the `Emacs state`! To start you could setup the `Emacs state` as the default one, pressing `fd` quickly would bring you to `Normal state` and pressing `ESC` from there would bring you back in `Emacs state`. This way you should never feel lost. To do so add the following snippet to your `~/.spacemacs`: ```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 evil-default-state 'emacs) (define-key evil-normal-state-map [escape] 'evil-emacs-state)) ``` ### Tips for advanced users 1) To Make `lisp state` the default state in `Emacs Lisp` buffers, insert in your `~/.spacemacs` the following snippet: ```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." (add-hook 'emacs-lisp-mode-hook 'evil-lisp-state)) ``` ## UI tweaks `Spacemacs` has a minimalistic and distraction free UI with a lot of subtle customizations which make it unique compared to other Emacs kits: - custom [powerline][powerline] mode-line [with color feedback](#mode-line) 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](#git-gutter-bitmaps) for [git gutter][git-gutter]. - dedicated startup page with a mode aimed at easily managing `Spacemacs` ## Commands Every sequences must be performed in `normal` mode. ### Return to normal mode `ESC` is the default key to return to normal mode. This is one of the main design flaw in Vim key bindings because the `ESC` key is very far from the home row. The popular way to avoid this is to replace `ESC` by `jj` pressed rapidly. Unfortunately it is pretty difficult in Emacs to keep a consistent behavior with this sequence (same thing with `jk` or `kj`). `Spacemacs` uses the sequence `fd` instead of `jj` which works in any Evil state and in any buffer and in the minibuffer. This sequence can be customized in your `~/.spacemacs`, for instance to revert back to the popular configuration using `jj` (not recommended) add this to your file: ```elisp (defun dotspacemacs/init () "User initialization for Spacemacs. This function is called at the very startup." (defvar spacemacs-normal-state-sequence '(?j . ?j)) (defvar spacemacs-normal-state-sequence-delay 0.2) ) ``` ### Executing Vim and Emacs commands Vim commands are executed as usual with the `:` key. To execute an Emacs command press `` (space) before: : ### Key bindings help A list of all the key bindings can be accessed by pressing: ? To narrow the list to `Spacemacs` specific key bindings set the pattern to `SPC` ### Included Evil plugins `Spacemacs` ships with the following evil plugins: Mode | Description ----------------------------------------|-------------------------------------- [evil-leader][evil-leader] | vim leader that bring a new layer of keys in normal mode [evil-little-word][evil-plugin01] | port of [camelcasemotion.vim][vim-plugin01] [evil-operator-comment][evil-plugin01] | comment/uncomment with `CC` [evil-visualstar][evil-plugin03] | search for current selection with `*` [evil-exchange][evil-plugin05] | port of [vim-exchange][vim-plugin04] [evil-surround][evil-plugin04] | port of [surround.vim][vim-plugin03] ### About helm `Spacemacs` tries to use [helm][helm] as much as possible. [helm][helm] is coupled to [popwin][popwin] so `helm` window always appears in a new temporary window at the bottom. The following `helm` modes are installed with `Spacemacs`: Key Binding | Mode | Description ------------|-----------------------------------------|------------------------ ` h s` | [helm-swoop][hswoop] | search for occurrences within a file and edit the result ` h y` | [helm-c-yasnippet][hyas] | select snippets ` h t` | [helm-themes][hthemes] | select a theme ` p f` | [helm-projectile][projectile] | select files within a projectile project ` ?` | [helm-descbinds][hdescbinds] | show key bindings ` s c` | [cofi/helm-flyspell-correct][hflyspell] | choose a corrected word ### Navigation #### 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) ` j h` | go to the beginning of line (and set a mark at the previous location in the line) ` j l` | go to the end of line (and set a mark at the previous location in the line) ` z z` | lock the cursor at the center of the screen #### 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 --------------|------------------------------------------------------------------ ` ` | initiate ace jump char mode ` l` | initiate ace jump line mode `` ``` | go back to the previous location (before the jump) #### Buffers and Files `Spacemacs` uses `ido` for opening files since `ido` way to navigate the file system is better than `helm` in my opinion (especially because `ido` can remember the last selected directories and buffers, maybe helm can do this ?). `ido` is also used to kill buffers. Buffer manipulation commands (start with `b`): Key Binding | Description --------------|---------------------------------------------------------------- ` b d` | delete the current buffer (beware the associated file is also deleted) ` b k` | kill the current buffer ` b K` | kill all buffers except the current one ` b m h` | move a buffer to the left ` b m j` | move a buffer to the bottom ` b m k` | move a buffer to the top ` b m l` | move a buffer to the right ` b n` | switch to next buffer ` b p` | switch to previous buffer ` b r` | rename the current buffer ` b s` | switch to a buffer using `helm` ` b w` | toggle read-only Files manipulation commands (start with `f`): Key Binding | Description --------------|---------------------------------------------------------------- ` f f` | open a file using `ido` ` f i` | open your `init.el` file ` f s` | save a file ` f S` | save all files ` f t` | toggle file tree side bar using [neotree][neotree] ` f y` | show current file absolute path in the minibuffer #### 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`. ### Window manipulation Every window has a number displayed at the start of the mode-line and can be quickly accessed using ` number`. Key Binding | Description --------------|---------------------------------------------------------------- ` 1` | go to first window ` 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 ` 0` | go to window number 10 Windows manipulation commands (start with `w`): Key Binding | Description --------------|---------------------------------------------------------------- ` w b` | split a window horizontally ` w c` | close a window ` w d` | toggle window dedication (dedicated window cannot be used by a mode) ` w H` | move window to the left ` w J` | move window to the bottom ` w K` | move window to the top ` w L` | move window to the right ` w m` | maximize/minimize a window ` w M` | maximize/minimize a window, when maximized the buffer is centered ` w p` | close the current sticky popup window ` w r` | rotate windows clockwise ` w R` | rotate windows counter-clockwise ` w u` | undo window layout (used to effectively undo a close window) ` w U` | redo window layout ` w v` | split a window vertically ` w w` | cycle and focus between windows #### Golden ratio Split windows can be dynamically resized depending on whether they are selected or not. Resizing is performed by the [golden-ratio][golden-ratio] mode. By default `golden-ratio` if off. The mode can be toggled on and off with: t g ### Text manipulation commands Text related commands (start with `x`): Key Binding | Description ------------------|------------------------------------------------------------ ` x u` | set the selected text to lower case ` x U` | set the selected text to upper case ` x d w` | delete trailing whitespaces ` x g l` | set languages used by translate commands ` x g t` | translate current word using Google Translate ` x g T` | reverse source and target languages ` x m j` | move down a line of text ` x m k` | move up a line of text ` x t c` | swap (transpose) the current character with the previous one ` x t w` | swap (transpose) the current word with the previous one ` x t l` | swap (transpose) the current line with the previous one ` x w c` | count the number of words in the selection region ` x w C` | count the number of occurrences per word in the select region ### Change font size The font size of the current buffer can be adjusted with the commands: Key Binding | Description --------------|------------------------------------------------------------ ` x +` | scale up the font and initiate the font scaling micro-state ` x -` | scale down the font and initiate the font scaling micro-state ` 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 ### Spell checking Spell checking commands start with `s`: Key Binding | Description ------------------|------------------------------------------------------------ ` s c` | list of corrections in a `helm` buffer ` s d` | change dictionary language ` s n` | go to the next spell check error ### Region selection Vi `Visual` modes are all supported by `evil`, `Spacemacs` adds another `Visual` mode via the [expand-region][expand-region] mode. Key Binding | Description --------------|---------------------------------------------------------------- ` 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 ### Region narrowing The displayed text of a buffer can be narrowed with the commands (start with `n`): Key Binding | Description --------------|---------------------------------------------------------------- ` n f` | narrow the buffer to the current function ` n p` | narrow the buffer to the visible page ` n r` | narrow the buffer to the selected text ` n w` | widen, i.e show the whole buffer again ### Auto highlight and edition of symbols `Spacemacs` supports auto highlighting of the current word (provided by the [auto-highlight-symbol][auto-highlight] mode) and add a micro-state to it which makes it a very handy tool to have on your tool belt. Key Binding | Description --------------|---------------------------------------------------------------- ` h e` | edit all occurrences of the current word ` t h` | toggle the auto highlighting Navigation between the highlighted symbols can be done with the commands: Key Binding | Description --------------|------------------------------------------------------------ ` h h` | initiate navigation micro-state ` h n` | go to next occurrence and initiate navigation micro-state ` h N` | go to previous occurrence and initiate navigation micro-state ` h c b` | change range to `whole buffer` ` h c d` | change range to `display area` ` h c f` | change range to `function` ` h C` | change range to default (`whole buffer`) In 'Spacemacs' highlight symbol micro-state: Key Binding | Description --------------|------------------------------------------------------------ `c` | change scope (`function`, `display area`, `whole buffer`) `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 `h` | go to home occurrence (go to starting occurrence) Any other key | leave the navigation micro-state The micro-state text in minibuffer display the following information: [6/11]* press (n) or (N) to navigate, (h) for home symbol, (c) to change scope 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 - * (star): appears if there is at least one occurrence which is not currently visible ### Color theme By default, `Spacemacs` uses the theme [Solarized][solarized-theme]. Key Binding | Description ------------------|------------------------------------------------------------ ` c t` | cycle between `Spacemacs` themes ` h t` | select a theme using a `helm` buffer `Spacemacs` available themes: - [Solarized][solarized-theme] - [Monokai][monokai-theme] - [Zenburn][zenburn-theme] ### UI elements #### Mode-line The mode line is a [powerline][powerline] customized to show the window number and the colorized Evil current state. The color codes for modes are: Evil State | Color ------------------|------------------ Normal | Orange Insert | Green Visual | Grey Emacs | Red Motion | Purple When [Flycheck][flycheck] minor mode is enabled, the mode line color changes according to the current flycheck state: ![flycheck-error](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/flycheck-error.png) ![flycheck-warning](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/flycheck-warning.png) ![flycheck-info](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/flycheck-info.png) #### Toggles Some UI indicators can be toggled on and off (toggles start with `t`): Key Binding | Description ------------------|------------------------------------------------------------ ` t 8` | display a mark on the 80th column ` t F` | toggle display of the fringe ` t n` | show the absolute line numbers ### 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 Lighter | Mode -------------|----------------------------------------------------------------- ⊞ | [golden-ratio][golden-ratio] mode Ⓐ | [auto-complete][auto-complete] mode Ⓗ | [auto-highlight-symbol][auto-highlight] mode Ⓒ | [centered-cursor][centered-cursor] mode eⓅ | [e-project][e-project] mode Ⓟ | [projectile][projectile] mode Ⓕ | flymake mode Ⓢ | flyspell mode (Ⓢ) | [smartparens][sp] mode (Ⓟ) | paredit mode Ⓨ | [yasnippet][yasnippet] mode **Note:** in terminal the regular indicators are used instead of the utf-8 ones. ### Line formatting `Spacemacs` replaces the default `J` Vi key binding (join current line with next line) by a slightly more frequent action which is to `go to the line below point and indent it`. Join lines can still be performed with ` j k` Line formatting commands start with `j`: Key Binding | Description ------------------|------------------------------------------------------------ `J` | go to next line and indent it using auto-indent rules ` j j` | same as `J` but will split the current line at point ` J` | split a quoted string or s-expression in place ` j J` | split a quoted string or s-expression and auto-indent ` j k` | join the current line with the next line Used together these key bindings are very powerful to quickly reformat the code. ### 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 `f` for `flycheck`): Key Binding | Description ------------------|------------------------------------------------------------ ` f c` | clear all errors ` f l` | display the `flycheck` list of errors/warnings ` f n` | go to the next `flycheck` error ` f p` | go to the previous flycheck error Custom fringe bitmaps: Symbol | Description :----------------------------------------------------------------------------------------------:|------------ ![dot-error](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/dot-error.png) | Error ![dot-warning](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/dot-warning.png) | warning ![dot-info](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/dot-info.png) | Info ### Project management Projects in `Spacemacs` are managed with [projectile][projectile]. So 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. Projects management commands (start with `p`): Key Binding | Description ------------------|------------------------------------------------------------ ` p C` | invalidate the cache of `projectile` ` p d` | open a `dired` buffer at the root of the project ` p f` | open a file of the project using `helm` ` p F` | find a file if the project using `ido` ` p k` | kill all the buffers of the project ` p g` | grep search in the project ` p r` | replace a string in the files of the project ` p s` | switch to a buffer of the project ### Working with Git Git commands (start with `g`): Key Binding | Description ------------------|------------------------------------------------------------ ` g c c` | highlight regions by age of commits ` g c C` | clear highlights ` g c t` | highlight regions by last updated time ` g s` | open a `magit` status window ` g m` | display the last commit message of the current line ` g t` | launch the git time machine - Highlight by age of commit or last update time is provided by [smeargle][smeargle]. - Git time machine is provided by [git-timemachine][git-timemachine]. - Git last commit message per line is provided by [git-messenger][git-messenger] #### Magit `Spacemacs` uses [magit][magit] to manage Git repositories. To open a `status buffer`, type in a buffer of a Git repository: g s The buffer is opened in `Emacs state` but you can sill navigate up and down with `k` and `j` respectively (should be like this in all `magit` buffers). Here are the often used bindings inside a `status buffer`: Key Binding | Description ------------------|------------------------------------------------------------ `$` | open `command output buffer` `c c` | open a `commit message buffer` `b b` | checkout a branch `b c` | create a branch `b v` | open the `branch manager buffer` `f f` | fetch changes `F -r F` | pull and rebase `j` | go down `k` | go up `K` | discard changes `l l` | open `log buffer` `P P` | push `q` | quit `s` | on a file or hunk in a diff: stage the file or hunk `+` | on a hunk: increase hunk size `-` | on a hunk: decrease hunk size `S` | stage all `TAB` | on a file: expand/collapse diff `u` | on a staged file: unstage `U` | unstage all staged files `z z` | stash changes In a commit message buffer press `C-c C-c` to commit the changes with the entered message. `C-c C-k` will discard the commit message. **Note:** Sometimes you will be asked about reverting the commit buffer, you can answer `y` with no issue. #### Quick guide for recurring use cases in Magit - Amend a commit: - `l l` to open `log buffer` - `c a` on the commit you want to amend - `C-c C-c` to submit the changes - Squash last commit: - `l l` to open `log buffer` - `E` on the second to last commit, it opens the `rebase buffer` - `j` to put point on last commit - `i` to pass in `insert state` - `s` to squash it - `C-c C-c` to continue to the `commit message buffer` - `C-c C-c` again when you have finished to edit the commit message - Force push a squashed commit: - in the `status buffer` you should see the new commit unpushed and the old commit unpulled - `P -f P` for force a push (**beware** usually it is not recommended to rewrite the history of a public repository, but if you are *sure* that you are the only one to work on a repository it is ok - i.e. in your fork). - Add upstream remote (the parent repository you have forked): - `b v` to open the `branch manager buffer` - `a` to add a remote, type the name (i.e. `upstream`) and the URL - Pull changes from upstream (the parent repository you have forked) and push: - `F -r C-u F` and choose `upstream` or the name you gave to it - `P P` to push the commit to `origin` #### Git gutter bitmaps `Spacemacs` has custom fringe bitmaps for [git-gutter-fringe][git-gutter]: Symbol | Description :-------------------------------------------------------------------------------------------:|----------------- ![git-new](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/git-new-line.png) | new line ![git-del](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/git-del-line.png) | at least one line has been deleted ![git-mod](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/doc/git-mod-line.png) | modified line ### Modes `Spacemacs` tries to add more natural Vi key bindings to some modes or simply add new leader key bindings. Leader key bindings start with `m` because they are bindings related to the current `major mode`. #### 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 #### Erlang `Spacemacs` uses [EDTS][edts] as an Erlang coding environment. Key Binding | Description ------------------|------------------------------------------------------------ ` m d` | show man page documentation ` m e` | go to next issue ` m g` | go to definition ` m G` | find a module in the current project ` m h` | open the header file under point ` m l` | find a function in the current module ` m m` | go to the macro definition under point ` m r` | go to the record definition under point #### Ledger Key Binding | Description ------------------|------------------------------------------------------------ ` m a` | add a transaction ` m d` | delete current transaction #### Lisp Lisp navigation and edition is performed with a custom evil `lisp state`. While in `lisp state` (assume that `evil-lisp-state-backward-prefix` is set to default `n`): Key Binding | Function --------------|------------------------------------------------------------ `(` | switch to `insert state` and insert "(" `$` | sp-end-of-sexp `0` | sp-beginning-of-sexp `a` | sp-absorb-sexp `b` | sp-forward-barf-sexp `nb` | sp-backward-barf-sexp `c` | sp-convolute-sexp `C` | sp-comment `dd` | sp-kill-hybrid-sexp `dx` | sp-kill-sexp `ndx` | sp-backward-kill-sexp `ds` | sp-kill-symbol `nds` | sp-backward-kill-symbol `dw` | sp-kill-word `ndw` | sp-backward-kill-word `D` | evil-delete-line `e$` | evil-lisp-state-eval-sexp-end-of-line `ef` | eval-defun `el` | eval-last-sexp `es` | eval-sexp `gs` | go to source of symbol under point `h` | sp-backward-symbol `H` | sp-backward-sexp `i` | evil-insert-state `j` | sp-down-sexp `J` | sp-backward-down-sexp `k` | sp-up-sexp `K` | sp-backward-up-sexp `l` | sp-forward-symbol `L` | sp-forward-sexp `m` | sp-join-sexp (think about `merge-sexp`) `o` | sp-newline and switch to `insert state` `O` | evil-open-above `p` | evil-past-after `P` | evil-past-before `r` | sp-raise-sexp `R` | sp-rewrap-sexp `C-r` | undo-tree-redo `s` | sp-forward-slurp-sexp `ns` | sp-backward-slurp-sexp `S` | sp-splice-sexp-killing-forward `nS` | sp-splice-sexp-killing-backward `t` | sp-transpose-sexp `T` | sp-transpose-hybrid-sexp `u` | undo-tree-undo `U` | sp-unwrap-sexp `nU` | sp-backward-unwrap-sexp `v` | er/expand-region `V` | select whole line and switch to `visual state` `x` | sp-delete-char `X` | sp-backward-delete-char `y` | sp-copy-sexp `ny` | sp-backward-copy-sexp `RET` | sp-newline (stay in `lisp state` see `o` to switch to `insert state`) `ESC` | evil-normal-state **Important Note:** Pressing `fd` while in `insert state` will return to previous evil state. This is handy to keep going back and forth between `lisp state` and `insert state`. #### Org In `org`, [evil-org-mode][evil-org-mode] is activated. Key Binding | Description ------------------|------------------------------------------------------------ `gh` | outline-up-heading `gj` | org-forward-heading-same-level `gk` | org-backward-heading-same-level `gl` | outline-next-visible-heading `t` | org-todo `T` | org-insert-todo-heading nil `H` | org-beginning-of-line `L` | org-end-of-line `;t` | org-show-todo-tree `o` | always-insert-item `O` | org-insert-heading `$` | org-end-of-line `^` | org-beginning-of-line `<` | org-metaleft `>` | org-metaright `;a` | org-agenda` #### Perforce Key Binding | Description ------------------|------------------------------------------------------------ ` p 4 a` | add a file in depot ` p 4 d` | delete a file in depot ` p 4 D` | p4-describe ` p 4 e` | checkout a file ` p 4 r` | rename a file ` p 4 R` | revert a file ` p 4 S` | submit CL #### Python ##### Inferior REPL process Start an iPython inferior REPL process with ` m i`. Send code to inferior process commands: Key Binding | Description ------------------|------------------------------------------------------------ ` m b` | send buffer and keep code buffer focused ` m B` | send buffer and switch to REPL in insert mode ` m f` | send function and keep code buffer focused ` m F` | send function and switch to REPL in insert mode ` m r` | send region and keep code buffer focused ` m R` | send region and switch to REPL in insert mode `CTRL+j` | next item in REPL history `CTRL+k` | previous item in REPL history ##### Testing in Python `Spacemacs` uses [nose][nose] as a test runner. An improved version of [nose.el][nose.el] is shipped with `Spacemacs`, this version adds: - windows support - test suite support The root of the project is detected with a `.git` directory or a `setup.cfg` file. Test commands (start with `m t` or `m T`): No Debug | Description ------------------|------------------------------------------------------------ m t a | launch all tests of the project m t f | launch the current test under point m t m | launch all tests of the current module m t s | launch all tests of the current suite Debug | Description ------------------|------------------------------------------------------------ m T a | launch all tests of the project in debug mode m T f | launch the current test under point in debug mode m T m | launch all tests of the current module in debug mode m T s | launch all tests of the current suite in debug mode ##### Other Python commands Key Binding | Description ------------------|------------------------------------------------------------ ` m d` | open documentation in `firefox` using [pylookup][pylookup] ` m g` | go to definition using [emacs-jedi][jedi] ` m p` | add a breakpoint #### R (ESS) **Important**: In order to speed up the boot time of `Spacemacs`, `ESS` must be loaded manually via the key binding: e s s ##### Inferior REPL process Start an `R` inferior REPL process with ` m i`. Send code to inferior process commands: Key Binding | Description ------------------|------------------------------------------------------------ ` m b` | send buffer and keep code buffer focused ` m B` | send buffer and switch to REPL in insert mode ` m f` | send function and keep code buffer focused ` m F` | send function and switch to REPL in insert mode ` m l` | send line and keep code buffer focused ` m L` | send line and switch to REPL in insert mode ` m r` | send region and keep code buffer focused ` m R` | send region and switch to REPL in insert mode ` m s` | send region or line and step (debug) ` m S` | send function or paragraph and step (debug) `CTRL+j` | next item in REPL history `CTRL+k` | previous item in REPL history ##### Other R commands Key Binding | Description ------------------|------------------------------------------------------------ ` m p` | object introspection popup [ess-R-object-popup][ess-R-object-popup] ` m v p` | view data under point using [ess-R-data-view][ess-R-data-view] ` m v t` | view table using [ess-R-data-view][ess-R-data-view] #### rcirc Key Binding | Description ------------------|------------------------------------------------------------ `CTRL+j` | next item in command history `CTRL+k` | previous item in command history ## TODO list - Add support for [multiple-cursors][multiple-cursors] mode. ## Thank you [Jokes aside](#contributions), thank you Richard for this great piece of software. Thank you to the whole Emacs community from core developers to elisp hackers! [evil]: https://gitorious.org/evil/pages/Home [evil-leader]: https://github.com/cofi/evil-leader [RSI]: http://en.wikipedia.org/wiki/Repetitive_strain_injury [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 [helm]: https://github.com/emacs-helm/helm [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 [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 [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 [keybindings]: https://github.com/syl20bnr/vimacs/blob/master/my-keybindings.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 [hflyspell]: https://gist.github.com/cofi/3013327 [evil-plugin01]: https://github.com/tarao/evil-plugins [evil-plugin02]: https://github.com/redguardtoo/evil-matchit [evil-plugin03]: https://github.com/bling/evil-visualstar [evil-plugin04]: https://github.com/timcharper/evil-surround [evil-plugin05]: https://github.com/Dewdrops/evil-exchange [vim-plugin01]: http://www.vim.org/scripts/script.php?script_id=1905 [vim-plugin02]: http://www.vim.org/scripts/script.php?script_id=39 [vim-plugin03]: http://www.vim.org/scripts/script.php?script_id=1697 [vim-plugin04]: https://github.com/tommcdo/vim-exchange [evil-org-mode]: https://github.com/edwtjo/evil-org-mode [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 [edts]: https://github.com/tjarvstrand/edts [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 [monokai-theme]: https://github.com/oneKelvinSmith/monokai-emacs [zenburn-theme]: https://github.com/bbatsov/zenburn-emacs [git-gutter]: https://github.com/syohex/emacs-git-gutter-fringe [magit]: http://magit.github.io/ [smeargle]: https://github.com/syohex/emacs-smeargle [git-timemachine]: https://github.com/pidu/git-timemachine [git-messenger]: https://github.com/syohex/emacs-git-messenger [neotree]: http://www.emacswiki.org/emacs/NeoTree