emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs(:completion): update READMEs to new format

Browse source
This commit is contained in:
Henrik Lissner 2021-10-16 01:21:31 +02:00 • committed by Henrik Lissner
parent b898fbe303
commit 11793094ba
7 changed files with 575 additions and 442 deletions
Download patch file Download diff file Expand all files Collapse all files

19
modules/completion/README.org
View file

@ -1,10 +1,19 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-changelog-search:::completion nil][Changelog]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]] ← [[doom-module-index:][Back to module index]] ↖ [[doom-module-source:completion][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
#+TITLE: :completion #+TITLE: :completion
#+DATE: July 29, 2021 #+CREATED: July 29, 2021
#+SINCE: v21.12.0 #+SINCE: 21.12.0
#+SETUPFILE: ../../docs/.setupfile.org
* Description * Description
These modules provide interfaces and frameworks completion, including code These modules provide interfaces and frameworks completion, including code
completion. completion.
* Frequently asked questions
** Should I choose Ivy, Helm, Vertico, or Ido?
:PROPERTIES:
:ID: 4f36ae11-1da8-4624-9c30-46b764e849fc
:END:
Vertico is Doom's default and comes highly recommended of the four. It is the
fastest, best integrated in Doom's ecosystem, and its module is the most
actively maintained of the four. It also has the cleanest codebase and ties into
native functionality already existing in Emacs, rather than reinventing the
wheel.

165
modules/completion/company/README.org
View file

@ -1,92 +1,99 @@
#+TITLE: completion/company ← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion company][Issues]] ↖ [[doom-module-source:completion/company][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
#+DATE: February 19, 2017 --------------------------------------------------------------------------------
#+SINCE: v2.0 #+TITLE: :completion company
#+STARTUP: inlineimages #+SUBTITLE: The ultimate code completion backend
#+CREATED: February 19, 2017
#+SINCE: 2.0.0
* Table of Contents :TOC_3:noexport: * Description :unfold:
- [[#description][Description]] This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. Many of Doom's
- [[#module-flags][Module Flags]] [[doom-module:][:lang]] modules require it for "intellisense" functionality.
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#code-completion][Code completion]]
- [[#vim-esque-omni-completion-prefix-c-x][Vim-esque omni-completion prefix (C-x)]]
- [[#configuration][Configuration]]
- [[#enable-company-backends-in-certain-modes][Enable company backend(s) in certain modes]]
- [[#troubleshooting][Troubleshooting]]
- [[#x-mode-doesnt-have-code-completion-support-or-requires-extra-setup][X-mode doesn't have code completion support or requires extra setup.]]
- [[#no-backends-or-the-incorrect-ones-have-been-registered-for-x-mode][No backends (or the incorrect ones) have been registered for X-mode.]]
* Description
This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. It is required
for code completion in many of Doom's :lang modules.
https://assets.doomemacs.org/completion/company/overlay.png https://assets.doomemacs.org/completion/company/overlay.png
** Module Flags ** Maintainers
+ =+childframe= Enables displaying completion candidates in a child frame, - [[doom-user:][@hlissner]]
rather than an overlay or tooltip (among with other UI enhancements). *This
requires GUI Emacs 26.1+ and is incompatible with the =+tng= flag*
+ =+tng= Enables completion using only ~TAB~. Pressing ~TAB~ will select the
next completion suggestion, while ~S-TAB~ will select the previous one. *This
is incompatible with the =+childframe= flag*
** Plugins [[doom-contrib-maintainer:][Become a maintainer?]]
+ [[https://github.com/company-mode/company-mode][company-mode]] ** Module flags
+ [[https://github.com/hlissner/emacs-company-dict][company-dict]] - +childframe ::
+ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=) Display completion candidates in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or
tooltip. *Requires GUI Emacs.*
- +tng ::
Invoke completion on [[kbd:][TAB]] instad of [[kbd:][C-SPC]]. When company is active, [[kbd:][TAB]] and
[[kbd:][S-TAB]] will navigate the completion candidates.
* Prerequisites ** Packages
This module has no direct prerequisites. - [[doom-package:][company-box]] if [[doom-module:][+childframe]]
- [[doom-package:][company-dict]]
- [[doom-package:][company-mode]]
However, some major modes may require additional setup for code completion to ** Hacks
work in them. Some major modes may have no completion support at all. Check that /No hacks documented for this module./
major mode's module's documentation for details.
** 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 no direct requirements, but some languages may have their own
requirements to fulfill before you get code completion in them (and some
languages may lack code completion support altogether). Run ~$ doom doctor~ to
find out if you're missing any dependencies.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
** Code completion ** Code completion
By default, completion is triggered after a short idle period or with the By default, completion is triggered after a short idle period or with the
=C-SPC= key. While the popup is visible, the following keys are available: [[kbd:][C-SPC]] key. While the popup is visible, the following keys are available:
| Keybind | Description | | Keybind | Description |
|---------+------------------------------------------| |---------+------------------------------------------|
| =C-n= | Go to next candidate | | [[kbd:][C-n]] | Go to next candidate |
| =C-p= | Go to previous candidate | | [[kbd:][C-p]] | Go to previous candidate |
| =C-j= | (evil) Go to next candidate | | [[kbd:][C-j]] | (evil) Go to next candidate |
| =C-k= | (evil) Go to previous candidate | | [[kbd:][C-k]] | (evil) Go to previous candidate |
| =C-h= | Display documentation (if available) | | [[kbd:][C-h]] | Display documentation (if available) |
| =C-u= | Move to previous page of candidates | | [[kbd:][C-u]] | Move to previous page of candidates |
| =C-d= | Move to next page of candidates | | [[kbd:][C-d]] | Move to next page of candidates |
| =C-s= | Filter candidates | | [[kbd:][C-s]] | Filter candidates |
| =C-S-s= | Search candidates with helm/ivy | | [[kbd:][C-S-s]] | Search candidates with helm/ivy |
| =C-SPC= | Complete common | | [[kbd:][C-SPC]] | Complete common |
| =TAB= | Complete common or select next candidate | | [[kbd:][TAB]] | Complete common or select next candidate |
| =S-TAB= | Select previous candidate | | [[kbd:][S-TAB]] | Select previous candidate |
** Vim-esque omni-completion prefix (C-x) ** Vim-esque omni-completion prefix (C-x)
In the spirit of Vim's omni-completion, the following insert mode keybinds are In the spirit of Vim's omni-completion, the following insert mode keybinds are
available to evil users to access specific company backends: available to evil users to access specific company backends:
| Keybind | Description |
|---------+-----------------------------------|
| [[kbd:][C-x C-]]​] | Complete etags |
| [[kbd:][C-x C-f]] | Complete file path |
| [[kbd:][C-x C-k]] | Complete from dictionary/keyword |
| [[kbd:][C-x C-l]] | Complete full line |
| [[kbd:][C-x C-o]] | Invoke complete-at-point function |
| [[kbd:][C-x C-n]] | Complete next symbol at point |
| [[kbd:][C-x C-p]] | Complete previous symbol at point |
| [[kbd:][C-x C-s]] | Complete snippet |
| [[kbd:][C-x s]] | Complete spelling suggestions |
| Keybind | Description | * TODO Configuration
|-----------+-----------------------------------| #+begin_quote
| =C-x C-]= | Complete etags | 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
| =C-x C-f= | Complete file path | #+end_quote
| =C-x C-k= | Complete from dictionary/keyword |
| =C-x C-l= | Complete full line |
| =C-x C-o= | Invoke complete-at-point function |
| =C-x C-n= | Complete next symbol at point |
| =C-x C-p= | Complete previous symbol at point |
| =C-x C-s= | Complete snippet |
| =C-x s= | Complete spelling suggestions |
* Configuration
** Enable company backend(s) in certain modes ** Enable company backend(s) in certain modes
The ~set-company-backend!~ function exists for setting ~company-backends~ The ~set-company-backend!~ function exists for setting ~company-backends~
buffer-locally in MODES, which is either a major-mode symbol, a minor-mode buffer-locally in MODES, which is either a major-mode symbol, a minor-mode
symbol, or a list of either. BACKENDS are prepended to ~company-backends~ for symbol, or a list of either. BACKENDS are prepended to ~company-backends~ for
those modes. those modes.
#+BEGIN_SRC emacs-lisp #+begin_src emacs-lisp
(after! js2-mode (after! js2-mode
(set-company-backend! 'js2-mode 'company-tide 'company-yasnippet)) (set-company-backend! 'js2-mode 'company-tide 'company-yasnippet))
@ -97,20 +104,18 @@ those modes.
(after! cc-mode (after! cc-mode
(set-company-backend! 'c-mode (set-company-backend! 'c-mode
'(:separate company-irony-c-headers company-irony))) '(:separate company-irony-c-headers company-irony)))
#+END_SRC #+end_src
To unset the backends for a particular mode, pass ~nil~ to it: To unset the backends for a particular mode, pass ~nil~ to it:
#+begin_src emacs-lisp
#+BEGIN_SRC emacs-lisp
(after! sh-script (after! sh-script
(set-company-backend! 'sh-mode nil)) (set-company-backend! 'sh-mode nil))
#+END_SRC #+end_src
* Troubleshooting * Troubleshooting
If code completion isn't working for you, consider the following common causes [[doom-report:][Report an issue?]]
before you file a bug report:
** X-mode doesn't have code completion support or requires extra setup. ** X-mode doesn't have code completion support or requires extra setup
There is no guarantee your language mode will have completion support. There is no guarantee your language mode will have completion support.
Some, like ~lua-mode~, don't have completion support in Emacs at all. Others may Some, like ~lua-mode~, don't have completion support in Emacs at all. Others may
@ -120,11 +125,19 @@ requires that you have a Robe server running (~M-x robe-start~).
Check the relevant module's documentation for this kind of information. Check the relevant module's documentation for this kind of information.
** No backends (or the incorrect ones) have been registered for X-mode. ** No backends (or the incorrect ones) have been registered for X-mode
Doom expects every mode to have an explicit list of company-backends (and as Doom expects every mode to have an explicit list of ~company-backends~ (and as
short a list as possible). This may mean you aren't getting all the completion short a list as possible). This may mean you aren't getting all the completion
you want or any at all. you want or any at all.
Check the value of ~company-backends~ (=SPC h v company-backends=) from that Check the value of ~company-backends~ ([[kbd:][SPC h v company-backends]]) from that mode
mode to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for details
details on changing what backends are available for that mode. on changing what backends are available for that mode.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

229
modules/completion/helm/README.org
View file

@ -1,169 +1,184 @@
#+TITLE: completion/helm ← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion helm][Issues]] ↖ [[doom-module-source:completion/helm][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
#+DATE: January 22, 2021 --------------------------------------------------------------------------------
#+SINCE: v2.0 #+TITLE: :completion helm
#+STARTUP: inlineimages #+SUBTITLE: A tank for hunting a house fly
#+CREATED: February 24, 2021
#+SINCE: 2.0.0
* Table of Contents :TOC_3:noexport: * Description :unfold:
- [[#description][Description]] This module provides Helm integration for a variety of Emacs commands, as well
- [[#module-flags][Module Flags]] as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep][Ripgrep]].
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#jump-to-navigation][Jump-to navigation]]
- [[#project-search--replace][Project search & replace]]
- [[#search][Search]]
- [[#replace][Replace]]
- [[#in-buffer-searching][In-buffer searching]]
- [[#helm-integration-for-various-completing-commands][Helm integration for various completing commands]]
- [[#general][General]]
- [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]]
- [[#search-1][Search]]
- [[#configuration][Configuration]]
- [[#icons][Icons]]
- [[#posframe][Posframe]]
- [[#troubleshooting][Troubleshooting]]
* Description ** Maintainers
This module provides Helm integration for a variety of Emacs commands, as well as /This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
a unified interface for project search and replace, powered by ripgrep.
** 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 #+begin_quote
I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
lighter, simpler and faster in many cases.
#+end_quote #+end_quote
Ivy is considered a first-class citizen in Doom, however it is still possible to use Helm if you so desire. ** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
** Module Flags * Installation
+ =+fuzzy= Enables fuzzy completion for Helm searches. [[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
+ =+childframe= Causes Helm to display in a floating child frame, above Emacs.
+ =+icons= Enables icons (supports both =all-the-icons= and =treemacs= icons)
** Plugins This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of
+ [[https://github.com/emacs-helm/helm][helm]] Doom itself, so you should already have it installed.
+ [[https://github.com/microamp/helm-rg][helm-rg]]
+ [[https://github.com/emacs-jp/helm-c-yasnippet][helm-c-yasnippet]]
+ [[https://github.com/tuhdo/helm-company][helm-company]]
+ [[https://github.com/emacs-helm/helm-describe-modes][helm-describe-modes]]
+ [[https://github.com/bbatsov/helm-projectile][helm-projectile]]
+ [[https://github.com/abo-abo/swiper-helm][helm-swiper]]
+ [[https://github.com/emacs-helm/helm-descbinds][helm-descbinds]]
+ [[https://github.com/PythonNut/helm-flx][helm-flx]]* (=+fuzzy=)
+ [[https://github.com/tumashu/helm-posframe][helm-posframe]]* (=+childframe=)
+ [[https://github.com/emacs-helm/helm-org][helm-org]]* (=:lang org=)
+ [[https://github.com/yyoncho/helm-icons][helm-icons]]* (=+icons=)
* Prerequisites Otherwise, Helm provides many commands to interface with a variety of programs
This module has no prerequisites. 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.
* Features * TODO Usage
Much like Ivy, Helm is a /large/ framework and as such #+begin_quote
covering everything is not in scope, however a number 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
of Doom-specific features are shown below: #+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 ** Jump-to navigation
Similar to Ivy, this module provides an interface to Similar to Ivy, this module provides an interface to navigate within a project
navigate within a project using =projectile=: using [[doom-package:][projectile]]:
| Keybind | Description | | Keybind | Description |
|------------------+-------------------------------------| |------------------+-------------------------------------|
| =SPC p f=, =SPC SPC= | Jump to file in project | | [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
| =SPC f f=, =SPC .= | Jump to file from current directory | | [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
| =SPC s i= | Jump to symbol in file | | [[kbd:][SPC s i]] | Jump to symbol in file |
** Project search & replace ** Project search & replace
This module also provides interacetive text search and replace using ripgrep This module also provides interactive text search and replace using ripgrep.
*** Search *** Search
| Keybind | Description | | Keybind | Description |
|---------+--------------------------| |---------+--------------------------|
| =SPC s p= | Search project | | [[kbd:][SPC s p]] | Search project |
| =SPC s P= | Search another project | | [[kbd:][SPC s P]] | Search another project |
| =SPC s d= | Search this directory | | [[kbd:][SPC s d]] | Search this directory |
| =SPC s D= | Search another directory | | [[kbd:][SPC s D]] | Search another directory |
Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u=
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 otherwise) changes the behavior of these commands, instructing the underlying
search engine to include ignored files. search engine to include ignored files.
This module also provides Ex Commands for evil users: This module also provides Ex Commands for evil users:
| Ex command | Description | | Ex command | Description |
|------------------------+------------------------------------------------------------------| |------------------------+------------------------------------------------------------------|
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
| ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) | | ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) |
The optional `!` is equivalent to the universal argument for the previous The optional ~!~ is equivalent to the universal argument for the previous
commands. commands.
*** Replace *** Replace
These keybindings are available while a search is active: 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 |
| Keybind | Description | 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).
| =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).
** In-buffer searching ** In-buffer searching
The =swiper= package provides an interactive buffer search powered by helm. It The [[doom-package:][swiper]] package provides an interactive buffer search powered by helm. It can
can be invoked with: 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]~
+ =SPC s s= (~swiper-isearch~) A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]].
+ =SPC s S= (~swiper-isearch-thing-at-point~)
+ =SPC s b= (~swiper~)
+ ~:sw[iper] [QUERY]~
A wgrep buffer can be opened from swiper with =C-c C-e=.
** Helm integration for various completing commands ** Helm integration for various completing commands
Helm also has a number of overrides for built-in functionality: Helm also has a number of overrides for built-in functionality:
*** General *** General
| Keybind | Description | | Keybind | Description |
|------------+---------------------------| |------------+---------------------------|
| =M-x=, =SPC := | Smarter, smex-powered M-x | | [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x |
| =SPC '= | Resume last ivy session | | [[kbd:][SPC ']] | Resume last ivy session |
*** Jump to files, buffers or projects *** Jump to files, buffers or projects
| Keybind | Description | | Keybind | Description |
|------------------+---------------------------------------| |------------------+---------------------------------------|
| =SPC RET= | Find bookmark | | [[kbd:][SPC RET]] | Find bookmark |
| =SPC f f=, =SPC .= | Browse from current directory | | [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
| =SPC p f=, =SPC SPC= | Find file in project | | [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
| =SPC f r= | Find recently opened file | | [[kbd:][SPC f r]] | Find recently opened file |
| =SPC p p= | Open another project | | [[kbd:][SPC p p]] | Open another project |
| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | | [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
| =SPC b B=, =SPC <= | Switch to buffer | | [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
*** Search *** Search
| Keybind | Description | | Keybind | Description |
|---------+-------------------------------------------| |---------+-------------------------------------------|
| =SPC p t= | List all TODO/FIXMEs in project | | [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
| =SPC s b= | Search the current buffer | | [[kbd:][SPC s b]] | Search the current buffer |
| =SPC s d= | Search this directory | | [[kbd:][SPC s d]] | Search this directory |
| =SPC s D= | Search another directory | | [[kbd:][SPC s D]] | Search another directory |
| =SPC s i= | Search for symbol in current buffer | | [[kbd:][SPC s i]] | Search for symbol in current buffer |
| =SPC s p= | Search project | | [[kbd:][SPC s p]] | Search project |
| =SPC s P= | Search another project | | [[kbd:][SPC s P]] | Search another project |
| =SPC s s= | Search the current buffer (incrementally) | | [[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
* Configuration
** Icons ** Icons
Icons are now included, and support 2 providers ([[https://github.com/domtronn/all-the-icons.el][all-the-icons]] and [[https://github.com/Alexander-Miller/treemacs][treemacs]]). Icon support is now included, through one of two providers: [[doom-package:][all-the-icons]] and
By default, to maintain consistency we use =all-the-icons=; however if you wish [[doom-package:][treemacs]]. By default, to maintain consistency we use [[doom-package:][all-the-icons]]; however if
to modify this you can do so using the below snippet: you wish to modify this you can do so using the below snippet:
#+begin_src emacs-lisp #+begin_src emacs-lisp
(after! helm (after! helm
(setq helm-icons-provider 'treemacs)) (setq helm-icons-provider 'treemacs))
#+end_src #+end_src
** Posframe ** TODO Posframe
* Troubleshooting * 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

58
modules/completion/ido/README.org Normal file
View file

@ -0,0 +1,58 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion ido][Issues]] ↖ [[doom-module-source:completion/ido][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :completion ido
#+SUBTITLE: A foil for other search engines
#+CREATED: October 13, 2021
#+SINCE: 21.12.0
* Description :unfold:
Interactive DO things. The completion engine that is /mostly/ built-into Emacs.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][crm-custom]]
- [[doom-package:][flx-ido]]
- [[doom-package:][ido-completing-read+]]
- [[doom-package:][ido-sort-mtime]]
- [[doom-package:][ido-vertical-mode]]
** Hacks
/No hacks documented for this module./
** 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 no external requirements./
* Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* 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]].
* Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

4
modules/completion/ido/config.el
View file

@ -9,7 +9,6 @@
(use-package! ido (use-package! ido
:hook (doom-first-input . ido-mode) :hook (doom-first-input . ido-mode)
:hook (ido-mode . ido-everywhere)
:hook (ido-mode . ido-ubiquitous-mode) :hook (ido-mode . ido-ubiquitous-mode)
:preface :preface
;; HACK `ido' is a really old package. It defines `ido-mode' manually and ;; HACK `ido' is a really old package. It defines `ido-mode' manually and
@ -29,7 +28,8 @@
ido-confirm-unique-completion t ido-confirm-unique-completion t
ido-case-fold t ido-case-fold t
ido-create-new-buffer 'always ido-create-new-buffer 'always
ido-enable-flex-matching t) ido-enable-flex-matching t
ido-everywhere t)
(map! :map (ido-common-completion-map ido-file-completion-map) (map! :map (ido-common-completion-map ido-file-completion-map)
"C-w" #'ido-delete-backward-word-updir "C-w" #'ido-delete-backward-word-updir

228
modules/completion/ivy/README.org
View file

@ -1,28 +1,11 @@
#+TITLE: completion/ivy ← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion ivy][Issues]] ↖ [[doom-module-source:completion/ivy][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
#+DATE: February 13, 2017 --------------------------------------------------------------------------------
#+SINCE: v2.0 #+TITLE: :completion ivy
#+STARTUP: inlineimages #+SUBTITLE: Yesterday's lightest search engine
#+CREATED: February 13, 2017
#+SINCE: 2.0.0
* Table of Contents :TOC_3:noexport: * Description :unfold:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#jump-to-navigation][Jump-to navigation]]
- [[#project-search--replace][Project search & replace]]
- [[#in-buffer-searching][In-buffer searching]]
- [[#ivy-integration-for-various-completing-commands][Ivy integration for various completing commands]]
- [[#general][General]]
- [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]]
- [[#search][Search]]
- [[#configuration][Configuration]]
- [[#enable-fuzzynon-fuzzy-search-for-specific-commands][Enable fuzzy/non-fuzzy search for specific commands]]
- [[#change-the-position-of-the-ivy-childframe][Change the position of the ivy childframe]]
- [[#troubleshooting][Troubleshooting]]
* Description
This module provides Ivy integration for a variety of Emacs commands, as well as This module provides Ivy 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]]. a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]].
@ -31,63 +14,87 @@ I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's
lighter, simpler and faster in many cases. lighter, simpler and faster in many cases.
#+end_quote #+end_quote
** Module Flags ** Maintainers
+ =+fuzzy= Enables fuzzy completion for Ivy searches. /This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
+ =+prescient= Enables prescient filtering and sorting for Ivy searches.
+ =+childframe= Causes Ivy to display in a floating child frame, above Emacs.
+ =+icons= Enables file icons for switch-{buffer,project}/find-file counsel
commands.
** Plugins ** Module flags
+ [[https://github.com/abo-abo/swiper][ivy]] - +childframe ::
+ [[https://github.com/abo-abo/swiper][counsel]] Display Ivy windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires
+ [[https://github.com/ericdanan/counsel-projectile][counsel-projectile]] GUI Emacs.*
+ [[https://github.com/abo-abo/swiper][swiper]] - +fuzzy ::
+ [[https://github.com/abo-abo/swiper][ivy-hydra]] Enable fuzzy completion for Ivy searches.
+ [[https://github.com/yevgnen/ivy-rich][ivy-rich]] - +icons ::
+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] Enable file icons for switch-{buffer,project}/find-file commands.
+ [[https://github.com/DarwinAwardWinner/amx][amx]] - +prescient ::
+ [[https://github.com/lewang/flx][flx]]* (=+fuzzy=) Enable prescient filtering and sorting for Ivy searches.
+ [[https://github.com/raxod502/prescient.el][prescient]]* (=+prescient=)
+ [[https://github.com/tumashu/ivy-posframe][ivy-posframe]]* (=+childframe=) ** Packages
+ [[https://github.com/asok/all-the-icons-ivy][all-the-icons-ivy]]* (=+icons=) - [[doom-package:][all-the-icons-ivy]]* if [[doom-module:][+icons]]
- [[doom-package:][amx]]
- [[doom-package:][counsel]]
- [[doom-package:][counsel-projectile]]
- [[doom-package:][flx]]* if [[doom-module:][+fuzzy]]
- [[doom-package:][ivy]]
- [[doom-package:][ivy-hydra]]
- [[doom-package:][ivy-posframe]]* if [[doom-module:][+childframe]]
- [[doom-package:][ivy-rich]]
- [[doom-package:][prescient]]* if [[doom-module:][+prescient]]
- [[doom-package:][swiper]]
- [[doom-package:][wgrep]]
** Hacks ** Hacks
+ Functions with ivy/counsel equivalents have been globally remapped (like - Functions with ivy/counsel equivalents have been globally remapped (like
~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will ~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will
invoke ~counsel-find-file~ instead. invoke ~counsel-find-file~ instead.
+ ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex - ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex
command) command)
* Prerequisites ** TODO Changelog
This module has no prerequisites. # This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Features * Installation
Ivy and its ilk are large plugins. Covering everything about them is outside of [[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
this documentation's scope, so only Doom-specific Ivy features are listed here:
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, Counsel (an Ivy plugin) 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
[[doom-package:][ivy]] is a /large/ framework for completing things. 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 ** Jump-to navigation
Inspired by Sublime Text's jump-to-anywhere, CtrlP/Unite in Vim, and Textmate's Inspired by Sublime Text's jump-to-anywhere, CtrlP/Unite in Vim, and Textmate's
Command-T, this module provides similar functionality by bringing ~projectile~ Command-T, this module provides similar functionality by bringing [[doom-package:][projectile]] and
and ~ivy~ together. [[doom-package:][ivy]] together.
https://assets.doomemacs.org/completion/ivy/projectile.png https://assets.doomemacs.org/completion/ivy/projectile.png
| Keybind | Description | | Keybind | Description |
|----------------------+-------------------------------------| |------------------+-------------------------------------|
| =SPC p f=, =SPC SPC= | Jump to file in project | | [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
| =SPC f f=, =SPC .= | Jump to file from current directory | | [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
| =SPC s i= | Jump to symbol in file | | [[kbd:][SPC s i]] | Jump to symbol in file |
** Project search & replace ** Project search & replace
This module provides interactive text search and replace using ripgrep. This module provides interactive text search and replace using ripgrep.
| Keybind | Description | | Keybind | Description |
|-----------+--------------------------| |---------+--------------------------|
| =SPC s p= | Search project | | [[kbd:][SPC s p]] | Search project |
| =SPC s P= | Search another project | | [[kbd:][SPC s P]] | Search another project |
| =SPC s d= | Search this directory | | [[kbd:][SPC s d]] | Search this directory |
| =SPC s D= | Search another directory | | [[kbd:][SPC s D]] | Search another directory |
https://assets.doomemacs.org/completion/ivy/search.png https://assets.doomemacs.org/completion/ivy/search.png
@ -96,7 +103,6 @@ otherwise) changes the behavior of these commands, instructing the underlying
search engine to include ignored files. search engine to include ignored files.
This module also provides Ex Commands for evil users: This module also provides Ex Commands for evil users:
| Ex command | Description | | Ex command | Description |
|------------------------+------------------------------------------------------------------| |------------------------+------------------------------------------------------------------|
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
@ -108,65 +114,79 @@ commands.
----- -----
These keybindings are available while a search is active: 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 |
| Keybind | Description | 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).
| =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).
https://assets.doomemacs.org/completion/ivy/search-replace.png https://assets.doomemacs.org/completion/ivy/search-replace.png
** In-buffer searching ** In-buffer searching
The =swiper= package provides an interactive buffer search powered by ivy. It The [[doom-package:][swiper]] package provides an interactive buffer search powered by ivy. It
can be invoked with: can be invoked with:
+ =SPC s s= (~swiper-isearch~) - [[kbd:][SPC s s]] (~swiper-isearch~)
+ =SPC s S= (~swiper-isearch-thing-at-point~) - [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~)
+ =SPC s b= (~swiper~) - [[kbd:][SPC s b]] (~swiper~)
+ ~:sw[iper] [QUERY]~ - ~:sw[iper] [QUERY]~
https://assets.doomemacs.org/completion/ivy/swiper.png https://assets.doomemacs.org/completion/ivy/swiper.png
A wgrep buffer can be opened from swiper with =C-c C-e=. A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]].
** Ivy integration for various completing commands ** Ivy integration for various completing commands
*** General *** General
| Keybind | Description | | Keybind | Description |
|----------------+---------------------------| |------------+---------------------------|
| =M-x=, =SPC := | Smarter, smex-powered M-x | | [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x |
| =SPC '= | Resume last ivy session | | [[kbd:][SPC ']] | Resume last ivy session |
*** Jump to files, buffers or projects *** Jump to files, buffers or projects
| Keybind | Description | | Keybind | Description |
|----------------------+---------------------------------------| |------------------+---------------------------------------|
| =SPC RET= | Find bookmark | | [[kbd:][SPC RET]] | Find bookmark |
| =SPC f f=, =SPC .= | Browse from current directory | | [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
| =SPC p f=, =SPC SPC= | Find file in project | | [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
| =SPC f r= | Find recently opened file | | [[kbd:][SPC f r]] | Find recently opened file |
| =SPC p p= | Open another project | | [[kbd:][SPC p p]] | Open another project |
| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | | [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
| =SPC b B=, =SPC <= | Switch to buffer | | [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
*** Search *** Search
| Keybind | Description | | Keybind | Description |
|-----------+-------------------------------------------| |---------+-------------------------------------------|
| =SPC p t= | List all TODO/FIXMEs in project | | [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
| =SPC s b= | Search the current buffer | | [[kbd:][SPC s b]] | Search the current buffer |
| =SPC s d= | Search this directory | | [[kbd:][SPC s d]] | Search this directory |
| =SPC s D= | Search another directory | | [[kbd:][SPC s D]] | Search another directory |
| =SPC s i= | Search for symbol in current buffer | | [[kbd:][SPC s i]] | Search for symbol in current buffer |
| =SPC s p= | Search project | | [[kbd:][SPC s p]] | Search project |
| =SPC s P= | Search another project | | [[kbd:][SPC s P]] | Search another project |
| =SPC s s= | Search the current buffer (incrementally) | | [[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
* Configuration
** TODO Enable fuzzy/non-fuzzy search for specific commands ** TODO Enable fuzzy/non-fuzzy search for specific commands
** TODO Change the position of the ivy childframe ** TODO Change the position of the ivy childframe
* TODO Troubleshooting * TODO 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

314
modules/completion/vertico/README.org
View file

@ -1,73 +1,67 @@
#+TITLE: completion/vertico ← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::completion vertico][Issues]] ↖ [[doom-module-source:completion/vertico][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
#+DATE: July 25, 2021 --------------------------------------------------------------------------------
#+SINCE: v3.0.0 #+TITLE: :completion vertico
#+STARTUP: inlineimages #+SUBTITLE: Tomorrow's search engine
#+CREATED: August 17, 2021
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport: * Description :unfold:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#vertico-keybindings][Vertico keybindings]]
- [[#jump-to-navigation][Jump-to navigation]]
- [[#project-search--replace][Project search & replace]]
- [[#in-buffer-searching][In-buffer searching]]
- [[#vertico-integration-for-various-completing-commands][Vertico integration for various completing commands]]
- [[#general][General]]
- [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]]
- [[#search][Search]]
- [[#file-path-completion][File Path Completion]]
- [[#consult][Consult]]
- [[#multiple-candidate-search][Multiple candidate search]]
- [[#async-search-commands][Async search commands]]
- [[#marginalia][Marginalia]]
- [[#orderless-filtering][Orderless filtering]]
- [[#configuration][Configuration]]
- [[#vertico][Vertico]]
- [[#consult-1][Consult]]
- [[#marginalia-1][Marginalia]]
- [[#embark][Embark]]
* Description
This module enhances the Emacs search and completion experience, and also This module enhances the Emacs search and completion experience, and also
provides a united interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]]. provides a united interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]].
It does this with several modular packages focused on enhancing the built-in It does this with several modular packages focused on enhancing the built-in
~completing-read~ interface, rather than replacing it with a parallel ecosystem ~completing-read~ interface, rather than replacing it with a parallel ecosystem
like =ivy= and =helm= do. The primary packages are: like [[doom-package:][ivy]] and [[doom-package:][helm]] do. The primary packages are:
+ Vertico, which provides the vertical completion user interface - Vertico, which provides the vertical completion user interface
+ Consult, which provides a suite of useful commands using ~completing-read~ - Consult, which provides a suite of useful commands using ~completing-read~
+ Embark, which provides a set of minibuffer actions - Embark, which provides a set of minibuffer actions
+ Marginalia, which provides annotations to completion candidates - Marginalia, which provides annotations to completion candidates
+ Orderless, which provides better filtering methods - Orderless, which provides better filtering methods
** Maintainers ** Maintainers
+ @iyefrat - [[doom-user:][@iyefrat]]
** Module Flags [[doom-contrib-maintainer:][Become a maintainer?]]
+ =+icons= Adds icons to =file= and =buffer= category completion selections.
** Plugins ** Module flags
+ [[https://github.com/minad/vertico][vertico]] - +icons ::
+ [[https://github.com/minad/consult][consult]] Add icons to =file= and =buffer= category completion selections.
+ [[https://github.com/oantolin/embark/][embark]]
+ [[https://github.com/oantolin/embark/][embark-consult]]
+ [[https://github.com/minad/marginalia][marginalia]]
+ [[https://github.com/oantolin/orderless][orderless]]
+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]]
+ [[https://github.com/minad/consult/][consult-flycheck]] (=:checkers syntax=)
+ [[https://github.com/iyefrat/all-the-icons-completion][all-the-icons-completion]] (=+icons=)
* Prerequisites ** Packages
Some of the advanced filtering features in async =consult= commands require - [[doom-package:][all-the-icons-completion]] if [[doom-module:][+icons]]
=grep= and =ripgrep= to be built with support for [[https://www.pcre.org/][PCRE]] lookahead, see [[#async-search-commands][Async - [[doom-package:][consult]]
search commands]] for more information. You can check if this is true for your - [[doom-package:][consult-flycheck]] if [[doom-module:][:checkers syntax]]
machine by running ~doom doctor~. - [[doom-package:][embark]]
- [[doom-package:][embark-consult]]
- [[doom-package:][marginalia]]
- [[doom-package:][orderless]]
- [[doom-package:][vertico]]
- [[doom-package:][wgrep]]
* Features ** Hacks
/No hacks documented for this module./
** 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]] (built with [[https://www.pcre.org/][PCRE]] support; run ~$
doom doctor~ to determine if your build meets this requirement), which is a hard
dependency of Doom itself, so you should already have it installed.
Otherwise, Consult (a plugin this module installs) 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
The packages in this module modify and use the built-in ~completing-read~ The packages in this module modify and use the built-in ~completing-read~
function, which is used by any function that requires completion. Due to this function, which is used by any function that requires completion. Due to this
@ -79,117 +73,116 @@ Doom-specific additions:
When in an active Vertico completion session, the following doom added When in an active Vertico completion session, the following doom added
keybindings are available: keybindings are available:
| Keybind | Description | | Keybind | Description |
|-----------------------+----------------------------------------------------| |--------------+--------------------------------------------------|
| =C-k= | (evil) Go to previous candidate | | [[kbd:][C-k]] | (evil) Go to previous candidate |
| =C-j= | (evil) Go to next candidate | | [[kbd:][C-j]] | (evil) Go to next candidate |
| =C-M-k= | (evil) Go to previous group | | [[kbd:][C-M-k]] | (evil) Go to previous group |
| =C-M-j= | (evil) Go to next group | | [[kbd:][C-M-j]] | (evil) Go to next group |
| =C-;= or =<leader> a= | Open an ~embark-act~ menu to chose a useful action | | [[kbd:][C-;]] or [[kbd:][<leader> a]] | Open an ~embark-act~ menu to chose a useful action |
| =C-c C-;= | export the current candidate list to a buffer | | [[kbd:][C-c C-;]] | export the current candidate list to a buffer |
| =C-SPC= | Preview the current candidate | | [[kbd:][C-SPC]] | Preview the current candidate |
~embark-act~ will prompt you with a =which-key= menu with useful commands on the ~embark-act~ will prompt you with a =which-key= menu with useful commands on the
selected candidate or candidate list, depending on the completion category. Note selected candidate or candidate list, depending on the completion category. Note
that you can press =C-h= instead of choosing a command to filter through the that you can press [[kbd:][C-h]] instead of choosing a command to filter through the
options with a Vertico buffer, that also has slightly more detailed descriptions options with a Vertico buffer, that also has slightly more detailed descriptions
due to Marginalia annotations. due to Marginalia annotations.
** Jump-to navigation ** Jump-to navigation
This module provides an interface to navigate within a project using This module provides an interface to navigate within a project using
=projectile=: [[doom-package:][projectile]]:
https://assets.doomemacs.org/completion/vertico/projectile.png https://assets.doomemacs.org/completion/vertico/projectile.png
| Keybind | Description | | Keybind | Description |
|----------------------+-------------------------------------| |------------------+-------------------------------------|
| =SPC p f=, =SPC SPC= | Jump to file in project | | [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
| =SPC f f=, =SPC .= | Jump to file from current directory | | [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
| =SPC s i= | Jump to symbol in file | | [[kbd:][SPC s i]] | Jump to symbol in file |
** Project search & replace ** Project search & replace
This module provides interactive text search and replace using ripgrep. This module provides interactive text search and replace using ripgrep.
| Keybind | Description | | Keybind | Description |
|-----------+--------------------------| |---------+--------------------------|
| =SPC s p= | Search project | | [[kbd:][<leader> s p]] | Search project |
| =SPC s P= | Search another project | | [[kbd:][<leader> s P]] | Search another project |
| =SPC s d= | Search this directory | | [[kbd:][<leader> s d]] | Search this directory |
| =SPC s D= | Search another directory | | [[kbd:][<leader> s D]] | Search another directory |
https://assets.doomemacs.org/completion/vertico/search.png https://assets.doomemacs.org/completion/vertico/search.png
Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u= 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 otherwise) changes the behavior of these commands, instructing the underlying
search engine to include ignored files. search engine to include ignored files.
This module also provides Ex Commands for evil users: This module also provides Ex Commands for evil users:
| Ex command | Description |
| Ex command | Description | |----------------------+----------------------------------------------------------------|
|------------------------+------------------------------------------------------------------|
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
| ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) | | ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) |
The optional `!` is equivalent to the universal argument for the previous The optional ~!~ is equivalent to the universal argument for the previous
commands. commands.
----- -----
On top of the usual Vertico keybindings, search commands also offer support for On top of the usual Vertico keybindings, search commands also offer support for
exporting the current candidate list to an editable buffer =C-c C-e=. After exporting the current candidate list to an editable buffer [[kbd:][C-c C-e]]. After
editing the changes can be committed with =C-c C-c= and aborted with =C-c C-k= editing the changes can be committed with [[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]]
(alternatively =ZZ= and =ZQ=, for evil users). It uses =wgrep= for grep (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). It uses [[doom-package:][wgrep]] for grep searches,
searches, =wdired= for file searches, and =occur= for buffer searches. [[doom-package:][wdired]] for file searches, and =occur= for buffer searches.
https://assets.doomemacs.org/completion/vertico/search-replace.png https://assets.doomemacs.org/completion/vertico/search-replace.png
** In-buffer searching ** In-buffer searching
This module provides some in buffer searching bindings: This module provides some in buffer searching bindings:
+ =SPC s s= (~isearch~) - [[kbd:][SPC s s]] (~isearch~)
+ =SPC s S= (~+vertico/search-symbol-at-point~ via ~consult-line~) - [[kbd:][SPC s S]] (~+vertico/search-symbol-at-point~ via ~consult-line~)
+ =SPC s b= (~consult-line~) - [[kbd:][SPC s b]] (~consult-line~)
https://assets.doomemacs.org/completion/vertico/buffer-search.png https://assets.doomemacs.org/completion/vertico/buffer-search.png
An ~occur-edit~ buffer can be opened from ~consult-line~ with =C-c C-e=. An ~occur-edit~ buffer can be opened from ~consult-line~ with [[kbd:][C-c C-e]].
** Vertico integration for various completing commands ** Vertico integration for various completing commands
*** General *** General
| Keybind | Description | | Keybind | Description |
|----------------+-----------------------------| |------------+-----------------------------|
| =M-x=, =SPC := | Enhanced M-x | | [[kbd:][M-x]], [[kbd:][SPC :]] | Enhanced M-x |
| =SPC '= | Resume last Vertico session | | [[kbd:][SPC ']] | Resume last Vertico session |
*** Jump to files, buffers or projects *** Jump to files, buffers or projects
| Keybind | Description | | Keybind | Description |
|----------------------+---------------------------------------| |------------------+---------------------------------------|
| =SPC RET= | Find bookmark | | [[kbd:][SPC RET]] | Find bookmark |
| =SPC f f=, =SPC .= | Browse from current directory | | [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
| =SPC p f=, =SPC SPC= | Find file in project | | [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
| =SPC f r= | Find recently opened file | | [[kbd:][SPC f r]] | Find recently opened file |
| =SPC p p= | Open another project | | [[kbd:][SPC p p]] | Open another project |
| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | | [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
| =SPC b B=, =SPC <= | Switch to buffer | | [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
=SPC b b= and =SPC ,= support changing the workspace you're selecting a buffer from [[kbd:][SPC b b]] and [[kbd:][SPC ,]] support changing the workspace you're selecting a buffer from
via [[https://github.com/minad/consult#narrowing-and-grouping][Consult narrowing]], e.g. if you're on the first workspace, you can switch to via [[https://github.com/minad/consult#narrowing-and-grouping][Consult narrowing]], e.g. if you're on the first workspace, you can switch to
selecting a buffer from the third workspace by typing =3 SPC= into the prompt, selecting a buffer from the third workspace by typing [[kbd:][3 SPC]] into the prompt, or
or the last workspace by typing =0 SPC=. the last workspace by typing [[kbd:][0 SPC]].
=SPC f f= and =SPC .= support exporting to a =wdired= buffer using =C-c C-e=. [[kbd:][SPC f f]] and [[kbd:][SPC .]] support exporting to a [[kbd:][wdired]] buffer using [[kbd:][C-c C-e]].
*** Search *** Search
| Keybind | Description | | Keybind | Description |
|-----------+-------------------------------------------| |---------+-------------------------------------------|
| =SPC p t= | List all TODO/FIXMEs in project | | [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
| =SPC s b= | Search the current buffer | | [[kbd:][SPC s b]] | Search the current buffer |
| =SPC s d= | Search this directory | | [[kbd:][SPC s d]] | Search this directory |
| =SPC s D= | Search another directory | | [[kbd:][SPC s D]] | Search another directory |
| =SPC s i= | Search for symbol in current buffer | | [[kbd:][SPC s i]] | Search for symbol in current buffer |
| =SPC s p= | Search project | | [[kbd:][SPC s p]] | Search project |
| =SPC s P= | Search another project | | [[kbd:][SPC s P]] | Search another project |
| =SPC s s= | Search the current buffer (incrementally) | | [[kbd:][SPC s s]] | Search the current buffer (incrementally) |
*** File Path Completion *** File Path Completion
Note that Emacs allows you to switch directories with shadow paths, for example Note that Emacs allows you to switch directories with shadow paths, for example
@ -205,17 +198,20 @@ This module modifies the default keybindings used in
~consult-completing-read-multiple~: ~consult-completing-read-multiple~:
| Keybind | Description | | Keybind | Description |
|---------+-------------------------------------------------------------| |---------+-------------------------------------------------------------|
| =TAB= | Select or deselect current candidate | | [[kbd:][TAB]] | Select or deselect current candidate |
| =RET= | Enters selected candidates (also toggles current candidate) | | [[kbd:][RET]] | Enters selected candidates (also toggles current candidate) |
*** Async search commands *** Async search commands
:PROPERTIES:
:ID: 4ab16bf0-f9e8-4798-8632-ee7b13d2291e
:END:
Consult async commands (e.g. ~consult-ripgrep~) will have a preceding separator Consult async commands (e.g. ~consult-ripgrep~) will have a preceding separator
character (usually =#=) before the search input. This is known as the =perl= character (usually ~#~) before the search input. This is known as the =perl=
splitting style. Input typed after the separator will be fed to the async splitting style. Input typed after the separator will be fed to the async
command until you type a second seperator, afterwhich the candidate list will be command until you type a second seperator, afterwhich the candidate list will be
filtered with Emacs instead (and can be filtered using =orderless=, for filtered with Emacs instead (and can be filtered using [[doom-package:][orderless]], for example).
example). The specific seperator character can be changed by editing it, and The specific seperator character can be changed by editing it, and might be
might be different if the initial input already contains =#=. different if the initial input already contains =#=.
Note that grep-like async commands translate the input (between the first and Note that grep-like async commands translate the input (between the first and
second =#=) to an Orderless-light expression: space separated inputs are all second =#=) to an Orderless-light expression: space separated inputs are all
@ -228,11 +224,11 @@ For more information [[https://github.com/minad/consult#asynchronous-search][see
** Marginalia ** Marginalia
| Keybind | Description | | Keybind | Description |
|---------+---------------------------------| |---------+---------------------------------|
| =M-A= | Cycle between annotation levels | | [[kbd:][M-A]] | Cycle between annotation levels |
Marginalia annotations for symbols (e.g. =SPC h f= and =SPC h v=) come with Marginalia annotations for symbols (e.g. [[kbd:][SPC h f]] and [[kbd:][SPC h v]]) come with extra
extra information the nature of the symbol. For the meaning of the annotations information the nature of the symbol. For the meaning of the annotations see
see ~marginalia--symbol-class~. ~marginalia--symbol-class~.
** Orderless filtering ** Orderless filtering
When using orderless to filter through candidates, the default behaviour is for When using orderless to filter through candidates, the default behaviour is for
@ -245,40 +241,62 @@ first matched candidate as input. Filtering further is instead achieved by
pressing space and entering another input. In essence, when trying to match pressing space and entering another input. In essence, when trying to match
=foobar.org=, instead of option 1., use option 2.: =foobar.org=, instead of option 1., use option 2.:
1. (BAD) Enter =foo TAB=, completes to =foobar.=, enter =org RET= 1. (BAD) Enter ~foo TAB~, completes to =foobar.=, enter ~org RET~
2. (GOOD) Enter =foo SPC org RET= 2. (GOOD) Enter ~foo SPC org RET~
Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more finegrained filtering, which Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more fine-grained filtering, which
you can use to further specify each space separated input in the following ways: you can use to further specify each space separated input in the following ways:
| Input | Description | | Input | Description |
|------------------+----------------------------------------------| |--------------+------------------------------------------|
| =!foo= | match without literal input =foo= | | ~!foo~ | match without literal input =foo= |
| =%foo= or =foo%= | perform ~char-fold-to-regexp~ on input =foo= | | ~%foo~ or ~foo%~ | perform ~char-fold-to-regexp~ on input =foo= |
| =`foo= or =foo`= | match input =foo= as an initialism | | ~`foo~ or ~foo`~ | match input =foo= as an initialism |
| ==foo= or =foo== | match only with literal input =foo= | | ~=foo~ or ~foo=~ | match only with literal input =foo= |
| =~foo= or =foo~= | match input =foo= with fuzzy/flex matching | | ~~foo~ or ~foo~~ | match input =foo= with fuzzy/flex matching |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
If you want to further configure this module, here are some good places to
start:
* Configuration
If you want to further configure this module, here are some good places to start:
** Vertico ** Vertico
Vertico provides several [[https://github.com/minad/vertico#extensions][extentions]] that can be used to extend it's interface Vertico provides several [[https://github.com/minad/vertico#extensions][extentions]] that can be used to extend it's interface
** Consult ** Consult
Much of the behaviour of Consult commands can be changed with Much of the behaviour of Consult commands can be changed with
~consult-customize~. The =vertico= module already does this, if you want to ~consult-customize~. The =vertico= module already does this, if you want to
override the module's modifications, do: override the module's modifications, do:
#+begin_src emacs-lisp #+begin_src emacs-lisp
(setq consult--read-config nil) (setq consult--read-config nil)
(consult-customize (consult-customize ...)
;...
)
#+end_src #+end_src
If you are changing the preview key (set to =C-SPC=), remember to change the
If you are changing the preview key (set to [[kbd:][C-SPC]]), remember to change the
binding on ~vertico-map~ as well, as the binding there gets previews to work to binding on ~vertico-map~ as well, as the binding there gets previews to work to
an extent on non-consult commands as well. an extent on non-consult commands as well.
** Marginalia ** Marginalia
You can add more Marginalia annotation levels and change the existing ones by You can add more Marginalia annotation levels and change the existing ones by
editing ~marginalia-annotator-registry~ editing ~marginalia-annotator-registry~
** Embark ** Embark
You can change the available commands in Embark for category ~$cat~ by editing You can change the available commands in Embark for category ~$cat~ by editing
~embark-$cat-map~, and even add new categories. Note that you add categories ~embark-$cat-map~, and even add new categories. Note that you add categories by
by defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them. defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them.
* 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