spacemacs/doc/QUICK_START.org

#+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-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 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 [[file:FAQ.org::How%20do%20I...][FAQ.org]] file.