doomemacs/modules/completion/helm

:completion helm

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
  • Jump-to navigation
  • Project search & replace
    • Search
    • Replace
  • In-buffer searching
  • Helm integration for various completing commands
    • General
    • Jump to files, buffers or projects
    • Search
• Configuration
  • helm-mode
  • Icons
• Troubleshooting
• Frequently asked questions
  • Helm vs Ivy vs Ido vs Vertico
• Appendix

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:

• https://rnchzn.github.io/helm/doc/helm-manual.html
• https://tuhdo.github.io/helm-intro.html

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:

General

Keybind	Description
M-x, SPC :	Smarter, smex-powered M-x
SPC '	Resume last ivy session

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

Ask a question?

Helm vs Ivy vs Ido vs Vertico

See this answer.

TODO Appendix

󱌣 This module has no appendix yet. Write one?