9.2 KiB
Helm layer
Description
This layer enables Helm everywhere in Spacemacs. The alternative to this layer is the Ivy layer which brings the same level of integration as Helm.
These completion systems are the central control towers of Spacemacs, they are used to manage buffers, projects, search results, configuration layers, toggles and more…
Mastering your choice of completion system will make you a Spacemacs power user.
Features:
- Project wide
greplike text search viahelm-dir-smart-do-search - Project wide text replacements using
helm-edit-mode - Buffer wide dynamic text search via
helm-swoop - Fuzzy matching for most
helm-sources - Detailed configuration parameters for helms appearance
- Intuitive
transient state
Install
Helm is part of the standard distribution of Spacemacs so you don't have to do anything to install it if you chose this distribution.
If you want/need to explicitly install Helm then add it to your ~/.spacemacs.
You will need to add helm to the existing dotspacemacs-configuration-layers
list in this file.
Alternative layers
Ivy layer is a replacement layer for Helm. When you add ivy to the existing
= list in your dotfile, it will completely replace the =helm layer.
To switch from Ivy to Helm, modify your ~/.spacemacs. You will need to add
helm to the existing dotspacemacs-configuration-layers list in this file,
and remove ivy.
Configuration
Note: in the following configuration examples, it is possible that helm
is not listed explicitly in your dotfile. If that is the case then just add
it as you would with any other layers.
Auto-Resize
It is possible to have Helm to resize its buffer window to adapt to the length
of the candidate list. By default the buffer size is fixed, to enable automatic
resizing set the layer variable helm-enable-auto-resize to non-nil.
(setq-default dotspacemacs-configuration-layers '(
(helm :variables helm-enable-auto-resize t)))
Default value is nil.
Disable Helm header
To hide the header in the Helm buffer set the layer variable helm-no-header
to non-nil.
(setq-default dotspacemacs-configuration-layers '(
(helm :variables helm-no-header t)))
Default value is nil.
Define Helm position
To set the position of the Helm buffer add the layer variable helm-position
to your dotfile.
The supported values are bottom, top, left and right.
(setq-default dotspacemacs-configuration-layers '(
(helm :variables helm-position 'top)))
Default value is bottom.
Enable fuzzy searching in Helm buffers
It is possible to control the fuzziness of Helm when searching for candidates.
By default this layer tries to enable fuzzy search to all Helm sources.
You can limit the fuzzy search to helm own defaults by setting the layer
variable helm-use-fuzzy to the value 'source.
(setq-default dotspacemacs-configuration-layers '(
(helm :variables helm-use-fuzzy 'source)))
Default value is always.
Key bindings
hjkl navigation
When using the Vim style or Hybrid style with the variable
hybrid-mode-enable-hjkl-bindings set to t, Spacemacs adds navigation in the
Helm buffers with hjkl.
| Key Binding | Description |
|---|---|
C-h |
go to next source |
C-H |
describe key (replace C-h) |
C-j |
go to previous candidate |
C-k |
go to next candidate |
C-l |
same as return |
Transient state
Spacemacs defines a transient state for Helm to make it work like Vim's Unite
plugin.
Initiate the transient state with M-SPC or s-M-SPC while in a Helm buffer.
| Key Binding | Description |
|---|---|
M-SPC or s-M-SPC |
initiate the transient state |
q |
quit transient state |
TAB |
switch to actions page and leave the transient state |
1 |
execute action 0 |
2 |
execute action 1 |
3 |
execute action 2 |
4 |
execute action 3 |
5 |
execute action 4 |
6 |
execute action 5 |
7 |
execute action 6 |
8 |
execute action 7 |
9 |
execute action 8 |
0 |
execute action 9 |
a |
switch to actions page |
g |
go to first candidate |
G |
go to last candidate |
h |
go to previous source |
j |
select next candidate |
k |
select previous candidate |
l |
go to next source |
t |
mark current candidate |
T |
mark all candidates |
v |
execute persistent action |
Bookmarks
In the helm-bookmarks buffer:
| Key Binding | Description |
|---|---|
C-d |
delete the selected bookmark |
C-e |
edit the selected bookmark |
C-f |
toggle filename location |
C-o |
open the selected bookmark in another window |
C-z and Tab switch
The command bound to C-z is much more useful than the one bound to Tab, so it
makes sense to swap them. It's also recommended here.
Helm focus
If you find yourself unable to return focus to Helm (after a careless
mouse-click for example), use SPC w b to return focus to the minibuffer.
Helm-swoop
Helm-swoop is very similar to moccur, it displays a helm buffer with all the
occurrences of the word under point. You can then change the search query in
real-time and navigate between them easily.
You can even edit the occurrences directly in the helm buffer and apply the
modifications to the buffer.
| Key Binding | Description |
|---|---|
SPC s s |
execute helm-swoop |
SPC s S |
execute helm-multi-swoop |
SPC s C-s |
execute helm-multi-swoop-all |
Universal argument
SPC u is not working before helm-M-x (SPC SPC). Instead, call helm-M-x
first, select the command you want to run, and press C-u before pressing
RETURN. For instance: SPC SPC org-reload C-u RET
Replacing text in several files
If you have rg, ag, pt or ack installed, replacing an occurrence of text
in several files can be performed via helm-ag.
Say you want to replace all foo occurrences by bar in your current
project:
- initiate a search with
SPC / - enter in edit mode with
C-c C-e - go to the occurrence and enter in
iedit statewithSPC s e - edit the occurrences then leave the
iedit state - press
C-c C-c
Note: In Spacemacs, helm-ag despite its name works with rg, pt and ack
as well (but not with grep).
Resume last session
Use SPC r l to resume the last helm session. For instance it is handy to
quickly toggle on and off a toggle using SPC h t.