6cb7399cac
This make `SPC h SPC` as default binding for accessing `helm-spacemacs`, by either A) changing all the documentation; and B) adding a deprecation message for `SPC f e h`. The deprecation use a warning, because if a message is used it's hidden directly when the helm buffer is shown, making it nearly unnoticeable for the user.
162 lines
6 KiB
Org Mode
162 lines
6 KiB
Org Mode
#+TITLE: Quick start
|
|
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../css/readtheorg.css" />
|
|
|
|
* Configuration :TOC_4_org:noexport:
|
|
- [[Configuration layers][Configuration layers]]
|
|
- [[Dotfile (.spacemacs)][Dotfile (.spacemacs)]]
|
|
- [[Dotdirectory (~/.spacemacs.d)][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-To's][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> : 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 [[file: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> : 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, [[file:../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 [[file:../core/templates/.spacemacs.template][dotfile template]] contain further information about how to customize
|
|
Spacemacs. See the dotfile configuration section of the [[file:DOCUMENTATION.org][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.
|
|
|
|
* 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 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~
|
|
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= 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.
|
|
|
|
** 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 [[file:HOWTOs.org][HOWTOs.org]] file.
|