***

Spacemacs

| [philosophy][] | [goals][] | [for who?][] | [screenshots][] | [documentation][DOCUMENTATION.md] | [contribute][CONTRIBUTE.md] | [achievements][] | [FAQ][] | *** [![Build Status](https://travis-ci.org/syl20bnr/spacemacs.svg)](https://travis-ci.org/syl20bnr/spacemacs) [![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)[![Twitter][]](http://www.twitter.com/spacemacs) *** **Quick Install:** git clone --recursive http://github.com/syl20bnr/spacemacs ~/.emacs.d **Table of Contents** - [Introduction](#introduction) - [Features](#features) - [Batteries Included](#batteries-included) - [Nice UI](#nice-ui) - [Excellent Evil Support](#excellent-evil-support) - [Convenient and Mnemonic Key Bindings](#convenient-and-mnemonic-key-bindings) - [Great [Documentation][DOCUMENTATION.MD]](#great-documentationdocumentationmd) - [Prerequisites](#prerequisites) - [Emacs version](#emacs-version) - [OS X](#os-x) - [Install](#install) - [Update](#update) - [Update notification](#update-notification) - [Rollback](#rollback) - [Configuration](#configuration) - [Configuration layers](#configuration-layers) - [Dotfile (.spacemacs)](#dotfile-spacemacs) - [Learning Spacemacs](#learning-spacemacs) - [Evil-tutor](#evil-tutor) - [The leader key](#the-leader-key) - [Universal argument](#universal-argument) - [Configuration layers and Package discovery](#configuration-layers-and-package-discovery) - [Key bindings discovery](#key-bindings-discovery) - [Describe functions](#describe-functions) - [Contributions](#contributions) - [Credits](#credits) - [FAQ](#faq) - [Common](#common) - [Windows](#windows) - [OS X](#os-x) # Introduction `Spacemacs` is a user-friendly and well-documented Emacs kit that integrates the best Emacs packages out there. It uses [Evil Mode][] to combine the ergonomic editing features of Vim with the extensibility of Emacs. Spacemacs is designed to be approachable for users coming from Vim–you do not need prior experience with Emacs to get started. If you are already an experienced Emacs user, you will appreciate the elegantly customized system and carefully curated, tightly integrated, set of packages. Spacemacs is currently in beta, and contributions are welcome. # Features ## Batteries Included Spacemacs integrates hundreds of packages and is ready to use with no additional configuration. It provides excellent support for many languages, including these: - [Elixir][] - [Haskell][] - [JavaScript][] - [LaTeX][] - [Python][] - [R][] - [Ruby][] - SCSS - [Scala][] - [Clojure][] - [C-C++][] It also ships with [Git support][] and [project management][] tools. All features are lazily loaded (on-demand) to minimize startup time. The Spacemacs community provides [additional configurations][contrib layers] that extend this default distribution. **[Visit the Documentation][DOCUMENTATION.MD]** ## Nice UI Spacemacs looks good. It ships with quality themes and a minimalist modeline. ![spacemacs_python](doc/img/spacemacs-python.png) ## Excellent Evil Support Spacemacs is designed around Vim keyboard bindings powered by [Evil Mode][]. The core packages are customized to integrate seamlessly with Evil. Spacemacs improves upon Vim by using task-specific states to group related commands. These states reduce the keystrokes needed to issue repetitive commands and reduce the number of keyboard bindings to learn. ## Convenient and Mnemonic Key Bindings `Spacemacs` organizes key bindings into mnemonic groups. For example, commands to operate on the buffer are prefixed by ` b`, and commands to operate on the project are under ` p`. There is no need to learn convoluted Emacs key chords–Spacemacs uses memorable bindings that are easy to type. ### Great [Documentation][DOCUMENTATION.MD] Most of Spacemacs' features, key bindings, and configuration options are extensively documented. If you need help, ask your question in the [Gitter Chat][] and a member of the community will help you out. # Prerequisites ## Emacs version `Spacemacs` is tested with Emacs 24.3 and 24.4 and therefore should boot on all the major OSes where these versions are installable. Some modes require third-party tools that you'll have to install via your favorite package manager. ## OS X The recommended version for OS X is [emacs-mac-port][]. It can be installed via [homebrew][] with the following commands: ```sh $ brew tap railwaycat/emacsmacport $ brew install emacs-mac ``` The default key handling is different from the official OS X port. To correct this you can add the [osx layer][] to your [dotfile][] layer list: ```elisp (setq-default dotspacemacs-configuration-layers '(osx)) ``` Note that the `emacs-mac-port` server behaves differently than the regular Emacs server. Details can be found on the emacs-mac-port [README][emacs-mac-port-server]. # Install 1. If you have an existing Emacs configuration, back it up: ```sh cd ~ mv .emacs.d .emacs.bak ``` 2. Clone this repository _with its submodules_: ```sh git clone --recursive http://github.com/syl20bnr/spacemacs ~/.emacs.d ``` `master` is the stable branch and is regularly updated. Switch to the `develop` branch if you want to use the bleeding-edge version. 3. Launch Emacs. Spacemacs will automatically install the packages it requires. 4. Restart Emacs to complete the installation. If you see something like this: ``` Loading............................................................Ready! [121 packages loaded in 3.208s] ``` then you should be good to go! Otherwise, see the [troubleshooting][troubleshoot] guide. # Update Spacemacs currently requires manual updates using the following procedure: 1. Update Emacs packages by clicking (press `RET`) on the `[Update]` link of the starting page. 2. Close Emacs and update the git repository: ```sh git pull --rebase git submodule sync; git submodule update ``` 3. Restart Emacs to complete the upgrade. ## Update notification For convenience an indicator is displayed in the mode-line whenever a new version of `Spacemacs` is available. Symbol | Description :------------------------------------:|---------------------------------- ![git-new](doc/img/update-green.png) | < 3 releases behind ![git-del](doc/img/update-orange.png) | < 5 releases behind ![git-mod](doc/img/update-red.png) | >= 5 releases behind **Note:** A feature allowing update by merely clicking on the indicator will be implemented _soon_! ## Rollback Should anything go wrong during an update, you can rollback ELPA packages to a previous version. Click (press `RET`) on the `[Rollback]` link of the startup page, choose a rollback slot. Rollback slot names are dates with the following format `YYYY-MM-DD_HH.MM.SS`. The date corresponds to the date of an update. The most recent slots are listed first. # Configuration `Spacemacs` divides its configuration into self-contained units called [configuration layers][config]. These layers are stacked on top of each other to achieve a custom configuration. `Spacemacs` uses the dotfile `~/.spacemacs` to control which layers to load. Within this file you may also generally configure certain features. ## Configuration layers A configuration layer is a directory containing at least the following files: - `packages.el`: Defines and configures packages to be downloaded from Emacs package repositories using `package.el` - `extensions.el`: Configures packages which cannot be downloaded with `package.el` such as built-in Emacs features and git submodules. If you already have your own `Emacs` configuration you can move it to your own layer. The following command creates a layer in the `private` directory: : configuration-layer/create-layer RET Any configuration layers you create must be explicitly loaded in `~/.spacemacs`. **Note:** For your privacy, the contents of the `private` directory are not under source control. See the documentation for a discussion on how to [manage your private configuration][manage_config]. ## Dotfile (.spacemacs) As mentioned `.spacemacs` controls which configuration layers to load and is also a means to customizing `Spacemacs`. The following command will create a `.spacemacs` file in your home directory: : dotspacemacs/install RET ...to open the installed dotfile: f e d ...to load some configuration layers using the variable `dotspacemacs-configuration-layers`: ```elisp ;; List of configuration layers to load. dotspacemacs-configuration-layers '(company-mode smex) ``` Some configuration layers support configuration variables to expose granular control over layer-specific features, [git layer][] being one such example. Variables can be directly set within `dotspacemacs-configuration-layers` like so: ```elisp ;; List of configuration layers to load. dotspacemacs-configuration-layers '(company-mode (git :variables git-magit-status-fullscreen t git-enable-github-support t git-gutter-use-fringe t) smex) ``` At anytime you can apply the changes made to the dotfile _without restarting_ `Spacemacs` by pressing SPC m c c. The [comments in this file][dotfile template] contain further information about how to customize `Spacemacs`. See the [dotfile configuration][dotfile] section of the documentation for more details. # Learning Spacemacs ## Evil-tutor Press SPC h T to begin an Evil-adapted Vimtutor. ## The leader key `Spacemacs` key bindings use a leader key which is by default bound to SPC (space bar). Change it by setting the variable `dotspacemacs-leader-key` in `~/.spacemacs`. ## Universal argument In `Spacemacs` the universal argument defaults to ` u` instead of `C-u` because the latter is used to scroll up as in Vim. ## Configuration layers and Package discovery By using `helm-spacemacs` with SPC f e h you can quickly search for a package and get the name of the layers using it. You can also easily go to the `README.md` of a layer or go to the initialization function of a package. ## Key bindings discovery Thanks to [guide-key][], whenever a prefix command is pressed (like ``) a buffer appears after one second listing the possible keys for this prefix. It is also possible to search for specific key bindings by pressing: ? To narrow the bindings list to those prefixed with ``, type a pattern like this regular expression: SPC\ b which would list all `buffer` related bindings. ## Describe functions `Describe functions` are powerful Emacs introspection commands to get information about functions, variables, modes etc. These commands are bound thusly: Key Binding | Description --------------|------------------------------------------------------------------ ` h d f` | describe-function ` h d k` | describe-key ` h d m` | describe-mode ` h d v` | describe-variable # Contributions `Spacemacs` needs _you_! We especially need to create more configuration layers that, for instance, bring support for new languages. If you are ready to contribute please begin by consulting the [contribution guidelines][CONTRIBUTE.md], thanks! # Credits [Spacemacs logo][] by [Nasser Alshammari][] released under a Creative Commons license. # FAQ ## Common 1. **Which version of Spacemacs am I running ?** The version is displayed on the upper right corner of the loading screen. You may also just type SPC f e v. 2. **Why are packages installed with `package-install` automatically deleted by Spacemacs when it boots ?** To declare new packages you have to create a new configuration layer, see the [quick start guide](#configuration). 3. **The Spacemacs banner is ugly, what should I do ?** Install the default font supported by Spacemacs or choose a fixed width font. More information in the [font section][] of the documentation. 4. **The powerline separators are ugly, how can I fix them ?** Use the property `:powerline-scale` of the variable `dotspacemacs-default-font`. See [font][] documentation for more details. 5. **The powerline separators have no anti-aliasing, what can I do ?** Emacs powerline uses XMP images to draw the separators in a graphical environment. You can have anti-aliasing if you use the `utf8` separator. Note that by default the `utf8` separator is used in a terminal. See the powerline section in the [documentation][powerline-doc]. ## Windows 1. **Why do the fonts on Windows looks so crappy ?** You can install [MacType][] on Windows to get very nice looking fonts. It is also recommended to disable smooth scrolling on Windows. 2. **How to fix the error: The directory ~/.emacs.d/server is unsafe ?** Change the owner of the directory `~/.emacs.d/server`: - from Properties select the Tab “Security”, - select the button “Advanced”, - select the Tab “Owner” - change the owner to your account name Source: [Stackoverflow][so-server-unsafe] ## OS X 1. **Why are the powerline colors not correct on OS X ?** This is a [known issue][powerline-srgb-issue] as of Emacs 24.4 due to `ns-use-srgb-colorspace` defaulting to true. It is recommended to use the [emacs-mac-port][] build. See the [install OSX section][] for more details. [Twitter]: http://i.imgur.com/tXSoThF.png [philosophy]: doc/DOCUMENTATION.md#philosophy [goals]: doc/DOCUMENTATION.md#goals [for who?]: doc/DOCUMENTATION.md#who-can-benefit-from-this- [screenshots]: doc/DOCUMENTATION.md#screenshots [config]: doc/DOCUMENTATION.md#configuration-layers [dotfile]: doc/DOCUMENTATION.md#dotfile-configuration [manage_config]: doc/DOCUMENTATION.md#managing-private-configuration-layers [using_package_buf]: doc/DOCUMENTATION.md#using-the-package-list-buffer [achievements]: doc/DOCUMENTATION.md#achievements [troubleshoot]: doc/DOCUMENTATION.md#troubleshoot [contrib layers]: doc/DOCUMENTATION.md#using-configuration-layers [Git support]: contrib/git/README.md [git layer]: contrib/git [ace-jump]: doc/DOCUMENTATION.md#vim-motions-with-ace-jump-mode [project management]: doc/DOCUMENTATION.md#project-management [Evil Mode]: doc/DOCUMENTATION.md#evil [private]: ./private [DOCUMENTATION.md]: doc/DOCUMENTATION.md [font section]: doc/DOCUMENTATION.md#font [CONTRIBUTE.md]: doc/CONTRIBUTE.md [powerline-seps]: doc/DOCUMENTATION.md#powerline-separators [FAQ]: https://github.com/syl20bnr/spacemacs#faq [dotfile]: https://github.com/syl20bnr/spacemacs#dotfile-spacemacs [dotfile template]: ./core/templates/.spacemacs.template [install OSX section]: https://github.com/syl20bnr/spacemacs#os-x [osx layer]: contrib/osx/README.md [guide-key]: https://github.com/kai2nenobu/guide-key [guide-key-tip]: https://github.com/aki2o/guide-key-tip [evil-nerd-commenter]: https://github.com/redguardtoo/evil-nerd-commenter [Gitter Chat]: https://gitter.im/syl20bnr/spacemacs [MacType]: https://code.google.com/p/mactype/ [emacs-mac-port]: https://github.com/railwaycat/emacs-mac-port [emacs-mac-port-server]: https://github.com/railwaycat/emacs-mac-port/blob/master/README-mac#L210-L213 [homebrew]: https://github.com/Homebrew/homebrew [Elixir]: contrib/lang/erlang-elixir [Haskell]: contrib/lang/haskell [LaTeX]: contrib/auctex [JavaScript]: contrib/lang/javascript [Python]: contrib/lang/python [R]: contrib/lang/ess [Ruby]: contrib/lang/ruby [Scala]: contrib/lang/scala [Clojure]: contrib/lang/clojure [C-C++]: contrib/lang/c-c++ [powerline-srgb-issue]: https://github.com/milkypostman/powerline/issues/54 [powerline-doc]: doc/DOCUMENTATION.md#powerline-separators [so-server-unsafe]: http://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start [Spacemacs logo]: https://github.com/nashamri/spacemacs-logo [Nasser Alshammari]: https://github.com/nashamri