9.8 KiB
:completion helm
Description unfold
This module provides Helm integration to a variety of Emacs commands, as well as a unified interface for project search and replace, powered by Ripgrep.
For official documentation about Helm, see:
Maintainers
This module has no dedicated maintainers. Become a maintainer?
Module flags
- +childframe
- Display Helm windows in a child frame rather than an popup buffer. Requires GUI Emacs.
- +fuzzy
- Enable fuzzy completion for Helm searches.
- +icons
- Display icons on completion results (where possible) using either doom-package:nerd-icons or doom-package:treemacs iconsets.
Packages
- doom-package:helm
- doom-package:helm-company
- doom-package:helm-c-yasnippet
- doom-package:helm-descbinds
- doom-package:helm-describe-modes
- doom-package:helm-flx* if doom-module:+fuzzy
- doom-package:helm-icons* if doom-module:+icons
- doom-package:helm-org* if doom-module::lang org
- doom-package:helm-posframe* if doom-module:+childframe
- doom-package:helm-projectile
- doom-package:helm-rg
- doom-package:helm-swiper
TODO Hacks
This module's hacks haven't been documented yet. Document them?
TODO Changelog
This module does not have a changelog yet.
Installation
Enable this module in your doom! block.
This module has only one requirement: Ripgrep, which is a hard dependency of Doom itself, so you should already have it installed.
By enabling this module, it will enable helm-mode and remap many commands to their helm equivalents, such as:
- find-file (C-c C-f or <leader> f f) -> helm-find-files
- execute-extended-command (M-x) -> helm-M-x
- switch-to-buffer (C-x b or <leader> b b) -> helm-buffers-list
- …among others
No setup is required on your part. Helm provides many commands to interface with a variety of programs from fzf to Dash docsets to pass and much more. These programs are optional for this module, but must be installed if you intend to use their associated Helm command or package.
TODO Usage
Much like doom-package:ivy and doom-package:vertico, doom-package:helm is a large framework. Covering all its features is not within the scope of this module's documentation, so only its highlights will be covered here.
Jump-to navigation
Similar to Ivy, this module provides an interface to navigate within a project using doom-package:projectile:
| Keybind | Description |
|---|---|
| SPC p f, SPC SPC | Jump to file in project (+helm/projectile-find-file) |
| SPC f f, SPC . | Jump to file from current directory (helm-find-files) |
| SPC s i | Jump to symbol in file (helm-semantic-or-imenu) |
Project search & replace
This module also provides interactive text search and replace using Ripgrep.
Search
| Keybind | Description |
|---|---|
| SPC s p | Search project (+default/search-project) |
| SPC s P | Search another project (+default/search-other-project) |
| SPC s d | Search this directory (+default/search-cwd) |
| SPC s D | Search another directory (+default/search-other-cwd) |
Prefixing these keys with the universal argument (SPC u for evil users; C-u otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files.
This module also provides Ex Commands for evil users:
| Ex command | Description |
|---|---|
:pg[rep][!] [QUERY] |
Search project (if !, include hidden files) |
:pg[rep]d[!] [QUERY] |
Search from current directory (if !, don't search recursively) |
The optional ! is equivalent to the universal argument for the previous
commands.
Replace
These keybindings are available while a search is active:
| Keybind | Description |
|---|---|
| C-c C-o | Open a buffer with your search results |
| C-c C-e | Open a writable buffer of your search results |
| C-SPC | Preview the current candidate |
| C-RET | Open the selected candidate in other-window |
Changes to the resulting doom-package:wgrep buffer (opened by C-c C-e) can be committed with C-c C-c and aborted with C-c C-k (alternatively ZZ and ZQ, for evil users).
In-buffer searching
The doom-package:swiper package provides an interactive buffer search powered by helm. It can be invoked with:
- SPC s s (swiper-isearch)
- SPC s S (swiper-isearch-thing-at-point)
- SPC s b (swiper)
:sw[iper] [QUERY]
A doom-package:wgrep buffer can be opened from swiper with C-c C-e.
Helm integration for various completing commands
Helm also has a number of overrides for built-in functionality:
Jump to files, buffers or projects
| Keybind | Description |
|---|---|
| SPC p t | List all TODO/FIXMEs in project |
| SPC s b | Search the current buffer (+default/search-buffer) |
| SPC s d | Search this directory (+default/search-cwd) |
| SPC s D | Search another directory (+default/search-other-cwd) |
| SPC s i | Search for symbol in current buffer |
| SPC s p | Search project (+default/search-project) |
| SPC s P | Search another project (+default/search-other-project) |
| SPC s s | Search the current buffer (incrementally) (+default/search-buffer) |
Search
| Keybind | Description |
|---|---|
| SPC p t | List all TODO/FIXMEs in project |
| SPC s b | Search the current buffer (+default/search-buffer) |
| SPC s d | Search this directory (+default/search-cwd) |
| SPC s D | Search another directory (+default/search-other-cwd) |
| SPC s i | Search for symbol in current buffer |
| SPC s p | Search project (+default/search-project) |
| SPC s P | Search another project (+default/search-other-project) |
| SPC s s | Search the current buffer (incrementally) (+default/search-buffer) |
TODO Configuration
This module's configuration documentation is incomplete. Complete it?
helm-mode
This module enables helm-mode by default, which will force any functions that
call completing-read, read-file-name, completion-in-region and friends to
use Helm's completion interface instead. Any function listed in the
helm-completing-read-handlers-alist variable will be exempt from this.
For example, an emacs command foo in package bar that uses a completion
framework other than helm, say company, may break if handed off to Helm, so it
makes sense to exempt foo with the following:
;; add to $DOOMDIR/config.el
(after! helm
(add-to-list 'helm-completing-read-handlers-alist (cons #'foo nil)))Icons
There are two icon "themes" available for this module: doom-package:nerd-icons and doom-package:treemacs. By default, and to maintain consistency with other icons across Doom's modules, doom-package:nerd-icons is used. To change this:
;; add to $DOOMDIR/config.el
(after! helm
(setq helm-icons-provider 'treemacs))Troubleshooting
There are no known problems with this module. Report one?
Frequently asked questions
Helm vs Ivy vs Ido vs Vertico
See this answer.
TODO Appendix
This module has no appendix yet. Write one?