d6cdd6aa88
`SPC h T e` for `emacs-tutorial` (aliased from `help-with-tutorial` for a more descriptive name) `SPC h T v` for `evil-tutor-start` Added a wikipedia link to the `vi` article, where the origins of modal editing is discussed.
177 lines
7 KiB
Org Mode
177 lines
7 KiB
Org Mode
#+TITLE: Quick start
|
||
|
||
* Table of Contents :TOC_5_gh:noexport:
|
||
- [[#configuration-layers][Configuration layers]]
|
||
- [[#dotfile-spacemacs][Dotfile (.spacemacs)]]
|
||
- [[#dotdirectory-spacemacsd][Dotdirectory (~/.spacemacs.d)]]
|
||
- [[#learning-spacemacs][Learning Spacemacs]]
|
||
- [[#editing-styles][Editing Styles]]
|
||
- [[#the-leader-keys][The leader keys]]
|
||
- [[#evil-tutor][Evil-tutor]]
|
||
- [[#universal-argument][Universal argument]]
|
||
- [[#configuration-layers-and-package-discovery][Configuration layers and Package discovery]]
|
||
- [[#key-bindings-discovery][Key bindings discovery]]
|
||
- [[#describe-functions][Describe functions]]
|
||
- [[#how-tos][How-To's]]
|
||
|
||
* Configuration layers
|
||
Spacemacs divides its configuration into self-contained units called
|
||
=configuration layers=. These layers are stacked on top of each other
|
||
to achieve a custom configuration.
|
||
|
||
By default Spacemacs uses a dotfile called =~/.spacemacs= to control which
|
||
layers to load. Within this file you can also configure certain features.
|
||
|
||
A configuration layer is a directory containing at least a =packages.el=
|
||
file which defines and configures packages to be downloaded from Emacs
|
||
package repositories using the =package.el= built-in feature of Emacs.
|
||
|
||
If you already have your own =Emacs= configuration you can move it to your
|
||
own layer.
|
||
|
||
The following command creates a layer in the =private= directory:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
SPC SPC configuration-layer/create-layer RET
|
||
#+END_EXAMPLE
|
||
|
||
Any configuration layers you create must be explicitly loaded in =~/.spacemacs=.
|
||
|
||
Note: For your privacy, the contents of the =private= directory are not
|
||
under source control. See the section on private configuration management in
|
||
the [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org][documentation]].
|
||
|
||
* Dotfile (.spacemacs)
|
||
As mentioned =.spacemacs= controls which configuration layers to load and
|
||
is also a means to customizing Spacemacs.
|
||
|
||
The following command will create a =.spacemacs= file in your home directory:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
SPC SPC dotspacemacs/install RET
|
||
#+END_EXAMPLE
|
||
|
||
To open the installed dotfile:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
SPC f e d
|
||
#+END_EXAMPLE
|
||
|
||
To load some configuration layers using the variable
|
||
=dotspacemacs-configuration-layers=:
|
||
|
||
#+BEGIN_SRC elisp
|
||
;; List of configuration layers to load.
|
||
dotspacemacs-configuration-layers '(auto-completion smex)
|
||
#+END_SRC
|
||
|
||
Some configuration layers support configuration variables to expose granular
|
||
control over layer-specific features, [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/+source-control/git/README.org][git layer]] being one such example.
|
||
Variables can be directly set within =dotspacemacs-configuration-layers= like so:
|
||
|
||
#+BEGIN_SRC elisp
|
||
;; List of configuration layers to load.
|
||
dotspacemacs-configuration-layers '(auto-completion
|
||
(git :variables
|
||
git-magit-status-fullscreen t)
|
||
smex)
|
||
#+END_SRC
|
||
|
||
At anytime you can apply the changes made to the dotfile or layers
|
||
_without restarting_ Spacemacs by pressing ~SPC f e R~.
|
||
|
||
The [[https://github.com/syl20bnr/spacemacs/blob/master/core/templates/.spacemacs.template][dotfile template]] contains further information about how to customize
|
||
Spacemacs. See the dotfile configuration section of the [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org#dotfile-configuration][documentation]] for
|
||
more details.
|
||
|
||
* Dotdirectory (~/.spacemacs.d)
|
||
Like =Emacs=, Spacemacs initialization can also be contained in an =init.el= file
|
||
in a special directory =~/.spacemacs.d=. The contents of the dotfile should be
|
||
then copied in the =init.el= file.
|
||
|
||
The Emacs dotfile or dotdirectory is not replaced but rather
|
||
complemented by the Spacemacs dotfile or dotdirectory. During startup,
|
||
Emacs still uses =~/.emacs.d/init.el= (or =~/.emacs=) for its
|
||
initialization, and variable =user-emacs-directory= will still point
|
||
to =~/.emacs.d/=, even if =~/.spacemacs.d= or =~/.spacemacs= are
|
||
present. Only now =~/.emacs.d/init.el= is provided by Spacemacs
|
||
(e.g. after cloning the Spacemacs git repo into an empty
|
||
=~/.emacs.d/=), and your own personal configurations go into
|
||
=~/.spacemacs.d/init.el= (or =~/.spacemacs=).
|
||
|
||
Have a look into the FAQ for an easy workaround to maintain (your
|
||
former) vanilla Emacs and (your new) Spacemacs configurations
|
||
side-by-side without the need to rename and backup =~/.emacs.d/=.
|
||
|
||
* Learning Spacemacs
|
||
** Editing Styles
|
||
Spacemacs can be used by Vim users or Emacs users by setting the
|
||
=dotspacemacs-editing-style= variable to =vim=, =emacs= or even =hybrid=
|
||
in the dotfile =~/.spacemacs=.
|
||
|
||
** The leader keys
|
||
Spacemacs key bindings use a leader key which is by default bound to
|
||
~SPC~ (space bar) in =vim= or =hybrid= editing styles and ~M-m~ in =emacs=
|
||
style.
|
||
|
||
You can change it by setting the variable =dotspacemacs-leader-key= if
|
||
you use the =vim= style or =dotspacemacs-emacs-leader-key= if you use
|
||
the =emacs= style (these variables must be set in the file =~/.spacemacs=).
|
||
|
||
For simplicity the documentation always refers to the leader key as
|
||
~SPC~.
|
||
|
||
There is a secondary leader key called the major-mode leader key which is
|
||
set to ~,~ by default. This key is a shortcut for ~SPC m~
|
||
where all the major-mode specific commands are bound.
|
||
|
||
** Evil-tutor
|
||
If you are willing to learn the Vim key bindings (highly recommended since
|
||
you can benefit from them even in =emacs= style), press ~SPC h T v~
|
||
to begin an Evil-adapted Vimtutor.
|
||
|
||
** Universal argument
|
||
In =vim= editing style the universal argument defaults to ~SPC u~
|
||
instead of ~C-u~ because the latter is used to scroll up as in Vim.
|
||
|
||
** Configuration layers and Package discovery
|
||
By using =helm-spacemacs-help= with ~SPC h SPC~ you can quickly search
|
||
for a package and get the name of the layers using it.
|
||
|
||
You can also easily go to the =README.org= of a layer or go to the initialization
|
||
function of a package.
|
||
|
||
** Key bindings discovery
|
||
Thanks to [[https://github.com/justbur/emacs-which-key][which-key]], whenever a prefix command is pressed (like ~SPC~)
|
||
a buffer appears after one second listing the possible keys for this prefix.
|
||
|
||
It is also possible to search for specific key bindings by pressing:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
SPC ?
|
||
#+END_EXAMPLE
|
||
|
||
To narrow the bindings list to those prefixed with =SPC=,
|
||
type a pattern like this regular expression:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
SPC\ b
|
||
#+END_EXAMPLE
|
||
|
||
which would list all =buffer= related bindings. *Note:* You are at the
|
||
/HELM-Descbind/ prompt, the pattern consists of 6 letters: uppercase ~SPC~, a
|
||
backslash, an actual space and a lowercase ~b~.
|
||
|
||
** Describe functions
|
||
=Describe functions= are powerful Emacs introspection commands to get information
|
||
about functions, variables, modes etc. These commands are bound thusly:
|
||
|
||
| Key binding | Description |
|
||
|-------------+-------------------|
|
||
| ~SPC h d f~ | describe-function |
|
||
| ~SPC h d k~ | describe-key |
|
||
| ~SPC h d m~ | describe-mode |
|
||
| ~SPC h d v~ | describe-variable |
|
||
|
||
* How-To's
|
||
Some quick =how-to's= are compiled in the [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/FAQ.org#how-do-i][FAQ.]]
|