Table of Contents

Helm layer

Table of ContentsClose


1. 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.

1.1. Features:

  • Project wide grep like text search via helm-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

2. 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.

Make sure that the other completion layers: compleseus and ivy are removed or commented out in the dotspacemacs-configuration-layers list. Or add helm below the other completion layers. Spacemacs uses the completion layer that's listed last.

2.1. 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.

3. 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.

3.1. 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.

3.2. 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.

3.3. 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.

3.4. Enable fuzzy searching in Helm buffers

It is possible to control the fuzziness of Helm when searching for candidates. By default this layer enable fuzzy search for all supported Helm sources. It this creates issues please disable it by setting this value to 'source.

In this case please open an issue so that this can be fixed.

(setq-default dotspacemacs-configuration-layers '(
  (helm :variables helm-use-fuzzy 'source)))

Default value is always.

3.5. 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)))

4. Key bindings

4.1. 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>

4.2. 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

4.3. Files

In the helm-files buffer:

Key binding Description
S-<return> open the selected file in other window

4.4. Buffers

In the helm-buffers buffer:

Key binding Description
S-<return> open the selected buffer in other window


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
S-<return> open the selected bookmark in other window

4.6. Colors/Faces

Key binding Description
SPC C l helm-colors
SPC h d F spacemacs/helm-faces

4.7. 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.

4.8. 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.

4.9. 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

4.10. 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

4.11. 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 with C-c C-e
  • Go to an occurrence of foo and enter iedit-mode with SPC s e
  • Change foo to bar
  • Save the modifications and leave helm-ag-edit with C-c C-c
  • Alternatively, discard all changes and leave helm-ag-edit with C-c C-k

Note: In Spacemacs, helm-ag despite its name works with rg, pt and ack as well (but not with grep).

4.12. 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.

5. External resources

Author: root

Created: 2024-05-17 Fri 04:17