184 lines
8.1 KiB
Org Mode
184 lines
8.1 KiB
Org Mode
← [[doom-module-index:][Back to module index]] ! [[doom-module-issues:::completion helm][Issues]] ↖ [[doom-repo:tree/develop/modules/completion/helm/][Github]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
|
|
--------------------------------------------------------------------------------
|
|
#+title: :completion helm
|
|
#+subtitle: A tank for hunting a house fly
|
|
#+created: February 20, 2017
|
|
#+since: 2.0.0
|
|
|
|
* Description :unfold:
|
|
This module provides Helm integration for a variety of Emacs commands, as well
|
|
as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep][Ripgrep]].
|
|
|
|
** Maintainers
|
|
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
|
|
|
** Module flags
|
|
- +childframe ::
|
|
Display Helm windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][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:][all-the-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
|
|
#+begin_quote
|
|
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
|
|
#+end_quote
|
|
|
|
** TODO Changelog
|
|
# This section will be machine generated. Don't edit it by hand.
|
|
/This module does not have a changelog yet./
|
|
|
|
* Installation
|
|
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
|
|
|
This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of
|
|
Doom itself, so you should already have it installed.
|
|
|
|
Otherwise, Helm provides many commands to interface with a variety of programs
|
|
from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][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 plugin.
|
|
|
|
* TODO Usage
|
|
#+begin_quote
|
|
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
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 |
|
|
|------------------+-------------------------------------|
|
|
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
|
|
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
|
|
| [[kbd:][SPC s i]] | Jump to symbol in file |
|
|
|
|
** Project search & replace
|
|
This module also provides interactive text search and replace using ripgrep.
|
|
|
|
*** Search
|
|
| Keybind | Description |
|
|
|---------+--------------------------|
|
|
| [[kbd:][SPC s p]] | Search project |
|
|
| [[kbd:][SPC s P]] | Search another project |
|
|
| [[kbd:][SPC s d]] | Search this directory |
|
|
| [[kbd:][SPC s D]] | Search another directory |
|
|
|
|
Prefixing these keys with the universal argument ([[kbd:][SPC u]] for evil users; [[kbd:][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 |
|
|
|---------+-----------------------------------------------|
|
|
| [[kbd:][C-c C-o]] | Open a buffer with your search results |
|
|
| [[kbd:][C-c C-e]] | Open a writable buffer of your search results |
|
|
| [[kbd:][C-SPC]] | Preview the current candidate |
|
|
| [[kbd:][C-RET]] | Open the selected candidate in other-window |
|
|
|
|
Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with
|
|
[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][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:
|
|
- [[kbd:][SPC s s]] (~swiper-isearch~)
|
|
- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~)
|
|
- [[kbd:][SPC s b]] (~swiper~)
|
|
- ~:sw[iper] [QUERY]~
|
|
|
|
A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]].
|
|
|
|
** Helm integration for various completing commands
|
|
Helm also has a number of overrides for built-in functionality:
|
|
|
|
*** General
|
|
| Keybind | Description |
|
|
|------------+---------------------------|
|
|
| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x |
|
|
| [[kbd:][SPC ']] | Resume last ivy session |
|
|
|
|
*** Jump to files, buffers or projects
|
|
| Keybind | Description |
|
|
|------------------+---------------------------------------|
|
|
| [[kbd:][SPC RET]] | Find bookmark |
|
|
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
|
|
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
|
|
| [[kbd:][SPC f r]] | Find recently opened file |
|
|
| [[kbd:][SPC p p]] | Open another project |
|
|
| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
|
|
| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
|
|
|
|
*** Search
|
|
| Keybind | Description |
|
|
|---------+-------------------------------------------|
|
|
| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
|
|
| [[kbd:][SPC s b]] | Search the current buffer |
|
|
| [[kbd:][SPC s d]] | Search this directory |
|
|
| [[kbd:][SPC s D]] | Search another directory |
|
|
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
|
|
| [[kbd:][SPC s p]] | Search project |
|
|
| [[kbd:][SPC s P]] | Search another project |
|
|
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) |
|
|
|
|
* TODO Configuration
|
|
#+begin_quote
|
|
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
** Icons
|
|
Icon support is now included, through one of two providers: [[doom-package:][all-the-icons]] and
|
|
[[doom-package:][treemacs]]. By default, to maintain consistency we use [[doom-package:][all-the-icons]]; however if
|
|
you wish to modify this you can do so using the below snippet:
|
|
|
|
#+begin_src emacs-lisp
|
|
(after! helm
|
|
(setq helm-icons-provider 'treemacs))
|
|
#+end_src
|
|
|
|
** TODO Posframe
|
|
|
|
* Troubleshooting
|
|
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
|
|
|
* Frequently asked questions
|
|
[[doom-suggest-faq:][Ask a question?]]
|
|
|
|
** Helm vs Ivy vs Ido vs Vertico
|
|
See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]].
|
|
|
|
* TODO Appendix
|
|
#+begin_quote
|
|
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
|
#+end_quote
|