471fce6106
As proposed in #2144, Use [=] as an alias of [+], and use [0] instead for resetting the zoom. Add a missing `q` binding/documentation. Close #2144 |
||
|---|---|---|
| assets | ||
| core | ||
| doc | ||
| layers | ||
| private | ||
| tests | ||
| travis | ||
| .gitignore | ||
| .projectile | ||
| .travis.yml | ||
| CHANGELOG.org | ||
| CONTRIBUTING.md | ||
| README.md | ||
| init.el | ||
| spacemacs.mk | ||
README.md
 
philosophy | goals | for whom? | screenshots | documentation | contribute | achievements | FAQ
***Quick Install:
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
Table of Contents
- Introduction
- Features
- Documentation
- Getting Help
- Prerequisites
- Install
- Update
- Contributions
- License
- Supporting Spacemacs
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.
Features
- Great documentation: Access documentation in Emacs with SPC f e h
- 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 space bar or alt-m.
- Mnemonic key bindings: commands have mnemonic prefixes like SPC b for all the buffer commands or SPC p for the project commands.
- Batteries included: discover hundreds of ready-to-use packages nicely organised in configuration layers following a set of conventions.
Documentation
A comprehensive documentation is available for each layer by pressing SPC f e h.
To go to the general documentation click here.
You can also check the Quick Start guide and the FAQ.
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 is operational with Emacs 24.3 but Emacs 24.4 and above are recommended to enjoy the full experience.
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.
OS X
We recommend the homebrew emacs-mac-port formula:
$ brew tap railwaycat/homebrew-emacsmacport
$ brew install emacs-mac --with-spacemacs-icon # OR, brew cask install emacs-mac
It is also recommended to add the osx layer to your dotfile:
(setq-default dotspacemacs-configuration-layers '(osx))
Note that the emacs-mac-port server behaves differently than the regular Emacs
server which in particular DOES NOT allow multi-tty if you start GUI i.e.
you can't connect to the Emacs GUI server with emacsclient but server-client
works if you start from terminal(TTY-only).
Details can be found on the emacs-mac-port README.
Windows
Good quality builds can be found on this page. It is recommended to install the most stable build.
Be sure to declare a environment variable named HOME pointing to your user
directory C:\Users\<username>. Then you can clone Spacemacs in this directory.
Sometimes you'll get the following error when you first start Emacs:
The directory ~/.emacs.d/server is unsafe
To fix it 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
For efficient searches we recommend to install pt (the platinum searcher).
pt version 1.7.7 or higher is required.
Install
-
If you have an existing Emacs configuration, back it up first:
cd ~ mv .emacs.d .emacs.d.bak mv .emacs .emacs.bakDon't forget to backup and remove
~/.emacsfile otherwise Spacemacs WILL NOT load since that file prevents Emacs from loading the proper initialization file. -
Clone the repository:
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.dmasteris 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 thedevelopbranch where you handle the update manually. -
Launch Emacs. Spacemacs will automatically install the packages it requires.
-
Restart Emacs to complete the installation.
If the mode-line turns red then be sure to visit the troubleshooting guide and consult the FAQ.
Spacemacs logo
If you are using Ubuntu and Unity then you can add the Spacemacs logo by following the instructions here.
If you're on a mac follow these instructions. You can find an .icns version of the logo by Nasser Alshammari in his repository.
Update
Spacemacs has a built-in notification of a new version when you are on the
master branch. If you are on the develop branch then you'll have to
update Spacemacs manually by updating your repository.
Automatic update
When a new version is available a little arrow appears in the mode-line.
Its color depends on the number of versions available since your last update. Green means that your current version is recent, orange and red that your current version is older.
Click on the arrow to update Spacemacs to the last version.
On develop branch
-
Update Emacs packages by clicking (press
RET) on the[Update]link of the starting page. -
Close Emacs and update the git repository:
git pull --rebase -
Restart Emacs to complete the upgrade.
Revert to a specific version
To revert to a specific version you just have to checkout the corresponding
branch, for instance to revert to the last 0.103:
git checkout origin/release-0.103
Contributions
Spacemacs is a community-driven project, it needs you to keep it up to date and propose useful and complete configuration!
Before contributing be sure to consult the contribution guidelines and conventions.
License
The license is GPLv3 for all parts specific to Spacemacs, this includes:
- the initialization and core files
- all the layer files.
- the documentation
For the packages shipped in this repository you can refer to the files header.
Spacemacs logo by Nasser Alshammari released under a Creative Commons license.
Supporting Spacemacs
The best way to support Spacemacs is to contribute to it either by reporting bugs, helping the community on the Gitter Chat or sending pull requests.
If you want to show your support financially you can buy a drink to the maintainer by clicking on the Paypal badge.
If you used spacemacs in a project and you want to show that fact, you can use
the spacemacs badge 
.
-
For Markdown:
[](http://github.com/syl20bnr/spacemacs) -
For HTML:
<a href="https://github.com/syl20bnr/spacemacs"><img src="https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg" /></a> -
For Org-mode:
[[https://github.com/syl20bnr/spacemacs][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
Thank you!