2017-04-25 15:42:58 +00:00
< a name = "top" id = "fork-destination-box" > < / a >
2021-08-23 21:02:26 +00:00
< a href = "https://develop.spacemacs.org" > < img src = "https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg" alt = "Made with Spacemacs" > < a href = "https://www.gnu.org/licenses/gpl-3.0.en.html" > < img src = "https://github.com/syl20bnr/spacemacs/blob/655e2886d88f79f4da01d607d29342e7447cad65/assets/gplv3.png" alt = "GPLv3 Software" align = "right" width = "70" height = "28" > < / a > < / a > < a href = "https://www.twitter.com/spacemacs" > < img src = "https://i.imgur.com/tXSoThF.png" alt = "Twitter" align = "right" > < / a > < br >
2018-03-04 05:14:36 +00:00
- - -
2015-06-21 20:02:04 +00:00
< p align = "center" > < img src = "/doc/img/title2.png" alt = "Spacemacs" / > < / p >
2015-03-29 05:16:03 +00:00
< p align = "center" >
2021-08-23 21:02:26 +00:00
< b > < a href = "https://develop.spacemacs.org/doc/DOCUMENTATION#core-pillars" > philosophy< / a > < / b >
2015-03-29 05:16:03 +00:00
|
2021-08-23 21:02:26 +00:00
< b > < a href = "https://develop.spacemacs.org/doc/DOCUMENTATION#who-can-benefit-from-this" > for whom?< / a > < / b >
2015-03-29 05:16:03 +00:00
|
2021-08-23 21:02:26 +00:00
< b > < a href = "https://develop.spacemacs.org/doc/DOCUMENTATION#screenshots" > screenshots< / a > < / b >
2015-03-29 05:16:03 +00:00
|
2021-08-23 21:02:26 +00:00
< b > < a href = "https://develop.spacemacs.org/doc/DOCUMENTATION.html" > documentation< / a > < / b >
2015-03-29 05:16:03 +00:00
|
Refactor CONTRIBUTING documentations
This commit merge the `CONTRIBUTING.md` and `doc/CONTRIBUTE.org` file
into a new `CONTRIBUTING.org` file. It also refactors the content to be
more organized and make its navigation more goal-oriented.
Github displays a link to the `CONTRIBUTING.*` file when people are
opening new issues or proposing new PRs. This file is important because
it is the entry-point to contributions guidelines for most of the users.
The current setup is non-optimal, even broken, as it adds a level of
indirection, and points to a contributing file that has broken
links (due to the new documentation format). The possible drawback of
the proposed solution is that I'm not sure if it is possible to include
it into the new online documentation as it is not in `doc/` folder.
The other possibility is to keep a small `CONTRIBUTING.md` file, as it
is now, pointing to the new documentation system (once online), but I'm
preferring the proposed solution for the following reasons:
- People that are willing to contribute will probably open Github
first (for forking, creating PR, etc), not the online documentation.
- It has one level of indirection less when people click on the
guidelines guide from a new issue/PR.
- `CONTRIBUTING.*` is by convention a special kind of file on github, so
it's valid reason to break the rule and not having it in the `doc/`
folder.
2015-11-22 13:11:08 +00:00
< b > < a href = "CONTRIBUTING.org" > contribute< / a > < / b >
2015-03-29 05:16:03 +00:00
|
2021-08-23 21:02:26 +00:00
< b > < a href = "https://develop.spacemacs.org/doc/DOCUMENTATION#achievements" > achievements< / a > < / b >
2015-03-29 05:16:03 +00:00
|
2021-08-23 21:02:26 +00:00
< b > < a href = "https://develop.spacemacs.org/doc/FAQ" > FAQ< / a > < / b >
2015-03-29 05:16:03 +00:00
< / p >
2018-03-04 05:14:36 +00:00
- - -
2016-03-04 15:29:17 +00:00
< p align = "center" >
< a href = "https://gitter.im/syl20bnr/spacemacs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" > < img src = "https://badges.gitter.im/Join Chat.svg" alt = "Gitter" > < / a >
2022-03-10 22:26:08 +00:00
< a href = "https://discord.gg/p4MddFu6Ag" > < img src = "https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt = "Discord" > < / a >
2021-04-14 11:28:47 +00:00
< a href = "https://github.com/syl20bnr/spacemacs/actions/workflows/elisp_test.yml" > < img src = "https://github.com/syl20bnr/spacemacs/actions/workflows/elisp_test.yml/badge.svg?branch=develop" > < / a >
2016-03-04 15:29:17 +00:00
< a href = "https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESFVNPKP4Y742" > < img src = "https://img.shields.io/badge/Paypal-Donate-blue.svg" alt = "Donate" > < / a >
2016-10-19 02:48:35 +00:00
< a href = "https://shop.spreadshirt.com/spacemacs-shop" > < img src = "https://img.shields.io/badge/Shop-T--Shirts-blue.svg" alt = "Donate" > < / a >
2021-03-26 17:15:06 +00:00
< a href = "https://www.slant.co/topics/12/~what-are-the-best-programming-text-editors" > < img src = "https://img.shields.io/badge/Slant-Recommend-ff69b4.svg" alt = "Recommend it" > < / a >
2016-03-04 15:29:17 +00:00
< / p >
2018-03-04 05:14:36 +00:00
- - -
2021-06-02 03:33:30 +00:00
2022-05-15 08:19:57 +00:00
**Quick Install**
2014-11-24 03:42:31 +00:00
2017-05-24 12:08:11 +00:00
This assumes you don't have an existing Emacs setup and want to run Spacemacs as
2022-06-04 18:49:24 +00:00
your config. If you do have one, look at the [full installation
instructions](#install) for other options.
2016-10-31 17:45:31 +00:00
2022-05-15 08:19:57 +00:00
```shell
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
* Windows Command Prompt:
```
git clone https://github.com/syl20bnr/spacemacs %appdata%/.emacs.d
2017-10-13 17:35:18 +00:00
```
2022-05-15 08:19:57 +00:00
* Windows PowerShell:
```powershell
git clone https://github.com/syl20bnr/spacemacs $env:appdata/.emacs.d
2017-10-13 17:35:18 +00:00
```
2021-07-31 10:11:11 +00:00
<!-- markdown - toc start - Don't edit this section. Run M - x markdown - toc - refresh - toc -->
2015-07-24 02:38:09 +00:00
**Table of Contents**
- [Introduction ](#introduction )
- [Features ](#features )
2015-09-23 03:26:12 +00:00
- [Documentation ](#documentation )
- [Getting Help ](#getting-help )
2015-07-24 02:38:09 +00:00
- [Prerequisites ](#prerequisites )
- [Emacs ](#emacs )
- [Linux distros ](#linux-distros )
2016-09-24 04:58:14 +00:00
- [macOS ](#macos )
2021-07-31 10:11:11 +00:00
- [Install emacs ](#install-emacs )
- [Using emacs-plus ](#using-emacs-plus )
- [Using emacs-mac ](#using-emacs-mac )
- [Using cask ](#using-cask )
- [Other ways ](#other-ways )
- [Install Source Code Pro font ](#install-source-code-pro-font )
- [Install Spacemacs ](#install-spacemacs )
2015-07-24 02:38:09 +00:00
- [Windows ](#windows )
2021-07-31 10:11:11 +00:00
- [Install Spacemacs in Windows ](#install-spacemacs-in-windows )
- [Notes ](#notes )
2015-07-24 02:38:09 +00:00
- [Install ](#install )
2016-02-01 01:43:08 +00:00
- [Default installation ](#default-installation )
2017-04-20 06:40:14 +00:00
- [Alternative installations ](#alternative-installations )
2016-06-23 04:25:04 +00:00
- [Modify HOME environment variable ](#modify-home-environment-variable )
- [Modify spacemacs-start-directory variable ](#modify-spacemacs-start-directory-variable )
2015-07-24 02:38:09 +00:00
- [Spacemacs logo ](#spacemacs-logo )
- [Update ](#update )
2022-01-03 21:00:08 +00:00
- [Rolling update (on develop) ](#rolling-update-on-develop )
2016-01-10 17:42:32 +00:00
- [Automatic update (on master branch) ](#automatic-update-on-master-branch )
- [Manual update (on master branch) ](#manual-update-on-master-branch )
2022-01-03 21:00:08 +00:00
- [Revert to a specific version (on master branch) ](#revert-to-a-specific-version-on-master-branch )
2016-01-11 05:38:58 +00:00
- [Quotes ](#quotes )
2015-01-06 23:50:20 +00:00
- [Contributions ](#contributions )
2016-01-10 17:42:32 +00:00
- [Communities ](#communities )
2019-06-22 18:06:17 +00:00
- [Spacemacs Everywhere ](#spacemacs-everywhere )
2015-04-08 02:51:21 +00:00
- [License ](#license )
2015-04-08 02:00:10 +00:00
- [Supporting Spacemacs ](#supporting-spacemacs )
2015-01-06 23:50:20 +00:00
<!-- markdown - toc end -->
2014-11-20 01:11:25 +00:00
# Introduction
2017-04-22 16:35:00 +00:00
Spacemacs is a new way of experiencing Emacs -- it's a sophisticated and
polished set-up, focused on ergonomics, mnemonics and consistency.
2014-10-16 17:03:17 +00:00
2017-04-22 16:35:00 +00:00
Just clone and 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.
2014-10-16 17:03:17 +00:00
2017-04-22 16:35:00 +00:00
Spacemacs can be used naturally by both Emacs and Vim users -- you can even mix
the two editing styles. Being able to quickly switch between input styles, makes
Spacemacs a great tool for pair-programming.
2015-03-29 04:42:37 +00:00
2017-04-22 16:35:00 +00:00
Spacemacs is currently in beta, and any contributions are very welcome.
2014-10-16 17:03:17 +00:00
2015-09-28 05:42:55 +00:00
![spacemacs_python ](doc/img/spacemacs-python.png )
2014-11-22 21:53:38 +00:00
# Features
2017-04-22 16:35:00 +00:00
- **Great documentation:** access the Spacemacs documentation with
2015-12-21 13:50:36 +00:00
< kbd > SPC h SPC< / kbd > .
2015-09-23 03:26:12 +00:00
- **Beautiful GUI:** you'll love the distraction free UI and its functional
mode-line.
2017-04-22 16:35:00 +00:00
- **Excellent ergonomics:** all the key bindings are accessible by pressing the
< kbd > space bar< / kbd > or < kbd > alt-m< / kbd > .
2015-09-23 03:26:12 +00:00
- **Mnemonic key bindings:** commands have mnemonic prefixes like
2017-04-22 16:35:00 +00:00
< kbd > SPC b< / kbd > for all the buffer commands or < kbd > SPC p< / kbd > for the project
commands.
2015-09-23 03:26:12 +00:00
- **Batteries included:** discover hundreds of ready-to-use packages nicely
organised in configuration layers following a set of
[conventions][CONVENTIONS.org].
2014-11-22 21:53:38 +00:00
2015-09-23 03:26:12 +00:00
# Documentation
2022-06-04 18:49:24 +00:00
Comprehensive documentation is available for each layer by pressing < kbd > SPC h
SPC< / kbd > .
2014-11-22 21:53:38 +00:00
2022-06-04 18:49:24 +00:00
You can also check the [general documentation][DOCUMENTATION.org], [quick start
guide][QUICK_START.org] and the [FAQ][FAQ.org].
2014-12-05 07:40:32 +00:00
2015-09-23 03:26:12 +00:00
# Getting Help
2014-12-08 02:30:00 +00:00
If you need help, ask your question in the [Gitter Chat][] and a member of the
community will help you out.
2014-11-22 21:53:38 +00:00
2015-04-26 06:05:17 +00:00
If you prefer IRC, connect to the [Gitter Chat IRC server][] and join the
`#syl20bnr/spacemacs` channel.
2020-03-12 19:45:06 +00:00
Last but not least there are a lot of high class tutorials available on YouTube:
* Jack of Some's Spacemacs related channel [here ](https://www.youtube.com/watch?v=r-BHx7VNX5s&list=PLd_Oyt6lAQ8Rxb0HUnGbRrn6R4Cdt2yoI )
* GDQuest's Game Design oriented tutorials to Spacemacs [here ](https://www.youtube.com/watch?v=hCNOB5jjtmc&list=PLhqJJNjsQ7KFkMVBunWWzFD8SlH714qm4 )
* Practicalli's Clojure tutorials based on Spacemacs [here ](https://www.youtube.com/watch?v=ZKuQDrQLAnc&list=PLpr9V-R8ZxiCHMl2_dn1Fovcd34Oz45su )
* Eivind Fonn's classic Spacemacs ABC [here ](https://www.youtube.com/watch?v=ZFV5EqpZ6_s&list=PLrJ2YN5y27KLhd3yNs2dR8_inqtEiEweE )
2020-03-08 18:32:57 +00:00
2014-11-20 01:11:25 +00:00
# Prerequisites
2017-04-20 06:40:14 +00:00
Spacemacs is an extension of a popular text editor called Emacs. Thus you need
to first install base Emacs and then download the Spacemacs extension files with
Git.
2015-06-03 02:29:08 +00:00
## Emacs
2022-01-03 21:00:08 +00:00
Spacemacs requires Emacs 27.1 or above. The development version of Emacs is not
2017-04-22 16:35:00 +00:00
*officially* supported, but it should nevertheless be expected to work.
2013-11-23 05:46:33 +00:00
2014-11-25 04:04:43 +00:00
Some modes require third-party tools that you'll have to install via your
favorite package manager.
2015-06-03 02:29:08 +00:00
### Linux distros
2017-04-22 16:35:00 +00:00
Install the `emacs` package with your linux distributions package manager.
2015-06-03 02:29:08 +00:00
2017-04-22 16:35:00 +00:00
Do not install the `xemacs` package. It's not supported by Spacemacs. XEmacs is
2017-04-29 02:47:50 +00:00
an old fork of Emacs. The X in its name is unrelated to X11.
2015-06-03 02:29:08 +00:00
2017-04-22 16:35:00 +00:00
Emacs has graphical support.
2015-09-25 00:53:41 +00:00
2022-06-04 18:49:24 +00:00
**Note:** Some linux distributions support only Emacs versions older than 27.1.
In this case you should [build from source][build_source] instead.
2016-02-15 05:43:33 +00:00
2016-09-24 04:58:14 +00:00
### macOS
2018-05-14 22:17:10 +00:00
#### Install emacs
2018-05-21 15:44:41 +00:00
##### Using emacs-plus
2018-05-14 22:17:10 +00:00
2022-01-29 02:09:46 +00:00
```shell
2018-05-21 15:44:41 +00:00
brew tap d12frosted/emacs-plus
2022-01-29 02:09:46 +00:00
# to install Emacs 27
2020-06-07 08:31:08 +00:00
brew install emacs-plus@27 --with-spacemacs-icon
# or to install Emacs 28
brew install emacs-plus@28 --with-spacemacs-icon
2022-01-29 02:09:46 +00:00
2019-10-07 22:20:41 +00:00
brew link emacs-plus
2018-05-14 22:17:10 +00:00
```
##### Using emacs-mac
2022-01-29 02:09:46 +00:00
```shell
2018-05-14 22:17:10 +00:00
brew tap railwaycat/emacsmacport
brew install emacs-mac
2019-10-07 22:20:41 +00:00
brew link emacs-mac
2018-05-14 22:17:10 +00:00
```
2018-05-21 15:44:41 +00:00
##### Using cask
Homebrew now recommends to use the cask version with the following message:
"Please try the Cask for a better-supported Cocoa version". To install the cask
version:
2022-01-29 02:09:46 +00:00
```shell
2021-03-13 23:16:16 +00:00
brew install --cask emacs
```
2018-05-21 15:44:41 +00:00
This installs a pre-built package from https://emacsformacosx.com/
2018-05-17 21:47:02 +00:00
2018-05-14 22:17:10 +00:00
##### Other ways
2018-05-21 15:44:41 +00:00
If you're not comfortable with the ways mentioned above, then
2022-06-04 18:49:24 +00:00
[EmacsWiki][emacs-for-macos] lists down a few ways to install Emacs for macOS.
2018-05-14 22:17:10 +00:00
#### Install Source Code Pro font
2018-05-21 15:44:41 +00:00
Once Emacs is installed, run the following commands in the terminal to install
the default Source Code Pro font:
2017-04-22 16:35:00 +00:00
2022-01-29 02:09:46 +00:00
```shell
2019-10-11 19:17:10 +00:00
brew tap homebrew/cask-fonts
2021-03-29 21:47:05 +00:00
brew install --cask font-source-code-pro
```
2018-05-14 22:17:10 +00:00
#### Install Spacemacs
2022-01-29 02:09:46 +00:00
```shell
2017-04-29 02:47:50 +00:00
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
2014-12-08 00:53:59 +00:00
```
2017-04-29 02:47:50 +00:00
**Notes:**
2017-03-26 13:55:24 +00:00
2022-06-04 18:49:24 +00:00
It's also recommended to add the [osx layer][] to your [dotfile][] after
completing the Spacemacs [install process ](#install ). Instructions on how to do
so are available in the documentation for the [osx layer][].
Depending on the installed version of GnuTLS, securely installing emacs packages
may fail. In this case it is possible to install using `emacs --insecure` .
However, be aware that this means your packages will be transferred using http,
use at your own risk.
2019-08-08 04:39:33 +00:00
2022-06-04 18:49:24 +00:00
You may also have some issues when searching for your projects. It is
recommended to install the GNU [ripgrep][ripgrep-homebrew] through homebrew:
2018-12-04 23:09:22 +00:00
2022-01-29 02:09:46 +00:00
```shell
brew install ripgrep
2018-12-04 23:09:22 +00:00
```
2015-06-03 02:29:08 +00:00
### Windows
2022-06-04 18:49:24 +00:00
Download the official 64-bit (x86_64) stable builds from the [GNU
FTP][emacs-for-windows].
2015-06-03 02:29:08 +00:00
2022-06-04 18:49:24 +00:00
You'll also need `gzip` and put it in your path. Download it from the [GNUWin32
project page][gzip-for-windows]
2017-10-30 01:43:15 +00:00
2021-07-31 10:11:11 +00:00
#### Install Spacemacs in Windows
2022-06-04 18:49:24 +00:00
By default, Emacs looks for the `.emacs.d` directory in:
2021-07-31 10:11:11 +00:00
`C:\Users\<username>\AppData\Roaming`
2015-06-03 02:29:08 +00:00
2021-07-31 10:11:11 +00:00
* Clone Spacemacs to the Roaming directory:
2022-05-15 08:19:57 +00:00
* Windows Command Prompt:
2022-01-29 02:09:46 +00:00
```
2022-05-15 08:19:57 +00:00
git clone https://github.com/syl20bnr/spacemacs %appdata%/.emacs.d
2021-07-31 10:11:11 +00:00
```
2015-06-03 02:29:08 +00:00
2021-07-31 10:11:11 +00:00
* Windows PowerShell prompt:
2022-01-29 02:09:46 +00:00
```powershell
2022-05-15 08:19:57 +00:00
git clone https://github.com/syl20bnr/spacemacs $env:appdata/.emacs.d
2021-07-31 10:11:11 +00:00
```
2022-06-04 18:49:24 +00:00
* Or if a `HOME` environment variable has been configured that points to your
2021-07-31 10:11:11 +00:00
user directory: `C:\Users\<username>`
Clone Spacemacs to the `<username>` directory:
2022-05-15 08:19:57 +00:00
* Windows Command Prompt:
2022-01-29 02:09:46 +00:00
```
2022-05-15 08:19:57 +00:00
git clone https://github.com/syl20bnr/spacemacs %homepath%/.emacs.d
2021-07-31 10:11:11 +00:00
```
2015-06-03 02:29:08 +00:00
2021-07-31 10:11:11 +00:00
* Windows PowerShell prompt:
2022-01-29 02:09:46 +00:00
```powershell
2022-05-15 08:19:57 +00:00
git clone https://github.com/syl20bnr/spacemacs $home/.emacs.d
2021-07-31 10:11:11 +00:00
```
#### Notes
* If the following error occurs after starting Emacs:
```
The directory ~/.emacs.d/server is unsafe
```
2015-06-03 02:29:08 +00:00
2021-07-31 10:11:11 +00:00
Fix it by changing the owner of the directory `~/.emacs.d/server` :
2022-06-04 18:49:24 +00:00
- From Properties select the Tab “Security”,
- Select the button “Advanced”,
- Select the Tab “Owner”
- Change the owner to your account name
2015-06-03 02:29:08 +00:00
2021-07-31 10:11:11 +00:00
Source: [Stack Overflow][so-server-unsafe]
2022-06-04 18:49:24 +00:00
* For efficient searches, we recommend installing [ripgrep][ripgrep-github].
2015-06-03 02:29:08 +00:00
2022-06-04 18:49:24 +00:00
* Depending on the installed version of GnuTLS, securely installing emacs
packages may fail. In this case it is possible to install using `emacs
--insecure`. However be aware that this means your packages will be transferred
using http, use at your own risk.
2019-08-08 04:39:33 +00:00
2022-06-04 18:49:24 +00:00
* The period (dot) before a file or folder name means that it's a hidden file or
folder. To show hidden files and folders:
2021-07-31 10:11:11 +00:00
- Press the Windows key
2022-06-04 18:49:24 +00:00
- Type `File explorer options`
2021-07-31 10:11:11 +00:00
- Select the `View` tab at the top
- Check `Show hidden files, folders and drives`
- Click `OK`
2014-11-20 01:11:25 +00:00
# Install
2016-02-01 01:43:08 +00:00
## Default installation
2017-04-20 06:40:14 +00:00
1. If you have an existing Emacs configuration, back it up first by running the
following code in your terminal:
2014-09-07 03:28:55 +00:00
2022-01-29 02:09:46 +00:00
```shell
2014-12-06 01:35:39 +00:00
cd ~
2015-10-29 17:38:08 +00:00
mv .emacs.d .emacs.d.bak
mv .emacs .emacs.bak
2014-12-05 07:40:32 +00:00
```
2013-11-23 05:46:33 +00:00
2017-04-22 16:35:00 +00:00
Don't forget to backup and *remove* the `~/.emacs` file. Otherwise Spacemacs
2022-06-04 18:49:24 +00:00
**WILL NOT** be able to load. This is because that file will prevent Emacs
from loading the proper initialization file.
2015-11-13 10:25:06 +00:00
2017-04-20 06:40:14 +00:00
2. Clone the repository with [Git][]:
2014-10-29 14:46:50 +00:00
2022-06-04 18:49:24 +00:00
**Note: Windows users** , see [Windows section ](#install-spacemacs-in-windows ).
2021-07-31 10:11:11 +00:00
2022-01-29 02:09:46 +00:00
```shell
2015-11-07 22:46:47 +00:00
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
2014-12-05 07:40:32 +00:00
```
2014-10-18 01:35:43 +00:00
2022-01-29 02:09:46 +00:00
Or in case you have a limited internet connection or speed,
2019-10-07 22:20:41 +00:00
2022-01-29 02:09:46 +00:00
```shell
2019-08-29 11:32:58 +00:00
git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
2014-11-22 05:45:19 +00:00
2020-01-30 22:40:23 +00:00
3. (Optional) Install the default fonts
2017-04-20 06:40:14 +00:00
2022-06-04 18:49:24 +00:00
It's recommended to install [Source Code Pro][] by Adobe as the default font.
It ensures that, for example, the symbols on the mode-line (bottom bar) looks
correct. It's also recommended to use a "Fallback font". These depend on the
system:
2017-04-20 06:40:14 +00:00
2017-04-21 02:34:57 +00:00
- GNU/Linux: *NanumGothic* (package named *fonts-nanum* on Debian, for
example)
2017-04-20 06:40:14 +00:00
- macOS: *Arial Unicode MS*
- Windows: *MS Gothic* or *Lucida Sans Unicode*
2022-06-04 18:49:24 +00:00
If the mode-line doesn't look similar to the [picture at the top of this
page](#introduction), make sure you have the correct fallback font installed.
2017-04-22 16:35:00 +00:00
2022-06-04 18:49:24 +00:00
If you're running in a terminal, then you'll also need to change the
terminal's font settings.
2016-06-30 06:53:32 +00:00
2020-01-30 22:40:23 +00:00
4. Launch Emacs. Spacemacs will automatically install the packages it requires.
2022-06-04 18:49:24 +00:00
5. Once the packages are installed, answer the questions in the Dotfile wizard
installer. If you are new to Emacs and Spacemacs, then it's fine to just
accept the default choices. It's easy to try the other choices later, without
having to reinstall Spacemacs. They can be changed in the dotfile
`~/.spacemacs` .
2016-01-05 06:16:29 +00:00
2022-06-04 18:49:24 +00:00
6. After answering the questions, Spacemacs will download and install the
remaining packages it will require. When the all the packages have been
installed, restart Emacs to complete the installation.
2017-04-22 16:35:00 +00:00
2017-04-29 02:47:50 +00:00
**Notes:**
2020-01-28 07:29:33 +00:00
If you are behind a firewall or similar and you get an error regarding package
downloads then you may try to disable the HTTPS protocol by starting Emacs with
2022-01-29 02:09:46 +00:00
```shell
2017-04-29 02:47:50 +00:00
emacs --insecure
```
2020-01-28 07:29:33 +00:00
but this should be a last resort because of the security implications.
2017-04-18 05:03:05 +00:00
2022-06-04 18:49:24 +00:00
You can set the `dotspacemacs-elpa-https` variable to `nil` in your dotfile
`~/.spacemacs` but this has the same security implications as the insecure flag.
You may also want to clear out your `.emacs.d/elpa` directory before doing this,
so that any corrupted packages you may have downloaded will be re-installed.
2016-01-10 22:42:23 +00:00
2017-04-29 02:47:50 +00:00
`error: Package 'package-build-' is unavailable` may occur due to heavy network
taffic. You can fix it by setting the `dotspacemacs-elpa-timeout` variable to
`70` in your dotfile.
2017-04-18 05:03:05 +00:00
2017-04-29 02:47:50 +00:00
`Warning (bytecomp)` and other compilation warnings are perfectly normal. If
2017-04-29 05:44:55 +00:00
you're curious, you can find out why these occur [here][compilation-warnings].
2015-03-18 05:13:45 +00:00
2022-06-04 18:49:24 +00:00
If the mode-line turns red, then be sure to consult the [FAQ][FAQ.org].
2014-11-25 04:04:43 +00:00
2017-04-20 06:40:14 +00:00
## Alternative installations
2022-06-04 18:49:24 +00:00
Currently, there are two supported locations for you to place your Spacemacs
configuration files.
2016-06-23 04:25:04 +00:00
### Modify HOME environment variable
2017-04-22 16:35:00 +00:00
This solution is ideal for quickly trying Spacemacs without compromising your
existing configuration. Clone Spacemacs outside the Emacs dotdirectory
`~/.emacs.d` and modify the HOME environment variable.
2016-02-01 01:43:08 +00:00
2022-01-29 02:09:46 +00:00
```shell
2016-02-01 01:43:08 +00:00
mkdir ~/spacemacs
2016-06-21 20:40:10 +00:00
git clone https://github.com/syl20bnr/spacemacs.git ~/spacemacs/.emacs.d
2016-02-01 01:43:08 +00:00
HOME=~/spacemacs emacs
```
2022-01-29 02:09:46 +00:00
**Note**: If you're using the Fish shell, then you'll need to modify the last
2017-04-22 16:35:00 +00:00
command to: `env HOME=$HOME/spacemacs emacs`
2016-02-01 01:43:08 +00:00
2016-06-23 04:25:04 +00:00
### Modify spacemacs-start-directory variable
This solution is better suited to "embed" Spacemacs into your own configuration.
2017-04-22 16:35:00 +00:00
If you've cloned Spacemacs into `~/.emacs.d/spacemacs/` , then drop the following
lines in the `~/.emacs.d/init.el` file:
2016-06-23 04:25:04 +00:00
```elisp
(setq spacemacs-start-directory "~/.emacs.d/spacemacs/")
(load-file (concat spacemacs-start-directory "init.el"))
```
2015-03-22 00:05:35 +00:00
## Spacemacs logo
2022-06-04 18:49:24 +00:00
For Linux users, create `spacemacs.desktop` in `~/.local/share/applications/`
using [this .desktop file][spacemacs-desktop] as a reference. Change the `Name`
parameter to `Name=Spacemacs` and the `Icon` parameter to
`Icon=/PATH/TO/EMACSD/core/banners/img/spacemacs.png` where `PATH/TO/EMACSD` is
the path to your `.emacs.d` directory, usually `~/.emacs.d` or
`~/.config/emacs` .
2015-03-22 00:05:35 +00:00
2022-06-04 18:49:24 +00:00
For macOS users, you need to [download the .icns version of the
logo][icon-repository] and simply [change the logo on the
Dock][icon-mac-instructions].
2015-06-08 11:23:22 +00:00
2014-12-05 07:40:32 +00:00
# Update
2022-06-04 18:49:24 +00:00
Spacemacs supports two different update schemes, the default is a rolling update
scheme based on the latest version of packages available. This version can be
found on the `develop` branch and is updated by a simple git pull.
2022-01-03 21:00:08 +00:00
2022-06-04 18:49:24 +00:00
The second method is deprecated. It was a fixed version scheme which was based
on a stable set of packages. The latest fixed version can be found on the
`master` branch and would show a notification when a new version is available.
Be warned that this method has not been updated in a long time, so packages will
be very old.
2022-01-03 21:00:08 +00:00
## Rolling update (on develop)
1. Close Emacs and update the git repository:
2022-01-29 02:09:46 +00:00
```shell
git pull --rebase
```
2022-01-03 21:00:08 +00:00
2. Restart Emacs to complete the upgrade.
2015-09-23 03:26:12 +00:00
2022-06-04 18:49:24 +00:00
## Deprecated automatic update (on master branch)
When a new version is available, a little arrow will appear in the mode-line.
2015-09-23 03:26:12 +00:00
2022-06-04 18:49:24 +00:00
Its color depends on the number of versions that have been released since the
2017-04-22 16:35:00 +00:00
last update. Green means that you have a recent version, orange and red means
that you have an older version.
2015-09-23 03:26:12 +00:00
2015-10-02 17:35:43 +00:00
![powerline_update ](doc/img/powerline-update.png )
2015-09-23 03:26:12 +00:00
2017-04-22 16:35:00 +00:00
Click on the arrow to update Spacemacs to the latest version.
2015-09-23 03:26:12 +00:00
2015-12-01 05:49:31 +00:00
## Manual update (on master branch)
2017-04-22 16:35:00 +00:00
Remove the `<` and `>` angle brackets when you're typing the lines below into
2022-06-04 18:49:24 +00:00
your shell. Make sure to also replace the text: "tag version which you are
updating to" with a tagged version. This page lists the [latest tags][]
2015-12-01 05:49:31 +00:00
2022-01-29 02:09:46 +00:00
```shell
2015-12-01 03:27:50 +00:00
git fetch
2016-02-15 06:29:59 +00:00
git reset --hard < tag version which you are updating to >
2015-12-01 03:27:50 +00:00
```
2022-01-03 21:00:08 +00:00
## Revert to a specific version (on master branch)
2017-04-22 16:35:00 +00:00
To revert to a specific version, just checkout the corresponding branch. For
2022-06-04 18:49:24 +00:00
instance, the following command reverts Spacemacs to version `0.200` :
2015-09-28 04:26:42 +00:00
2022-01-29 02:09:46 +00:00
```shell
git checkout origin/release-0.200
```
2015-09-28 04:26:42 +00:00
2022-06-04 18:49:24 +00:00
**After updating Spacemacs (either manually or automatically), you should also
check if any updates are available for your packages. On the Spacemacs Home
Buffer < kbd > SPC b h< / kbd > , click (press < kbd > RET< / kbd > ) on the `[Update
Packages]` button, or use the convenient keybinding < kbd > SPC f e U< / kbd > **
2016-01-04 11:41:13 +00:00
2016-01-11 05:38:58 +00:00
# Quotes
[Quote][quote01] by [ashnur ](https://github.com/ashnur ):
2016-01-07 13:21:21 +00:00
2017-04-21 02:34:57 +00:00
«I feel that spacemacs is an aircraft carrier and I am playing table tennis
on the deck as a freerider.»
2016-01-07 13:21:21 +00:00
2016-06-20 19:58:36 +00:00
[Quote][quote02] by [deuill ](https://github.com/deuill ):
«I LOVE SPACEMACS AND MAGIT
That is all»
2014-11-24 03:55:35 +00:00
# Contributions
2017-04-22 16:35:00 +00:00
Spacemacs is a community-driven project, it needs _you_ to keep it up to date
and to propose great and useful configurations for all the things!
2014-11-24 03:55:35 +00:00
2022-06-04 18:49:24 +00:00
Before contributing, be sure to consult the [contribution
guidelines][CONTRIBUTING.org] and [conventions][CONVENTIONS.org].
2014-11-24 03:55:35 +00:00
2015-12-01 13:26:32 +00:00
# Communities
- [Gitter Chat]
- [Stack Exchange]
- [Reddit]
2019-06-22 18:06:17 +00:00
# Spacemacs Everywhere
2022-06-04 18:49:24 +00:00
Once you've learned the Spacemacs key bindings, you can use them in other
IDEs/tools, thanks to the following projects:
- [Intellimacs ](https://github.com/MarcoIeni/intellimacs ) - Spacemacs' like key
bindings for IntelliJ platform
- [Spaceclipse ](https://github.com/MarcoIeni/spaceclipse ) - Spacemacs’ like key
bindings for Eclipse
- [SpaceVim ](https://github.com/SpaceVim/SpaceVim ) - A community-driven modular
vim distribution
- [VSpaceCode ](https://github.com/VSpaceCode/VSpaceCode ) - Spacemacs’ like key
bindings for Visual Studio Code
2019-06-22 18:06:17 +00:00
2015-04-08 02:51:21 +00:00
# License
2015-10-12 23:12:09 +00:00
The license is GPLv3 for all parts specific to Spacemacs, this includes:
2015-04-08 02:51:21 +00:00
- the initialization and core files
2016-01-01 23:22:05 +00:00
- all the layer files
2015-04-08 02:51:21 +00:00
- the documentation
2017-04-07 03:07:29 +00:00
For the packages shipped in this repository, you can refer to the files header.
2015-03-13 03:23:10 +00:00
2022-06-04 18:49:24 +00:00
[Spacemacs logo][] by [Nasser Alshammari][] released under a [Creative Commons
Attribution-ShareAlike 4.0 International
License.][creativecommons-4]
2015-03-13 03:23:10 +00:00
2015-04-08 02:00:10 +00:00
# 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.
2016-10-19 02:48:35 +00:00
You can show your love for the project by getting cool Spacemacs t-shirts, mugs
and more in the [Spacemacs Shop][].
2017-04-22 16:35:00 +00:00
If you want to show your support financially, then you can contribute to
2022-06-04 18:49:24 +00:00
[Bountysource][], or buy a drink for the maintainer by clicking on the [Paypal
badge](#top).
2015-04-08 02:00:10 +00:00
2017-04-22 16:35:00 +00:00
If you used spacemacs in a project, and you want to show that fact, you can use
2022-06-04 18:49:24 +00:00
the spacemacs badge: [![Built with
Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg)](https://develop.spacemacs.org)
2015-11-12 12:12:27 +00:00
- For Markdown:
2020-08-29 09:59:30 +00:00
```markdown
2021-08-23 21:02:26 +00:00
[![Built with Spacemacs ](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg )](https://develop.spacemacs.org)
2015-11-12 12:12:27 +00:00
```
- For HTML:
2020-08-29 09:59:30 +00:00
```html
2021-08-23 21:02:26 +00:00
< a href = "https://develop.spacemacs.org" > < img alt = "Built with Spacemacs" src = "https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg" / > < / a >
2015-11-12 12:12:27 +00:00
```
- For Org-mode:
2020-08-29 09:59:30 +00:00
```org
2021-08-23 21:02:26 +00:00
[[https://develop.spacemacs.org][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
2015-11-12 12:12:27 +00:00
```
Thank you!
2015-04-08 02:00:10 +00:00
2021-03-26 17:15:06 +00:00
[Twitter]: https://i.imgur.com/tXSoThF.png
Refactor CONTRIBUTING documentations
This commit merge the `CONTRIBUTING.md` and `doc/CONTRIBUTE.org` file
into a new `CONTRIBUTING.org` file. It also refactors the content to be
more organized and make its navigation more goal-oriented.
Github displays a link to the `CONTRIBUTING.*` file when people are
opening new issues or proposing new PRs. This file is important because
it is the entry-point to contributions guidelines for most of the users.
The current setup is non-optimal, even broken, as it adds a level of
indirection, and points to a contributing file that has broken
links (due to the new documentation format). The possible drawback of
the proposed solution is that I'm not sure if it is possible to include
it into the new online documentation as it is not in `doc/` folder.
The other possibility is to keep a small `CONTRIBUTING.md` file, as it
is now, pointing to the new documentation system (once online), but I'm
preferring the proposed solution for the following reasons:
- People that are willing to contribute will probably open Github
first (for forking, creating PR, etc), not the online documentation.
- It has one level of indirection less when people click on the
guidelines guide from a new issue/PR.
- `CONTRIBUTING.*` is by convention a special kind of file on github, so
it's valid reason to break the rule and not having it in the `doc/`
folder.
2015-11-22 13:11:08 +00:00
[CONTRIBUTING.org]: CONTRIBUTING.org
2021-08-23 21:02:26 +00:00
[CONVENTIONS.org]: https://develop.spacemacs.org/doc/CONVENTIONS
[DOCUMENTATION.org]: https://develop.spacemacs.org/doc/DOCUMENTATION
[QUICK_START.org]: https://develop.spacemacs.org/doc/QUICK_START
[FAQ.org]: https://develop.spacemacs.org/doc/FAQ
[VIMUSERS.org]: https://develop.spacemacs.org/doc/VIMUSERS
[dotfile]: https://develop.spacemacs.org/doc/DOCUMENTATION#dotfile-configuration
[osx layer]: https://develop.spacemacs.org/layers/+os/osx/README.html
2014-11-22 21:53:38 +00:00
[Gitter Chat]: https://gitter.im/syl20bnr/spacemacs
2015-04-26 06:05:17 +00:00
[Gitter Chat IRC server]: https://irc.gitter.im/
2021-03-26 17:15:06 +00:00
[Homebrew]: https://brew.sh
2017-04-22 16:35:00 +00:00
[emacs-plus]: https://github.com/d12frosted/homebrew-emacs-plus
2022-06-04 18:49:24 +00:00
[emacs-for-macos]: https://www.emacswiki.org/emacs/EmacsForMacOS#toc12
2021-08-23 21:02:26 +00:00
[powerline documentation]: https://develop.spacemacs.org/doc/DOCUMENTATION.html#powerline-separators
2020-01-07 03:33:13 +00:00
[emacs-for-windows]: https://ftp.gnu.org/gnu/emacs/windows/
2021-04-08 14:33:33 +00:00
[gzip-for-windows]: http://gnuwin32.sourceforge.net/packages/gzip.htm
2022-06-04 18:49:24 +00:00
[ripgrep-github]: https://github.com/BurntSushi/ripgrep
2021-03-26 17:15:06 +00:00
[so-server-unsafe]: https://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start
2015-03-13 03:23:10 +00:00
[Spacemacs logo]: https://github.com/nashamri/spacemacs-logo
[Nasser Alshammari]: https://github.com/nashamri
2017-04-22 16:35:00 +00:00
[compilation-warnings]: https://github.com/quelpa/quelpa/issues/90#issuecomment-137982713
2015-03-22 00:05:35 +00:00
[cpaulik-unity-icon]: http://splendidabacus.com/posts/2015/03/spacemacs-unity-icon/
2021-03-26 17:15:06 +00:00
[icon-mac-instructions]: https://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/
2017-04-22 16:35:00 +00:00
[latest tags]: https://github.com/syl20bnr/spacemacs/tags
2015-09-23 03:26:12 +00:00
[icon-repository]: https://github.com/nashamri/spacemacs-logo
2021-03-26 17:15:06 +00:00
[Stack Exchange]: https://emacs.stackexchange.com/questions/tagged/spacemacs
2015-12-01 13:26:32 +00:00
[Reddit]: https://www.reddit.com/r/spacemacs
2016-01-11 05:38:58 +00:00
[quote01]: https://gitter.im/syl20bnr/spacemacs?at=568e627a0cdaaa62045a7df6
2016-06-20 19:58:36 +00:00
[quote02]: https://gitter.im/syl20bnr/spacemacs?at=5768456c6577f032450cfedb
2016-03-20 01:52:50 +00:00
[build_source]: https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html
2016-01-11 21:37:45 +00:00
[Bountysource]: https://salt.bountysource.com/teams/spacemacs
2016-07-04 01:56:39 +00:00
[Source Code Pro]: https://github.com/adobe-fonts/source-code-pro
2016-10-19 02:48:35 +00:00
[Spacemacs Shop]: https://shop.spreadshirt.com/spacemacs-shop
2017-04-20 06:40:14 +00:00
[Git]: https://git-scm.com/downloads
2022-06-04 18:49:24 +00:00
[spacemacs-desktop]: https://github.com/emacs-mirror/emacs/blob/master/etc/emacs.desktop
[creativecommons-4]: https://creativecommons.org/licenses/by-sa/4.0/
[ripgrep-homebrew]: https://formulae.brew.sh/formula/ripgrep