problem: The spacemacs-completion layer defines the variable: helm-use-fuzzy But the spacemacs-base distribution doesn't use the spacemacs-completion layer by default. helm-use-fuzzy is used in the helm layer. When a helm buffer is opened, for example: `SPC SPC` Then a warnings buffer opens: >Error (use-package): helm/:config: Symbol’s value as variable is void: helm-use-fuzzy solution: Make sure that helm-use-fuzzy is bound and true. |
||
---|---|---|
.. | ||
img | ||
local/helm-spacemacs-help | ||
config.el | ||
funcs.el | ||
layers.el | ||
packages.el | ||
README.org |
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
grep
like 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
.
Ripgrep: maximum number of column
If you use ripgrep
the default value for --max-columns
is 512
. To change
if set the layer variable spacemacs-helm-rg-max-column-number
.
(setq-default dotspacemacs-configuration-layers '(
(helm :variables spacemacs-helm-rg-max-column-number 1024)))
Key bindings
hjkl navigation
When using the Vim style or Hybrid style with the variable
hybrid-style-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 |
Colors/Faces
Key binding | Description |
---|---|
SPC C l |
helm-colors |
SPC h d F |
spacemacs/helm-faces |
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 C |
clear helm-swoop own cache |
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.
To replace all occurrences of foo
with bar
in your current project:
- Initiate a search with
SPC /
(in a project) - Open
helm-ag-edit
withC-c C-e
- Go to an occurrence of
foo
and enteriedit-mode
withSPC s e
- Change
foo
tobar
- Save the modifications and leave
helm-ag-edit
withC-c C-c
- Alternatively, discard all changes and leave
helm-ag-edit
withC-c C-k
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
.