263 lines
11 KiB
Org Mode
263 lines
11 KiB
Org Mode
#+TITLE: Helm layer
|
|
|
|
#+TAGS: completion|layer
|
|
|
|
[[file:img/helm.png]]
|
|
|
|
* Table of Contents :TOC_5_gh:noexport:
|
|
- [[#description][Description]]
|
|
- [[#features][Features:]]
|
|
- [[#install][Install]]
|
|
- [[#alternative-layers][Alternative layers]]
|
|
- [[#configuration][Configuration]]
|
|
- [[#auto-resize][Auto-Resize]]
|
|
- [[#disable-helm-header][Disable Helm header]]
|
|
- [[#define-helm-position][Define Helm position]]
|
|
- [[#enable-fuzzy-searching-in-helm-buffers][Enable fuzzy searching in Helm buffers]]
|
|
- [[#ripgrep-maximum-number-of-column][Ripgrep: maximum number of column]]
|
|
- [[#key-bindings][Key bindings]]
|
|
- [[#hjkl-navigation][hjkl navigation]]
|
|
- [[#transient-state][Transient state]]
|
|
- [[#files][Files]]
|
|
- [[#buffers][Buffers]]
|
|
- [[#bookmarks][Bookmarks]]
|
|
- [[#colorsfaces][Colors/Faces]]
|
|
- [[#c-z-and-tab-switch][C-z and Tab switch]]
|
|
- [[#helm-focus][Helm focus]]
|
|
- [[#helm-swoop][Helm-swoop]]
|
|
- [[#universal-argument][Universal argument]]
|
|
- [[#replacing-text-in-several-files][Replacing text in several files]]
|
|
- [[#resume-last-session][Resume last session]]
|
|
- [[#external-resources][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.
|
|
|
|
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.
|
|
|
|
** 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.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq-default dotspacemacs-configuration-layers '(
|
|
(helm :variables helm-enable-auto-resize t)))
|
|
#+END_SRC
|
|
|
|
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.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq-default dotspacemacs-configuration-layers '(
|
|
(helm :variables helm-no-header t)))
|
|
#+END_SRC
|
|
|
|
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=.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq-default dotspacemacs-configuration-layers '(
|
|
(helm :variables helm-position 'top)))
|
|
#+END_SRC
|
|
|
|
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 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.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq-default dotspacemacs-configuration-layers '(
|
|
(helm :variables helm-use-fuzzy 'source)))
|
|
#+END_SRC
|
|
|
|
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=.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setq-default dotspacemacs-configuration-layers '(
|
|
(helm :variables spacemacs-helm-rg-max-column-number 1024)))
|
|
#+END_SRC
|
|
|
|
* 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 [[https://github.com/Shougo/unite.vim][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 |
|
|
|
|
** Files
|
|
In the =helm-files= buffer:
|
|
|
|
| Key binding | Description |
|
|
|--------------+----------------------------------------|
|
|
| ~S-<return>~ | open the selected file in other window |
|
|
|
|
** Buffers
|
|
In the =helm-buffers= buffer:
|
|
|
|
| Key binding | Description |
|
|
|--------------+------------------------------------------|
|
|
| ~S-<return>~ | open the selected buffer in other window |
|
|
|
|
** 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 |
|
|
| ~S-<return>~ | open the selected bookmark in other 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 [[http://tuhdo.github.io/helm-intro.html][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
|
|
[[https://github.com/ShingoFukuyama/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 [[https://github.com/syohex/emacs-helm-ag][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
|
|
- [[https://github.com/emacs-helm/helm/wiki][The Helm wiki]]
|
|
- [[http://tuhdo.github.io/helm-intro.html][The Helm guide]]
|