302 lines
14 KiB
Org Mode
302 lines
14 KiB
Org Mode
← [[doom-module-index:][Back to module index]] ! [[doom-module-issues:::completion vertico][Issues]] ↖ [[doom-repo:tree/develop/modules/completion/vertico/][Github]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
|
|
--------------------------------------------------------------------------------
|
|
#+title: :completion vertico
|
|
#+subtitle: Tomorrow's search engine
|
|
#+created: July 25, 2021
|
|
#+since: 21.12.0 (#4664)
|
|
|
|
* Description :unfold:
|
|
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]].
|
|
|
|
It does this with several modular packages focused on enhancing the built-in
|
|
~completing-read~ interface, rather than replacing it with a parallel ecosystem
|
|
like [[doom-package:][ivy]] and [[doom-package:][helm]] do. The primary packages are:
|
|
|
|
- Vertico, which provides the vertical completion user interface
|
|
- Consult, which provides a suite of useful commands using ~completing-read~
|
|
- Embark, which provides a set of minibuffer actions
|
|
- Marginalia, which provides annotations to completion candidates
|
|
- Orderless, which provides better filtering methods
|
|
|
|
** Maintainers
|
|
- [[doom-user:][@iyefrat]]
|
|
|
|
[[doom-contrib-maintainer:][Become a maintainer?]]
|
|
|
|
** Module flags
|
|
- +icons ::
|
|
Add icons to =file= and =buffer= category completion selections.
|
|
|
|
** Packages
|
|
- [[doom-package:][all-the-icons-completion]] if [[doom-module:][+icons]]
|
|
- [[doom-package:][consult]]
|
|
- [[doom-package:][consult-flycheck]] if [[doom-module:][:checkers syntax]]
|
|
- [[doom-package:][embark]]
|
|
- [[doom-package:][embark-consult]]
|
|
- [[doom-package:][marginalia]]
|
|
- [[doom-package:][orderless]]
|
|
- [[doom-package:][vertico]]
|
|
- [[doom-package:][wgrep]]
|
|
|
|
** 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~
|
|
function, which is used by any function that requires completion. Due to this
|
|
the full scope of these packages is too large to cover here and you are
|
|
encouraged to go and read their excellent documentation. We will detail
|
|
Doom-specific additions:
|
|
|
|
** Vertico keybindings
|
|
When in an active Vertico completion session, the following doom added
|
|
keybindings are available:
|
|
|
|
| Keybind | Description |
|
|
|--------------+--------------------------------------------------|
|
|
| [[kbd:][C-k]] | (evil) Go to previous candidate |
|
|
| [[kbd:][C-j]] | (evil) Go to next candidate |
|
|
| [[kbd:][C-M-k]] | (evil) Go to previous group |
|
|
| [[kbd:][C-M-j]] | (evil) Go to next group |
|
|
| [[kbd:][C-;]] or [[kbd:][<leader> a]] | Open an ~embark-act~ menu to chose a useful action |
|
|
| [[kbd:][C-c C-;]] | export the current candidate list to a buffer |
|
|
| [[kbd:][C-SPC]] | Preview the current candidate |
|
|
|
|
~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
|
|
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
|
|
due to Marginalia annotations.
|
|
|
|
** Jump-to navigation
|
|
This module provides an interface to navigate within a project using
|
|
[[doom-package:][projectile]]:
|
|
|
|
https://assets.doomemacs.org/completion/vertico/projectile.png
|
|
|
|
| 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 provides interactive text search and replace using ripgrep.
|
|
|
|
| Keybind | Description |
|
|
|---------+--------------------------|
|
|
| [[kbd:][<leader> s p]] | Search project |
|
|
| [[kbd:][<leader> s P]] | Search another project |
|
|
| [[kbd:][<leader> s d]] | Search this directory |
|
|
| [[kbd:][<leader> s D]] | Search another directory |
|
|
|
|
https://assets.doomemacs.org/completion/vertico/search.png
|
|
|
|
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.
|
|
|
|
-----
|
|
|
|
On top of the usual Vertico keybindings, search commands also offer support for
|
|
exporting the current candidate list to an editable buffer [[kbd:][C-c C-e]]. After
|
|
editing the changes 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). It uses [[doom-package:][wgrep]] for grep searches,
|
|
[[doom-package:][wdired]] for file searches, and =occur= for buffer searches.
|
|
|
|
https://assets.doomemacs.org/completion/vertico/search-replace.png
|
|
|
|
** In-buffer searching
|
|
This module provides some in buffer searching bindings:
|
|
|
|
- [[kbd:][SPC s s]] (~isearch~)
|
|
- [[kbd:][SPC s S]] (~+vertico/search-symbol-at-point~ via ~consult-line~)
|
|
- [[kbd:][SPC s b]] (~consult-line~)
|
|
|
|
https://assets.doomemacs.org/completion/vertico/buffer-search.png
|
|
|
|
An ~occur-edit~ buffer can be opened from ~consult-line~ with [[kbd:][C-c C-e]].
|
|
|
|
** Vertico integration for various completing commands
|
|
*** General
|
|
| Keybind | Description |
|
|
|------------+-----------------------------|
|
|
| [[kbd:][M-x]], [[kbd:][SPC :]] | Enhanced M-x |
|
|
| [[kbd:][SPC ']] | Resume last Vertico 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 |
|
|
|
|
[[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
|
|
selecting a buffer from the third workspace by typing [[kbd:][3 SPC]] into the prompt, or
|
|
the last workspace by typing [[kbd:][0 SPC]].
|
|
|
|
[[kbd:][SPC f f]] and [[kbd:][SPC .]] support exporting to a [[kbd:][wdired]] buffer using [[kbd:][C-c C-e]].
|
|
|
|
*** 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) |
|
|
|
|
*** File Path Completion
|
|
Note that Emacs allows you to switch directories with shadow paths, for example
|
|
starting at =/foo/bar/baz=, typing =/foo/bar/baz/~/= will switch the searched
|
|
path to the home directory. For more information see ~substitute-in-file-name~
|
|
and ~file-name-shadow-mode~. This module will erase the "shadowed" portion of
|
|
the path from the minibuffer, so in the previous example the path will be reset
|
|
to =~/=.
|
|
|
|
** Consult
|
|
*** Multiple candidate search
|
|
This module modifies the default keybindings used in
|
|
~consult-completing-read-multiple~:
|
|
| Keybind | Description |
|
|
|---------+-------------------------------------------------------------|
|
|
| [[kbd:][TAB]] | Select or deselect current candidate |
|
|
| [[kbd:][RET]] | Enters selected candidates (also toggles current candidate) |
|
|
|
|
*** Async search commands
|
|
:PROPERTIES:
|
|
:ID: 4ab16bf0-f9e8-4798-8632-ee7b13d2291e
|
|
:END:
|
|
Consult async commands (e.g. ~consult-ripgrep~) will have a preceding separator
|
|
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
|
|
command until you type a second seperator, afterwhich the candidate list will be
|
|
filtered with Emacs instead (and can be filtered using [[doom-package:][orderless]], for example).
|
|
The specific seperator character can be changed by editing it, and might be
|
|
different if the initial input already contains =#=.
|
|
|
|
Note that grep-like async commands translate the input (between the first and
|
|
second =#=) to an Orderless-light expression: space separated inputs are all
|
|
matched in any order. If the grep backend does not support PCRE lookahead, it'll
|
|
only accept 3 space separated inputs to prevent long lookup times, and further
|
|
filtering should be done after a second =#=.
|
|
|
|
For more information [[https://github.com/minad/consult#asynchronous-search][see here]].
|
|
|
|
** Marginalia
|
|
| Keybind | Description |
|
|
|---------+---------------------------------|
|
|
| [[kbd:][M-A]] | Cycle between annotation levels |
|
|
|
|
Marginalia annotations for symbols (e.g. [[kbd:][SPC h f]] and [[kbd:][SPC h v]]) come with extra
|
|
information the nature of the symbol. For the meaning of the annotations see
|
|
~marginalia--symbol-class~.
|
|
|
|
** Orderless filtering
|
|
When using orderless to filter through candidates, the default behaviour is for
|
|
each space separated input to match the candidate as a regular expression or
|
|
literally.
|
|
|
|
Note that due to this style of matching, pressing tab does not expand the input
|
|
to the longest matching prefix (like shell completion), but rather uses the
|
|
first matched candidate as input. Filtering further is instead achieved by
|
|
pressing space and entering another input. In essence, when trying to match
|
|
=foobar.org=, instead of option 1., use option 2.:
|
|
|
|
1. (BAD) Enter ~foo TAB~, completes to =foobar.=, enter ~org RET~
|
|
2. (GOOD) Enter ~foo SPC org RET~
|
|
|
|
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:
|
|
| Input | Description |
|
|
|--------------+------------------------------------------|
|
|
| ~!foo~ | match without literal 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 only with literal input =foo= |
|
|
| ~~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:
|
|
|
|
** Vertico
|
|
Vertico provides several [[https://github.com/minad/vertico#extensions][extentions]] that can be used to extend it's interface
|
|
|
|
** Consult
|
|
Much of the behaviour of Consult commands can be changed with
|
|
~consult-customize~. The =vertico= module already does this, if you want to
|
|
override the module's modifications, do:
|
|
#+begin_src emacs-lisp
|
|
(setq consult--read-config nil)
|
|
(consult-customize ...)
|
|
#+end_src
|
|
|
|
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
|
|
an extent on non-consult commands as well.
|
|
|
|
** Marginalia
|
|
You can add more Marginalia annotation levels and change the existing ones by
|
|
editing ~marginalia-annotator-registry~
|
|
|
|
** Embark
|
|
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 by
|
|
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
|