spacemacs/layers/+completion/helm

Helm layer

• Description
  • Features:
• Install
  • Alternative layers
• Configuration
  • Auto-Resize
  • Disable Helm header
  • Define Helm position
  • Enable fuzzy searching in Helm buffers
  • Ripgrep: maximum number of column
• Key bindings
  • hjkl navigation
  • Transient state
  • Bookmarks
  • Colors/Faces
  • C-z and Tab switch
  • Helm focus
  • Helm-swoop
  • Universal argument
  • Replacing text in several files
  • Resume last session
• External resources

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

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

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.

External resources

• The Helm wiki
• The Helm guide