mirror of
https://github.com/doomemacs/doomemacs.git
synced 2026-03-08 15:50:40 -07:00
6f40ad55f5
There's little reason for users to use these macros in their private configs over plain ol' `with-eval-after-load` and `use-package`, unless they're writing their own modules. It's my fault for signal boosting them in documentation and whenever I'm asked for help, because beginners now believe they are somehow required for Doom to work correctly (there are guides out there telling beginners that migrating to Doom involves replacing all instances of `with-eval-after-load` and `use-package` in their pre-existing configs with `after!` and `use-package!` -- which was never true). What's more, I plan to replace `use-package`, internally, so the `use-package!` macro won't exist for much longer.
206 lines
9.9 KiB
Org Mode
206 lines
9.9 KiB
Org Mode
#+title: :completion helm
|
|
#+subtitle: A bazooka for hunting house flies
|
|
#+created: February 20, 2017
|
|
#+since: 2.0.0
|
|
|
|
* 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 [[https://github.com/BurntSushi/ripgrep][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./ [[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: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
|
|
#+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.
|
|
|
|
By enabling this module, it will enable helm-mode and remap many commands to
|
|
their helm equivalents, such as:
|
|
|
|
- [[cmd:][find-file]] ([[kbd:][C-c C-f]] or [[kbd:][<leader> f f]]) -> [[cmd:][helm-find-files]]
|
|
- [[cmd:][execute-extended-command]] ([[kbd:][M-x]]) -> [[cmd:][helm-M-x]]
|
|
- [[cmd:][switch-to-buffer]] ([[kbd:][C-x b]] or [[kbd:][<leader> b b]]) -> [[cmd:][helm-buffers-list]]
|
|
- ...among others
|
|
|
|
No setup is required on your part. 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 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 |
|
|
|--------------------------------------+-------------------------------------------------------|
|
|
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project (~+helm/projectile-find-file~) |
|
|
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory (~helm-find-files~) |
|
|
| [[kbd:][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 [[https://github.com/BurntSushi/ripgrep][Ripgrep]].
|
|
|
|
*** Search
|
|
| Keybind | Description |
|
|
|-------------------+---------------------------------------------------------|
|
|
| [[kbd:][SPC s p]] | Search project (~+default/search-project~) |
|
|
| [[kbd:][SPC s P]] | Search another project (~+default/search-other-project~) |
|
|
| [[kbd:][SPC s d]] | Search this directory (~+default/search-cwd~) |
|
|
| [[kbd:][SPC s D]] | Search another directory (~+default/search-other-cwd~) |
|
|
|
|
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 [[doom-package: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]] ([[cmd:][swiper-isearch]])
|
|
- [[kbd:][SPC s S]] ([[cmd:][swiper-isearch-thing-at-point]])
|
|
- [[kbd:][SPC s b]] ([[cmd:][swiper]])
|
|
- ~:sw[iper] [QUERY]~
|
|
|
|
A [[doom-package: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 p t]] | List all TODO/FIXMEs in project |
|
|
| [[kbd:][SPC s b]] | Search the current buffer (~+default/search-buffer~) |
|
|
| [[kbd:][SPC s d]] | Search this directory (~+default/search-cwd~) |
|
|
| [[kbd:][SPC s D]] | Search another directory (~+default/search-other-cwd~) |
|
|
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
|
|
| [[kbd:][SPC s p]] | Search project (~+default/search-project~) |
|
|
| [[kbd:][SPC s P]] | Search another project (~+default/search-other-project~) |
|
|
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) (~+default/search-buffer~) |
|
|
|
|
*** Search
|
|
| Keybind | Description |
|
|
|-------------------+--------------------------------------------------------------------|
|
|
| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
|
|
| [[kbd:][SPC s b]] | Search the current buffer (~+default/search-buffer~) |
|
|
| [[kbd:][SPC s d]] | Search this directory (~+default/search-cwd~) |
|
|
| [[kbd:][SPC s D]] | Search another directory (~+default/search-other-cwd~) |
|
|
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
|
|
| [[kbd:][SPC s p]] | Search project (~+default/search-project~) |
|
|
| [[kbd:][SPC s P]] | Search another project (~+default/search-other-project~) |
|
|
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) (~+default/search-buffer~) |
|
|
|
|
* TODO Configuration
|
|
#+begin_quote
|
|
/This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
|
#+end_quote
|
|
|
|
** 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
|
|
[[var:][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:
|
|
#+begin_src emacs-lisp
|
|
;; add to $DOOMDIR/config.el
|
|
(with-eval-after-load 'helm
|
|
(add-to-list 'helm-completing-read-handlers-alist (cons #'foo nil)))
|
|
#+end_src
|
|
|
|
** 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:
|
|
#+begin_src emacs-lisp
|
|
;; add to $DOOMDIR/config.el
|
|
(with-eval-after-load 'helm
|
|
(setq helm-icons-provider 'treemacs))
|
|
#+end_src
|
|
|
|
* 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
|