:completion helm

A search engine for admirals

1. Description

This module provides Helm integration for a variety of Emacs commands, as well as a unified interface for project search and replace, powered by ripgrep.

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

+childframe
Display Helm popups in a floating frame rather than in the pop up window at the bottom.
+fuzzy
Enable fuzzy completion for Helm searches.
+icons
Enable icons (supports both all-the-icons and treemacs icons).

1.4. Hacks

No hacks documented for this module.

2. Prerequisites

This module has no external prerequisites.

3. Usage

Much like Ivy, Helm is a large framework and as such covering everything is not in scope, however a number of Doom-specific features are shown below:

3.1. Jump-to navigation

Similar to Ivy, this module provides an interface to navigate within a project using projectile:

Keybind Description
<leader> p f or <leader> SPC Jump to file in project
<leader> f f or <leader> . Jump to file from current directory
<leader> s i Jump to symbol in file

3.2. Project search & replace

This module also provides interactive text search and replace using ripgrep.

3.2.1. Search

Keybind Description
<leader> s p Search project
<leader> s P Search another project
<leader> s d Search this directory
<leader> s D Search another directory

Prefixing these keys with the universal argument (<leader> 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.

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

3.3. In-buffer searching

The swiper package provides an interactive buffer search powered by helm. It can be invoked with:

  • <leader> s s (swiper-isearch)
  • <leader> s S (swiper-isearch-thing-at-point)
  • <leader> s b (swiper)
  • :sw[iper] [QUERY]

A wgrep buffer can be opened from swiper with C-c C-e.

3.4. Helm integration for various completing commands

Helm also has a number of overrides for built-in functionality:

3.4.1. General

Keybind Description
M-x or <leader> : Smarter, smex-powered M-x
<leader> Resume last ivy session

3.4.2. Jump to files, buffers or projects

Keybind Description
<leader> RET Find bookmark
<leader> f f or <leader> . Browse from current directory
<leader> p f or <leader> SPC Find file in project
<leader> f r Find recently opened file
<leader> p p Open another project
<leader> b b or <leader> , Switch to buffer in current workspace
<leader> b B or <leader> < Switch to buffer

3.4.3. Search

Keybind Description
<leader> p t List all TODO/FIXMEs in project
<leader> s b Search the current buffer
<leader> s d Search this directory
<leader> s D Search another directory
<leader> s i Search for symbol in current buffer
<leader> s p Search project
<leader> s P Search another project
<leader> s s Search the current buffer (incrementally)

4. Configuration

4.1. Icons

Icons are now included, and support 2 providers (all-the-icons and treemacs). By default, to maintain consistency we use all-the-icons; however if you wish to modify this you can do so using the below snippet:

(after! helm
  (setq helm-icons-provider 'treemacs))

4.2. TODO Posframe

5. Troubleshooting

There are no known problems with this module. Report one?

6. TODO Appendix

This module has no appendix yet. Write one?