emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
doomemacs/modules/completion/helm/README.org
Henrik Lissner 88bb045388
docs(*): replace all-the-icons with nerd-icons 
Also colorizes the leading icon in notices.
2023-09-16 20:19:11 +02:00

206 lines
9.8 KiB
Org Mode
Raw Blame History

#+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
(after! 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
(after! 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
Reference in a new issue View git blame Copy permalink