philosophy | for whom? | screenshots | documentation | contribute | achievements | FAQ

`. 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: [Stack Overflow][so-server-unsafe] For efficient searches we recommend to install `pt` ([the platinum searcher][]). `pt` version 1.7.7 or higher is required. # Install ## Default installation 1. If you have an existing Emacs configuration, back it up first by running the following code in your terminal: ```sh cd ~ mv .emacs.d .emacs.d.bak mv .emacs .emacs.bak ``` 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 with [Git][]: ```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. **Note for Windows users** If you use windows, you have to modify the git command by inserting the correct path to your .emacs.d folder. The dot before the folder means that it is hidden, so you'll have to search for hidden files to find the folder. When you have found the folder, substitute the original path with the correct one. The proper code would look something like this: ```sh git clone https://github.com/syl20bnr/spacemacs /path/to/your/.emacs.d ``` 3. Install the default fonts The default font used by Spacemacs is [Source Code Pro][] by Adobe. It is recommended to install it to ensure correct visual representation. Also a "Fallback font" for nicer-looking symbols in the modeline (bottom bar) is recommended. These depend on the system: - GNU/Linux: *NanumGothic* (package named *fonts-nanum* on Debian, for example) - macOS: *Arial Unicode MS* - Windows: *MS Gothic* or *Lucida Sans Unicode* If the modeline doesn't look as great as in the pictures, make sure you have the correct fallback font installed. 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. Finally, restart Emacs to complete the installation. **Note:** 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 `~/.spacemacs` 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. **Note:** `error: Package 'package-build-' is unavailable` may occur due to heavy network taffic. You can fix it by setting the `dotspacemacs-elpa-timeout` to `70` in your dotfile. **Note:** `Warning (bytecomp)` and other compilation warnings are perfectly normal. If curious, you can find out why these occur [here](https://github.com/quelpa/quelpa/issues/90#issuecomment-137982713). If the mode-line turns red then be sure to consult the [FAQ][FAQ.org]. ## Alternative installations It may be useful to clone Spacemacs outside Emacs dotdirectory `~/.emacs.d` so you can try Spacemacs without replacing completely your 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` ### Modify spacemacs-start-directory variable This solution is better suited to "embed" Spacemacs into your own configuration. Say you cloned Spacemacs in `~/.emacs.d/spacemacs/` then drop these lines in `~/.emacs.d/init.el`: ```elisp (setq spacemacs-start-directory "~/.emacs.d/spacemacs/") (load-file (concat spacemacs-start-directory "init.el")) ``` ## Spacemacs logo For Ubuntu users, follow this guide to [change the logo in Unity][cpaulik-unity-icon]. For Mac users, you need to [download the .icns version of the logo][icon-repository], then [change the logo on Dock][icon-mac-instructions]. # 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 (on master branch) 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 mean that your current version is older.  Click on the arrow to update Spacemacs to the last version. ## Manual update (on master branch) (Remove the angle brackets when typing the lines below into your shell.) ```sh git fetch git reset --hard ``` ## On develop branch 1. Update Emacs packages by clicking (press `RET`) on the `[Update Packages]` link of the starting page. 2. Close Emacs and update the git repository: ```sh git pull --rebase ``` 3. 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`: ```sh git checkout origin/release-0.103 ``` **After you update, either manually, or automatically, you are advised to update your packages by clicking the `[Update Packages]` button on the Spacemacs Home Buffer.** # Quotes [Quote][quote01] by [ashnur](https://github.com/ashnur): «I feel that spacemacs is an aircraft carrier and I am playing table tennis on the deck as a freerider.» [Quote][quote02] by [deuill](https://github.com/deuill): «I LOVE SPACEMACS AND MAGIT That is all» # Contributions Spacemacs is a community-driven project, it needs _you_ to keep it up to date and propose great and useful configuration for all the things! Before contributing be sure to consult the [contribution guidelines][CONTRIBUTING.org] and [conventions][CONVENTIONS.org]. Here is a throughput graph of the repository for the last few weeks: [](https://waffle.io/syl20bnr/spacemacs/metrics) # Communities - [Gitter Chat] - [Stack Exchange] - [Reddit] # 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 Attribution-ShareAlike 4.0 International License.](http://creativecommons.org/licenses/by-sa/4.0/) # 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. You can show your love for the project by getting cool Spacemacs t-shirts, mugs and more in the [Spacemacs Shop][]. If you want to show your support financially you can contribute to [Bountysource][] or buy a drink for the maintainer by clicking on the [Paypal badge](#top). If you used spacemacs in a project and you want to show that fact, you can use the spacemacs badge: [](http://spacemacs.org) - For Markdown: ``` [](http://spacemacs.org) ``` - For HTML: ``` ``` - For Org-mode: ``` [[http://spacemacs.org][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]] ``` Thank you! [Twitter]: http://i.imgur.com/tXSoThF.png [CONTRIBUTING.org]: CONTRIBUTING.org [CONVENTIONS.org]: http://spacemacs.org/doc/CONVENTIONS [DOCUMENTATION.org]: http://spacemacs.org/doc/DOCUMENTATION [QUICK_START.org]: http://spacemacs.org/doc/QUICK_START [FAQ.org]: http://spacemacs.org/doc/FAQ [VIMUSERS.org]: http://spacemacs.org/doc/VIMUSERS [dotfile]: http://spacemacs.org/doc/DOCUMENTATION#orgheadline45 [osx layer]: http://spacemacs.org/layers/+os/osx/README.html [Gitter Chat]: https://gitter.im/syl20bnr/spacemacs [Gitter Chat IRC server]: https://irc.gitter.im/ [Homebrew]: http://brew.sh [emacs-for-windows]: http://emacsbinw64.sourceforge.net/ [emacs-for-windows-stable]: https://sourceforge.net/projects/emacsbinw64/files/release/ [the platinum searcher]: https://github.com/monochromegane/the_platinum_searcher [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 [cpaulik-unity-icon]: http://splendidabacus.com/posts/2015/03/spacemacs-unity-icon/ [icon-mac-instructions]: http://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/ [icon-repository]: https://github.com/nashamri/spacemacs-logo [Stack Exchange]: http://emacs.stackexchange.com/questions/tagged/spacemacs [Reddit]: https://www.reddit.com/r/spacemacs [quote01]: https://gitter.im/syl20bnr/spacemacs?at=568e627a0cdaaa62045a7df6 [quote02]: https://gitter.im/syl20bnr/spacemacs?at=5768456c6577f032450cfedb [build_source]: https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html [Bountysource]: https://salt.bountysource.com/teams/spacemacs [Source Code Pro]: https://github.com/adobe-fonts/source-code-pro [Spacemacs Shop]: https://shop.spreadshirt.com/spacemacs-shop [Git]: https://git-scm.com/downloads