From 45bf3825ddc8137a31df8a25ae8057d0d11105f1 Mon Sep 17 00:00:00 2001 From: Lucius Hu <1222865+lebensterben@users.noreply.github.com> Date: Mon, 25 Jul 2022 04:25:05 -0400 Subject: [PATCH] README: rewrite (#15660) rewrite --- README.md | 743 +++++++++++++++++++++++++++++------------------------- 1 file changed, 405 insertions(+), 338 deletions(-) diff --git a/README.md b/README.md index 2a5bffdc9..1d549a965 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ -Made with SpacemacsGPLv3 SoftwareTwitter
-- - - +Made with Spacemacs +GPLv3 Software +Twitter -

Spacemacs

-

+ +

Spacemacs

+

philosophy | for whom? @@ -20,80 +22,45 @@ FAQ

-- - - -

+ +

Gitter Discord - +elisp state Donate -Donate +Merchandise Recommend it

+ - - - +**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 ``` - -**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 + ``` - +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. SPC b for all the buffer commands or SPC p 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 SPC h SPC. -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 + and + . + + 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\\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\`. + +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\` +3. Now clone this repository with Git. The following work for both shell + and PowerShell: - Clone Spacemacs to the `` 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\` 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 ``` -## 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