TakeV
/
spacemacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

README: rewrite (#15660) 

rewrite
This commit is contained in:
Lucius Hu 2022-07-25 04:25:05 -04:00 committed by GitHub
parent 03ccb174db
commit 45bf3825dd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 405 additions and 338 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

743
README.md
View File

@ -1,10 +1,12 @@
<a name="top" id="fork-destination-box"></a>
<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>
- - -
<a href="https://develop.spacemacs.org"><img src="assets/spacemacs-badge.svg" alt="Made with Spacemacs" height="20"></a>
<a href="https://www.gnu.org/licenses/gpl-3.0.en.html"><img src="assets/gplv3.png" alt="GPLv3 Software" align="right" height="20"></a>
<a href="https://www.twitter.com/spacemacs"><img src="https://i.imgur.com/tXSoThF.png" alt="Twitter" align="right" height="20"></a>
<!-- logo and links -->
<p align="center"><img src="/doc/img/title2.png" alt="Spacemacs"/></p>
<p align="center">
<span align="center">
<p><img src="doc/img/title2.png" alt="Spacemacs"/></p>
<p>
<b><a href="https://develop.spacemacs.org/doc/DOCUMENTATION#core-pillars">philosophy</a></b>
|
<b><a href="https://develop.spacemacs.org/doc/DOCUMENTATION#who-can-benefit-from-this">for whom?</a></b>
@ -20,80 +22,45 @@
<b><a href="https://develop.spacemacs.org/doc/FAQ">FAQ</a></b>
</p>
- - -
<p align="center">
<!-- badges -->
<p>
<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>
<a href="https://discord.gg/p4MddFu6Ag"><img src="https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt="Discord"></a>
<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>
<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" alt="elisp state"></a>
<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>
<a href="https://shop.spreadshirt.com/spacemacs-shop"><img src="https://img.shields.io/badge/Shop-T--Shirts-blue.svg" alt="Donate"></a>
<a href="https://shop.spreadshirt.com/spacemacs-shop"><img src="https://img.shields.io/badge/Shop-T--Shirts-blue.svg" alt="Merchandise"></a>
<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>
</p>
</span>
- - -
**Quick Start**
**Quick Install**
If you *don't* have an existing Emacs setup and want to run Spacemacs as your
configuration, and if you have all [prerequisites](#prerequisites) installed,
you can install Spacemacs with one line:
This assumes you don't have an existing Emacs setup and want to run Spacemacs as
your config. If you do have one, look at the [full installation
instructions](#install) for other options.
```shell
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
* Windows Command Prompt:
```
git clone https://github.com/syl20bnr/spacemacs %appdata%/.emacs.d
* shell:
```sh
git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
```
* Windows PowerShell:
```powershell
git clone https://github.com/syl20bnr/spacemacs $env:appdata/.emacs.d
git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
```
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
If `HOME` is not set in environment or in registry:
- [Introduction](#introduction)
- [Features](#features)
- [Documentation](#documentation)
- [Getting Help](#getting-help)
- [Prerequisites](#prerequisites)
- [Emacs](#emacs)
- [Linux distros](#linux-distros)
- [macOS](#macos)
- [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)
- [Windows](#windows)
- [Install Spacemacs in Windows](#install-spacemacs-in-windows)
- [Notes](#notes)
- [Install](#install)
- [Default installation](#default-installation)
- [Alternative installations](#alternative-installations)
- [Modify HOME environment variable](#modify-home-environment-variable)
- [Modify spacemacs-start-directory variable](#modify-spacemacs-start-directory-variable)
- [Spacemacs logo](#spacemacs-logo)
- [Update](#update)
- [Rolling update (on develop)](#rolling-update-on-develop)
- [Automatic update (on master branch)](#automatic-update-on-master-branch)
- [Manual update (on master branch)](#manual-update-on-master-branch)
- [Revert to a specific version (on master branch)](#revert-to-a-specific-version-on-master-branch)
- [Quotes](#quotes)
- [Contributions](#contributions)
- [Communities](#communities)
- [Spacemacs Everywhere](#spacemacs-everywhere)
- [License](#license)
- [Supporting Spacemacs](#supporting-spacemacs)
```powershell
git clone https://github.com/syl20bnr/spacemacs $env:APPDATA/.emacs.d
```
<!-- markdown-toc end -->
If you do have an existing Emacs configuration, look at the [full installation
instructions](#install) for other options.
# Introduction
Spacemacs is a new way of experiencing Emacs -- it's a sophisticated and
@ -122,167 +89,372 @@ mode-line.
<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
organized in configuration layers following a set of
[conventions][CONVENTIONS.org].
organized 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].
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
If you need help, ask your questions 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.
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)
* Jack of Some's [Spacemacs tutorial videos][jack-of-some].
* GDQuest's [Game Design oriented tutorials ][gdquest] to Spacemacs.
* Practicalli's [Clojure tutorials based on Spacemacs][practicalli].
* Eivind Fonn's classic [Spacemacs ABC][eivind-fonn].
# Prerequisites
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.
## Emacs
Spacemacs requires Emacs 27.1 or above. The development version of Emacs is not
*officially* supported, but it should nevertheless be expected to work.
1. A package manager if the OS doesn't have one already.
Some modes require third-party tools that you'll have to install via your
favorite package manager.
2. Spacemacs is an extension of a popular text editor called [Emacs][GNU Emacs].
So you'll need Emacs installed first.
### Linux distros
Install the `emacs` package with your linux distributions package manager.
Spacemacs requires Emacs 27.1 or above. The development version of Emacs is
not *officially* supported, but it should nevertheless be expected to work.
Do not install the `xemacs` package. It's not supported by Spacemacs. XEmacs is
an old fork of Emacs. The X in its name is unrelated to X11.
3. [git][Git] is required to download and update Spacemacs.
Emacs has graphical support.
4. Tar, either [GNU Tar][] or [BSD Tar][], is required to install and update
Emacs packages used by Spacemacs.
**Note:** Some linux distributions support only Emacs versions older than 27.1.
In this case you should [build from source][build_source] instead.
5. *(Optional)* The default font used by Spacemacs is [Source Code Pro][]. You
may customize your own font settings and choose another font. If you want to
use this default font, it must be installed.
Spacemacs also uses fallback fonts to ensure certain Unicode symbols it uses
symbols appear correctly. The fonts used are determined by the OS:
- Linux: [Nanum Gothic][]
- macOS: [Arial Unicode MS][]
- Windows: [MS Gothic][] and [Lucida Sans Unicode][]
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.
6. *(Optional)* Various commands in Spacemacs needs one of the following line
searching program:
- [ripgrep (rg)][ripgrep]
- [The silver searcher (ag)][ag]
- [The platinum searcher (pt)][pt]
- [ack][]
- [GNU Grep][] or [BSD Grep][]
Grep is very slow but it's widely available on most systems and is used as an
fallback option.
We strongly recommend [ripgrep][] over other line searching programs, for its
blazing fast speed. The following subsections helps you to install it.
### Linux
1. Most Linux distribution ships a package manager already and if this is the
case you are all set for this step.
If it doesn't, you may need to build the softwares mentioned below from their
sources.
2. In most distributions, Emacs is installed via an `emacs` package from the
package manager.
**N.B.** DO not install [XEmacs][] because it's not supported by Spacemacs.
XEmacs is an old fork of Emacs with various [subtle
differences][Emacs And XEmacs].
**N.B.** Some Linux distributions support only Emacs versions older than
27.1. In this case you should
[build it from source][Build Emacs from Source] instead.
3. Very likely Git is already installed on your system. Otherwise, you should
be able to install `git` from your system's package manager.
4. Very likely Tar is already installed on your system. Otherwise, you should
be able to install `tar` from your system's package manager.
5. *(Optional)* If Nerd Fonts and Nanum Gothic are available from your
distribution's package manager, you should install it there.
Otherwise, the generic way to install it is:
1. Download the latest pre-built `TTF` font from
<https://github.com/adobe-fonts/source-code-pro/releases/latest> and
<https://fonts.google.com/specimen/Nanum+Gothic>.
2. Extract the archive and move the font files to `~/.fonts`.
3. Refresh font cache with:
```sh
fc-cache -fv
```
6. *(Optional)* If your distribution is listed [here][ripgrep-installation],
follow the instructions. Otherwise, you can download its pre-built binary or
build it from source.
### macOS
#### Install emacs
1. The most popular package manager on macOS is [Homebrew][], to install it:
##### Using emacs-plus
```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
```shell
brew tap d12frosted/emacs-plus
2. Several options exist for installing Emacs on macOS:
# to install Emacs 27
brew install emacs-plus@27 --with-spacemacs-icon
# or to install Emacs 28
brew install emacs-plus@28 --with-spacemacs-icon
1. [Emacs Plus][] features [additional functionalities][Emacs Plus features]
over base Emacs.
brew link emacs-plus
```
```sh
brew tap d12frosted/emacs-plus
##### Using emacs-mac
# install latest stable release, with Spacemacs icon and native compilation
brew install emacs-plus --with-spacemacs-icon --with-native-comp
```
```shell
brew tap railwaycat/emacsmacport
brew install emacs-mac
brew link emacs-mac
```
2. [Emacs Mac Port][] adds native GUI support to Emacs 28. And the full list
of features is available [here][Emacs Mac Port features].
##### Using cask
```sh
brew tap railwaycat/emacsmacport
brew install emacs-mac
```
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:
3. [Emacs for Mac OS X][] is the binary build of GNU Emacs, *without* any
extra feature.
```shell
brew install --cask emacs
```
```sh
brew install --cask emacs
```
This installs a pre-built package from https://emacsformacosx.com/
3. To install `git`:
##### Other ways
```sh
brew install git
```
If you're not comfortable with the ways mentioned above, then
[EmacsWiki][emacs-for-macos] lists down a few ways to install Emacs for macOS.
4. macOS ships with [BSD Tar][] so you don't need to install it.
#### Install Source Code Pro font
5. *(Optional)* To install Source Code Pro Font:
Once Emacs is installed, run the following commands in the terminal to install
the default Source Code Pro font:
```sh
brew tap homebrew/cask-fonts
brew install --cask font-source-code-pro
```
```shell
brew tap homebrew/cask-fonts
brew install --cask font-source-code-pro
```
Arial Unicode MS is shipped with macOS v10.5 and later so you don't need to
install it manually.
#### Install Spacemacs
6. *(Optional)* You can install `ripgrep` via `Homebrew`:
```shell
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
**Notes:**
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.
You may also have some issues when searching for your projects. It is
recommended to install the GNU [ripgrep][ripgrep-homebrew] through homebrew:
```shell
brew install ripgrep
```
```sh
brew install ripgrep
```
### Windows
Download the official 64-bit (x86_64) stable builds from the [GNU
FTP][emacs-for-windows].
You'll also need `gzip` and put it in your path. Download it from the [GNUWin32
project page][gzip-for-windows]
1. We recommend [Scoop][] as the package manager for Windows users. You can
install it via PowerShell:
#### Install Spacemacs in Windows
By default, Emacs looks for the `.emacs.d` directory in:
`C:\Users\<username>\AppData\Roaming`
```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # Optional: Needed to run a remote script the first time
irm get.scoop.sh | iex
```
* Clone Spacemacs to the Roaming directory:
* Windows Command Prompt:
```
git clone https://github.com/syl20bnr/spacemacs %appdata%/.emacs.d
```
2. Emacs can be installed in PowerShell:
```powershell
scoop bucket add extras
scoop install emacs
```
3. To install `git` in PowerShell:
```powershell
scoop bucket add main
scoop install git
```
4. Windows 10 build 17063 and later ships with [BSD Tar][] and you won't need to
install it manually.
If you're running an earlier version of Windows, Tar can be installed in
PowerShell:
```powershell
scoop bucket add main
scoop install tar
```
5. To install Source Code Pro Font in PowerShell:
```powershell
scoop bucket add KnotUntied_scoop-fonts https://github.com/KnotUntied/scoop-fonts
scoop install sourcecodepro
```
MS Gothic and Lucida Sans Unicode are shipped with Windows 2003 and later so
you don't need to install it manually.
6. *(Optional)* You can install `ripgrep` in PowerShell:
```powershell
scoop bucket add main
scoop install ripgrep
```
# Install
## Default Install
1. The default installation downloads Spacemacs to the `.emacs.d` directory in
your `HOME` directory.
But in the case of Windows, `HOME` is not set out-of-box. We recommend you to
set it as an environment variable, with the same value as environment
variable `HOMEPATH`, which usually looks like `C:\Users\<username>`.
2. Since Spacemacs will now be downloaded at `$HOME/.emacs.d`, if it already
exists it'll be overridden.
Also, if you have either `$HOME/.emacs.el` or `$HOME/.emacs`, they will
appear before Spacemacs in Emacs's initialization steps. Thus they must be
renamed in order for Spacemacs to load correctly.
To backup/rename the aforementioned files/directory, in shell:
```sh
[ -d $HOME/.emacs.d ] && mv $HOME/.emacs.d $HOME/.emacs.d.bak
[ -f $HOME/.emacs.el ] && mv $HOME/.emacs.el .emacs.el.bak
[ -f $HOME/.emacs ] && mv $HOME/.emacs $HOME/.emacs.bak
```
or in PowerShell:
* Windows PowerShell prompt:
```powershell
git clone https://github.com/syl20bnr/spacemacs $env:appdata/.emacs.d
if( TestPath -Path $HOME/.emacs.d )
{
Rename-Item $HOME/.emacs.d $HOME/.emacs.d.bak
}
if( TestPath -Path $HOME/.emacs.el )
{
Rename-Item $HOME/.emacs.el $HOME/.emacs.el.bak
}
if( TestPath -Path $HOME/.emacs )
{
Rename-Item $HOME/.emacs $HOME/.emacs.bak
}
```
* Or if a `HOME` environment variable has been configured that points to your
user directory: `C:\Users\<username>`
3. Now clone this repository with Git. The following work for both shell
and PowerShell:
Clone Spacemacs to the `<username>` directory:
* Windows Command Prompt:
```
git clone https://github.com/syl20bnr/spacemacs %homepath%/.emacs.d
```
```sh
git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
```
* Windows PowerShell prompt:
```powershell
git clone https://github.com/syl20bnr/spacemacs $home/.emacs.d
```
In case you have a limited internet connection or limited speed:
#### Notes
```sh
git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
* If the following error occurs after starting Emacs:
4. Now you can launch Emacs and Spacemacs will be loaded.
## Alternative Install Location
To install Spacemacs in a different location, we first need to introduce how
Spacemacs is loaded:
When Emacs is started, it looks for the init file
[in a deterministic way][Emacs: Find Init]. The
[default installation](#default-install) exploits it by occupying
`$HOME/.emacs.d/init.el` and let Emacs use it as its init file.
In other word, in default installation, Emacs find and load
`$HOME/.emacs.d/init.el`, which is then responsible to load other files in
`$HOME/.emacs.d`.
If you want to install Spacemacs to a different location, you need to make
sure it's loaded by Emacs in one of its [init file][Emacs: Find Init].
For example, if you've cloned Spacemacs to `$HOME/spacemacs`, and if you use
`$HOME/.emacs.el` as Emacs init file, then the following lines in
`$HOME/.emacs.el`:
```elisp
;; set variable `spacemacs-start-directory' to point to your Spacemacs
;; installation location, "~" is equivalent to "$HOME"
(setq spacemacs-start-directory "~/.emacs.d/spacemacs")
;; load Spacemacs's initialization file
(load-file (expand-file-name "init.el" spacemacs-start-directory))
```
# First Launch and Configuration
1. After cloning Spacemacs, the first time when you launch Emacs, Spacemacs will
automatically install the essential packages it requires. This step is the
bootstrap.
2. Once the bootstrap packages are installed, Spacemacs checks whether you have
an customization file `$HOME/.spacemacs`, known as `dotspacemacs`:
- If it already exists, Spacemacs loads it as the configuration.
- Otherwise, you need to answer a few questions and Spacemacs will generate
the `dotspacemacs` file for you.
If you are new to Emacs and/or Spacemacs, it's fine to just accept the
default choices. They can be changed in the `dotspacemacs` file later.
3. Spacemacs will download and install remaining packages it will require,
according to your `dotspacemacs`. When the all the packages have been
installed, restart Emacs to complete the installation.
4. `dotspacemacs` is the configuration file for Spacemacs, it's self
explanatory and is written in Emacs Lisp. Read
[general documentation][DOCUMENTATION.org] and
[quick start guide][QUICK_START.org] for more information.
5. In case you want to store your `dotspacemacs` at another location, say
under `$HOME/.spacemacs.d`:
- First set the environment variable `SPACEMACSDIR` to `$HOME/.spacemacs.d`.
- Move `$HOME/.spacemacs` to `$HOME/.spacemacs.d/init.el`.
In other word, set `SPACEMACSDIR` to the parent directory of your
`dotspacemacs`, and move `dotspacemacs` to the said directory.
## Spacemacs logo
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, by default `~/.emacs.d`.
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].
## Notes
- Depending on the installed version of GnuTLS, securely installing Emacs
packages may fail. It may also fail if you have a bad internet environment.
In either case it is possible to install packages using `emacs --insecure`.
However be aware that this means your packages will be transferred using HTTP,
use at your own risk.
- (*Windows)* If the following error occurs after starting Emacs:
```
The directory ~/.emacs.d/server is unsafe
@ -296,146 +468,19 @@ user directory: `C:\Users\<username>`
Source: [Stack Overflow][so-server-unsafe]
* For efficient searches, we recommend installing [ripgrep][ripgrep-github].
* 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.
* The period (dot) before a file or folder name means that it's a hidden file or
folder. To show hidden files and folders:
- (*Windows*) The period (dot) before a file or folder name means that it's a
hidden file or folder. To show hidden files and folders:
- Press the Windows key
- Type `File explorer options`
- Select the `View` tab at the top
- Check `Show hidden files, folders and drives`
- Click `OK`
# Install
## Default installation
1. If you have an existing Emacs configuration, back it up first by running the
following code in your terminal:
```shell
cd ~
mv .emacs.d .emacs.d.bak
mv .emacs .emacs.bak
```
Don't forget to backup and *remove* the `~/.emacs` file. Otherwise Spacemacs
**WILL NOT** be able to load. This is because that file will prevent Emacs
from loading the proper initialization file.
2. Clone the repository with [Git][]:
**Note: Windows users**, see [Windows section](#install-spacemacs-in-windows).
```shell
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
Or in case you have a limited internet connection or speed,
```shell
git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
3. (Optional) Install the default fonts
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:
- GNU/Linux: *NanumGothic* (package named *fonts-nanum* on Debian, for
example)
- macOS: *Arial Unicode MS*
- Windows: *MS Gothic* or *Lucida Sans Unicode*
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.
If you're running in a terminal, then you'll also need to change the
terminal's font settings.
4. Launch Emacs. Spacemacs will automatically install the packages it requires.
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`.
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.
**Notes:**
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
```shell
emacs --insecure
```
but this should be a last resort because of the security implications.
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.
`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.
`Warning (bytecomp)` and other compilation warnings are perfectly normal. If
you're curious, you can find out why these occur [here][compilation-warnings].
If the mode-line turns red, then be sure to consult the [FAQ][FAQ.org].
## Alternative installations
Currently, there are two supported locations for you to place your Spacemacs
configuration files.
### Modify HOME environment variable
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.
```shell
mkdir ~/spacemacs
git clone https://github.com/syl20bnr/spacemacs.git ~/spacemacs/.emacs.d
HOME=~/spacemacs emacs
```
**Note**: If you're using the Fish shell, then you'll 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.
If you've cloned Spacemacs into `~/.emacs.d/spacemacs/`, then drop the following
lines in the `~/.emacs.d/init.el` file:
```elisp
(setq spacemacs-start-directory "~/.emacs.d/spacemacs/")
(load-file (concat spacemacs-start-directory "init.el"))
```
## Spacemacs logo
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`.
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].
# Update
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.
found on the `develop` branch and is updated by a simple `git pull`.
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
@ -446,7 +491,7 @@ be very old.
## Rolling update (on develop)
1. Close Emacs and update the git repository:
```shell
```sh
git pull --rebase
```
@ -468,16 +513,16 @@ Remove the `<` and `>` angle brackets when you're typing the lines below into
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][]
```shell
```sh
git fetch
git reset --hard <tag version which you are updating to>
```
## Revert to a specific version (on master branch)
To revert to a specific version, just checkout the corresponding branch. For
instance, the following command reverts Spacemacs to version `0.200`:
## Revert to a specific release version (on master branch)
To revert to a specific release version, just checkout the corresponding branch.
For instance, the following command reverts Spacemacs to version `0.200`:
```shell
```sh
git checkout origin/release-0.200
```
@ -506,9 +551,9 @@ Before contributing, be sure to consult the [contribution
guidelines][CONTRIBUTING.org] and [conventions][CONVENTIONS.org].
# Communities
- [Gitter Chat]
- [Stack Exchange]
- [Reddit]
- [Gitter Chat][]
- [Stack Exchange][]
- [Reddit][]
# Spacemacs Everywhere
@ -546,8 +591,8 @@ If you want to show your support financially, then 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: [![Built with
If you used Spacemacs in a project, and you want to show that fact, you can use
the Spacemacs badge: [![Built with
Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg)](https://develop.spacemacs.org)
- For Markdown:
@ -570,41 +615,63 @@ Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c208270
Thank you!
[Twitter]: https://i.imgur.com/tXSoThF.png
[CONTRIBUTING.org]: CONTRIBUTING.org
[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
[CONVENTIONS.org]: doc/CONVENTIONS.org
[DOCUMENTATION.org]: doc/DOCUMENTATION.org
[FAQ.org]: doc/FAQ.org
[QUICK_START.org]: doc/QUICK_START.org
[Gitter Chat]: https://gitter.im/syl20bnr/spacemacs
[Gitter Chat IRC server]: https://irc.gitter.im/
[Homebrew]: https://brew.sh
[emacs-plus]: https://github.com/d12frosted/homebrew-emacs-plus
[emacs-for-macos]: https://www.emacswiki.org/emacs/EmacsForMacOS#toc12
[powerline documentation]: https://develop.spacemacs.org/doc/DOCUMENTATION.html#powerline-separators
[emacs-for-windows]: https://ftp.gnu.org/gnu/emacs/windows/
[gzip-for-windows]: http://gnuwin32.sourceforge.net/packages/gzip.htm
[ripgrep-github]: https://github.com/BurntSushi/ripgrep
[so-server-unsafe]: https://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start
[Spacemacs logo]: https://github.com/nashamri/spacemacs-logo
[Nasser Alshammari]: https://github.com/nashamri
[compilation-warnings]: https://github.com/quelpa/quelpa/issues/90#issuecomment-137982713
[cpaulik-unity-icon]: http://splendidabacus.com/posts/2015/03/spacemacs-unity-icon/
[icon-mac-instructions]: https://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/
[latest tags]: https://github.com/syl20bnr/spacemacs/tags
[icon-repository]: https://github.com/nashamri/spacemacs-logo
[Stack Exchange]: https://emacs.stackexchange.com/questions/tagged/spacemacs
[Reddit]: https://www.reddit.com/r/spacemacs
[jack-of-some]: https://www.youtube.com/watch?v=r-BHx7VNX5s&list=PLd_Oyt6lAQ8Rxb0HUnGbRrn6R4Cdt2yoI
[gdquest]: https://www.youtube.com/watch?v=hCNOB5jjtmc&list=PLhqJJNjsQ7KFkMVBunWWzFD8SlH714qm4
[practicalli]: https://www.youtube.com/watch?v=jMJ58Gcc1RI&list=PLpr9V-R8ZxiCHMl2_dn1Fovcd34Oz45su
[eivind-fonn]: https://www.youtube.com/watch?v=ZFV5EqpZ6_s&list=PLrJ2YN5y27KLhd3yNs2dR8_inqtEiEweE
[GNU Emacs]: https://www.gnu.org/software/emacs/
[XEmacs]: https://www.xemacs.org
[Emacs And XEmacs]: https://www.emacswiki.org/emacs/EmacsAndXEmacs
[Build Emacs from Source]: https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html
[Emacs: Find Init]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Find-Init.html
[Emacs Plus]: https://github.com/d12frosted/homebrew-emacs-plus
[Emacs Plus features]: https://github.com/d12frosted/homebrew-emacs-plus#features-explained
[Emacs Mac Port]: https://github.com/railwaycat/homebrew-emacsmacport
[Emacs Mac Port features]: https://bitbucket.org/mituharu/emacs-mac/src/master/README-mac
[Emacs for Mac OS X]: https://emacsformacosx.com/
[Git]: https://git-scm.com/downloads
[GNU Tar]: https://www.gnu.org/software/tar/
[BSD Tar]: https://man.openbsd.org/tar
[Source Code Pro]: https://adobe-fonts.github.io/source-code-pro/
[Nanum Gothic]: https://fonts.google.com/specimen/Nanum+Gothic
[Arial Unicode MS]: https://docs.microsoft.com/en-us/typography/font-list/arial-unicode-ms
[MS Gothic]: https://docs.microsoft.com/en-us/typography/font-list/ms-gothic
[Lucida Sans Unicode]: https://docs.microsoft.com/en-us/typography/font-list/lucida-sans-unicode
[ripgrep]: https://github.com/BurntSushi/ripgrep
[ripgrep-installation]: https://github.com/BurntSushi/ripgrep#installation=
[ag]: https://github.com/ggreer/the_silver_searcher
[pt]: https://github.com/monochromegane/the_platinum_searcher
[ack]: https://github.com/beyondgrep/ack3
[GNU Grep]: https://www.gnu.org/software/grep/
[BSD Grep]: https://man.openbsd.org/grep
[Homebrew]: https://brew.sh
[Scoop]: https://scoop.sh
[spacemacs-desktop]: https://github.com/emacs-mirror/emacs/blob/master/etc/emacs.desktop
[icon-repository]: https://github.com/nashamri/spacemacs-logo
[icon-mac-instructions]: https://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/
[so-server-unsafe]: https://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start
[latest tags]: https://github.com/syl20bnr/spacemacs/tags
[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
[spacemacs-desktop]: https://github.com/emacs-mirror/emacs/blob/master/etc/emacs.desktop
[Spacemacs logo]: https://github.com/nashamri/spacemacs-logo
[Nasser Alshammari]: https://github.com/nashamri
[creativecommons-4]: https://creativecommons.org/licenses/by-sa/4.0/
[ripgrep-homebrew]: https://formulae.brew.sh/formula/ripgrep
[Spacemacs Shop]: https://shop.spreadshirt.com/spacemacs-shop
[Bountysource]: https://salt.bountysource.com/teams/spacemacs