- Code guidelines
- Key bindings conventions
- Writing documentation
Function names follow these conventions:
spacemacs/xxx
is an interactive function calledxxx
spacemacs//xxx
is a private function calledxxx
(implementation details)spacemacs|xxx
is a macro calledxxx
Variables follow these conventions:
spacemacs-xxx
is a variablespacemacs--xxx
is a private variable (implementation details)
A package is initialized in a function with name <layer>/init-xxx
where:
<layer>
is the layer namexxx
is the package name
- Always use
progn
when a code block requires multiple lines for:init
or:config
keywords. - If there is only one line of code then try to keep
:init
or:config
keywords on the same line. - Don’t nest multiple
use-package
calls unless you have a very good reason to do it.
SPC o
and SPC m o
must not be used by any layer. They are reserved for the
user.
SPC m
is reserved for the current major mode. Three keys bindings are not an
issue (ie. SPC m h d
) since SPC m
can be accessed via ,
.
Whenever possible a transient-state should be enabled with M-SPC
and s-M-SPC
. We
need the latter bindings on OS X since M-SPC
is used by the OS for spotlight.
For instance transient-states dedicated to special buffers like helm
or ido
buffers are good candidates to be put on M-SPC
and s-M-SPC
.
It is recommended to add q
to leave the transient-state.
Evilifying a buffer is to set the evilified state
as the default
state for the major mode of the buffer.
The evilified state
is derived from the emacs state
and modify the
map to:
- add
hjkl
navigation - add scrolling feature on
C-f
,C-b
,C-d
andC-u
G
andgg
to go to the end and beginning of the buffer- add incremental search with
/
,n
andN
- enabling
evil-ex
on:
- add
visual state
andvisual line state
onv
andV
- add yank on
y
in visual state only - activate evil-leader key on
SPC
Setting the evilified state
to a mode is done by calling the macro
spacemacs|evilify-map
.
Evilification rebinds shadowed key bindings according to the following rules:
- alphabetic key bindings:
x
->X
->C-x
->C-X
SPC
->'
/
->\
:
->|
C-g
cannot be shadowed
If a key binding cannot be remapped then it is ignored and a warning message
is displayed in *Messages*
.
To be consistent with the Vim way, n
and N
are favored over Emacs n
and
p
.
Ideally a transient-state should be provided to smooth the navigation experience. A transient-state allows to repeat key bindings without entering each time the prefix commands. More info on transient-states in the documentation.
The prefix for going to something is SPC m g
.
Key | Description |
---|---|
m g a | go to alternate file (i.e. .h <--> .cpp ) |
m g b | go back to previous location (before last jump) |
m g g | go to things under point |
m g G | go to things under point in other window |
m g t | go to corresponding test file if any |
Navigation in buffers like Helm
and ido
which are in insert state
should be performed with C-j
and C-k
bindings for vertical movements.
Key | Description |
---|---|
C-j | go down |
C-k | go up |
Confirming and aborting actions which are bound to C-c C-c
and C-c C-k
in raw Emacs are mirrored in Spacemacs to:
Key | Description |
---|---|
SPC m , and SPC m c | Valid/Confirm the message |
SPC m a and SPC m k | Abort/Discard the message |
Some example of these modes are magit
commit messages, message-mode
for
mails or org-mode
notes.
Live evaluation of code is under the prefix SPC m e
.
Key | Description |
---|---|
m e $ | put point at the end of the line and evaluate |
m e b | evaluate buffer |
m e e | evaluate last expression |
m e f | evaluate function |
m e l | evaluate line |
m e r | evaluate region |
A lot of languages can interact with a REPL. To help keeping a consistent behavior between those languages the following conventions should be followed:
SPC m s
is the prefix for sending code. This allows fast interaction with the REPL whenever it is possible- lower case key bindings keep the focus on the current buffer
- upper case key bindings move the focus to the REPL buffer
Key | Description |
---|---|
m s b | send buffer |
m s B | send buffer and switch to REPL |
m s d | first key to send buffer and switch to REPL to debug (step) |
m s D | second key to send buffer and switch to REPL to debug (step) |
m s f | send function |
m s F | send function and switch to REPL |
m s i | start/switch to REPL inferior process |
m s l | send line |
m s L | send line and switch to REPL |
m s r | send region |
m s R | send region and switch to REPL |
Note: we don’t distinguish between the file and the buffer.
History navigation in shells or REPLs buffers should be bound as well to
C-j
and C-k
.
Key | Description |
---|---|
C-j | next item in history |
C-k | previous item in history |
C-l | clear screen |
C-r | search backward in history |
The base prefix for major mode specific compilation is SPC m c
.
Key Binding | Description |
---|---|
m c b | compile buffer |
m c c | compile |
m c r | clean and compile |
Note: we don’t distinguish between the file and the buffer. We can implement an auto-save of the buffer before compiling the buffer.
The base prefix for debugging commands is SPC d
.
Key Binding | Description |
---|---|
m d a | abandon current process |
m d b | toggle a breakpoint |
m d B | clear all breakpoints |
m d c | continue |
m d d | start debug session |
m d i | inspect value at point |
m d l | local variables |
m d n | next |
m d r | run |
m d s | step |
Notes:
- Ideally a transient-state for breakpoint navigation should be provided.
- If there is no toggle breakpoint function, then it should be implemented at the spacemacs level and ideally the function should be proposed as a patch upstream (major mode repository).
For layers supporting markup languages please follow the following keybindings whenever applicable.
All header functionality should be grouped under SPC m h
Key Binding | Description |
---|---|
m h i | Insert a header |
m h I | Insert a header alternative method (if existing) |
m h 1..10 | Insert a header of level 1..10 (if possible) |
Insertion of common elements like links or footnotes should be grouped
under SPC m i
Key Binding | Description |
---|---|
m i f | Insert footnote |
m i i | Insert image |
m i l | Insert link |
m i u | Insert url |
m i w | Insert wiki-link |
Manipulation of text regions should be grouped under SPC m x
Key Binding | Description |
---|---|
m x b | Make region bold |
m x c | Make region code |
m x i | Make region italic |
m x q | Quote a region |
m x r | Remove formatting from region |
m x s | Make region strike-through |
m x u | Make region underlined |
m x v | Make region verbose |
In normal mode Vim style movement should be enabled with these keybindings:
Key Binding | Description |
---|---|
g h | Move up one level in headings |
g j | Move to next heading on same level |
g k | Move to previous heading on same level |
g l | Move down one level in headings |
Promotion, demotion and movement of headings or list elements (whatever is possible) should be enabled with the following keys in any mode
Key Binding | Description |
---|---|
M-h | Promote heading by one level |
M-j | Move element down |
M-k | Move element up |
M-l | Demote heading by one level |
If table specific commands are available the they are grouped under the
SPC m t
group.
A lot of languages have their own test frameworks. These frameworks share common actions that we can unite under the same key bindings:
SPC m t
is the prefix for test execution.SPC m t X
is used to executeSPC m t x
but in debug mode (if supported).
Key | Description |
---|---|
m t a | execute all the tests of the current project |
m t A | execute all the tests of the current project in debug |
m t b | execute all the tests of the current buffer |
m t B | execute all the tests of the current buffer in debug |
m t t | execute the current test (thing at point, function) |
m t T | execute the current test in debug (thing at point, function) |
Note: we don’t distinguish between the file and the buffer. We can implement an auto-save of the buffer before executing the tests of buffer.
Key | Description |
---|---|
m t m | execute the tests of the current module |
m t M | execute the tests of the current module in debug |
m t s | execute the tests of the current suite |
m t S | execute the tests of the current suite in debug |
Note that there are overlaps, depending on the language we will choose one or more bindings for the same thing
- Global toggles are under
SPC t
,SPC T
andSPC C-t
- Major mode toggles are only under
SPC m T
Refactoring prefix is SPC m r
.
Major-mode code formatting is under prefix SPC m =
.
Key Binding | Description |
---|---|
m = = | format thing under point |
m = b | format current buffer |
m = f | format current function |
The base prefix for help commands is SPC h
. Documentation is considered
as an help command.
Key | Description |
---|---|
m h h | documentation of thing under point |
m h r | documentation of selected region |
Spacemacs provides an example layer README.org
file in
~/.emacs.d/core/templates/README.org.template
.
- Spacemacs tries to keep the documentation consistent between all layers by
providing some rules for spacing:
- After each header, you should not add an empty line
- Exception: If the first item under the header is a table, add an empty line after it
- At the end of each header node, there should be an empty line
- Note: Many layer
READMEs
do not follow this convention yet. Please fix them if you can.
- After each header, you should not add an empty line
- To keep things readable only mention the prefix
SPC
when documenting key bindings, you don’t need to mentionM-m
.