Professional Documents
Culture Documents
[Introduction](#introduction)
[Features](#features)
[Documentation](#documentation)
[Getting Help](#getting-help)
[Prerequisites](#prerequisites)
- [Emacs](#emacs)
- [Linux distros](#linux-distros)
- [macOS](#macos)
- [Windows](#windows)
- [Install](#install)
- [Default installation](#default-installation)
- [Alternate installations](#alternate-installations)
- [Modify HOME environment variable](#modify-home-environment-variable)
- [Modify spacemacs-start-directory variable](#modify-spacemacs-start-di
rectory-variable)
- [Spacemacs logo](#spacemacs-logo)
- [Update](#update)
- [Automatic update (on master branch)](#automatic-update-on-master-branch)
- [Manual update (on master branch)](#manual-update-on-master-branch)
- [On develop branch](#on-develop-branch)
- [Revert to a specific version](#revert-to-a-specific-version)
- [Quotes](#quotes)
- [Contributions](#contributions)
- [Communities](#communities)
- [License](#license)
- [Supporting Spacemacs](#supporting-spacemacs)
<!-- markdown-toc end -->
# Introduction
Spacemacs is a new way to experience Emacs -- a sophisticated and
polished set-up focused on ergonomics, mnemonics and consistency.
Just clone it, launch it, then press the space bar to explore the
interactive list of carefully-chosen key bindings. You can also press
the home buffer's `[?]` button for some great first key bindings to
try.
Spacemacs can be used naturally by both Emacs and Vim users -- you can
even mix the two editing styles. Switching easily between input styles
makes Spacemacs a great tool for pair-programming.
Spacemacs is currently in beta, and contributions are very welcome.
![spacemacs_python](doc/img/spacemacs-python.png)
# Features
- **Great documentation:** access documentation in Emacs with
<kbd>SPC h SPC</kbd>.
- **Beautiful GUI:** you'll love the distraction free UI and its functional
mode-line.
- **Excellent ergonomics:** all the key bindings are accessible by pressing
the <kbd>space bar</kbd> or <kbd>alt-m</kbd>.
- **Mnemonic key bindings:** commands have mnemonic prefixes like
<kbd>SPC b</kbd> for all the buffer commands or <kbd>SPC p</kbd> for the
project commands.
- **Batteries included:** discover hundreds of ready-to-use packages nicely
organised in configuration layers following a set of
[conventions][CONVENTIONS.org].
# Documentation
Comprehensive documentation is available for each layer by pressing
<kbd>SPC h SPC</kbd>.
You can also check the [general documentation][DOCUMENTATION.org],
[quick start guide][QUICK_START.org] and the [FAQ][FAQ.org].
# Getting Help
If you need help, ask your question in the [Gitter Chat][] and a member of the
community will help you out.
If you prefer IRC, connect to the [Gitter Chat IRC server][] and join the
`#syl20bnr/spacemacs` channel.
# Prerequisites
## Emacs
Spacemacs requires Emacs 24.4 or above. The development version of Emacs (at the
time of writing, this is 25.2) is not *officially* supported, but should
nevertheless be expected to work.
Some modes require third-party tools that you'll have to install via your
favorite package manager.
### Linux distros
Install Emacs from the package manager of your Linux distribution.
You should install the "emacs" package, not the "xemacs" package.
XEmacs is an old fork of Emacs. The X in its name is unrelated to X11.
Both Emacs and XEmacs have graphical support.
**Note:** Ubuntu LTS 12.04 and 14.04 repositories have only Emacs 24.3
available. You have to [build from source][build_source] Emacs 24.4 or greater,
as Spacemacs won't work with 24.3. The same may be true for other distributions
as well.
### macOS
The recommended way of installing Emacs on macOS is using [homebrew][]:
```sh
$ brew tap d12frosted/emacs-plus
$ brew install emacs-plus
$ brew linkapps emacs-plus
```
*Note:* these homebrew commands will install GNU Emacs, and link it to your
`/Applications` directory. You still need to run the `git clone` mentioned at
the start of this file. That will populate your `~/.emacs.d` directory, which is
what transforms a regular GNU Emacs into Spacemacs.
*Note:* the proposed `emacs-plus` tap is identical to the `emacs` formulae, it
just builds GNU Emacs with support of several features by default along with
providing Spacemacs icon.
See [emacs-plus](https://github.com/d12frosted/homebrew-emacs-plus) for more
information.
*Note:* after you have completed the [install process](#install) below, it is
also recommended to add the [osx layer][] to your [dotfile][]. Install
```
Don't forget to backup and *remove* `~/.emacs` file otherwise Spacemacs
**WILL NOT** load since that file prevents Emacs from loading the proper
initialization file.
2. Clone the repository:
```sh
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
`master` is the stable branch and it is _immutable_, **DO NOT** make any
modification to it or you will break the update mechanism. If you want to
fork Spacemacs safely use the `develop` branch where you handle the update
manually.
3. (Optional) Install the [Source Code Pro][] font.
If you are running in terminal you'll also need to change font settings of
your terminal.
4. Launch Emacs. Spacemacs will automatically install the packages it requires.
If you get an error regarding package downloads then you may try to disable
the HTTPS protocol by starting Emacs with
```sh
emacs --insecure
```
Or you can set the `dotspacemacs-elpa-https` to `nil` in your dotfile to
remove the need to start Emacs with `--insecure` argument. You may wish to
clear out your `.emacs.d/elpa` directory before doing this, so that any
corrupted packages you may have downloaded will be re-installed.
5. Restart Emacs to complete the installation.
If the mode-line turns red then be sure to consult the [FAQ][FAQ.org].
## Alternate installations
It may be useful to clone Spacemacs outside Emacs dotdirectory `~/.emacs.d` so
you can try Spacemacs without replacing completely our own configuration.
There is currently two possibilities to support alternative location for
Spacemacs configuration.
### Modify HOME environment variable
This solution is ideal to quickly try Spacemacs without compromising your
existing configuration.
```sh
mkdir ~/spacemacs
git clone https://github.com/syl20bnr/spacemacs.git ~/spacemacs/.emacs.d
HOME=~/spacemacs emacs
```
Note: If you're on Fish shell, you will need to modify the last command to: `env
HOME=$HOME/spacemacs emacs`