:completion vertico

A search engine for deckers

1. Description

This module enhances the Emacs search and completion experience, and also provides a united interface for project search and replace, powered by 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 ivy and 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.

1.2. Module flags

Adds icons to file and buffer category completion selections.

1.4. Hacks

No hacks documented for this module.

2. Prerequisites

This module has no external prerequisites.

3. Usage

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:

3.1. Vertico keybindings

When in an active Vertico completion session, the following doom added keybindings are available:

Keybind Description
C-p Go to previous candidate
C-n Go to next candidate
C-k (evil) Go to previous candidate
C-j (evil) Go to next candidate
C-; or <leader> a Open an embark-act menu to chose a useful action
C-c C-; export the current candidate list to a buffer
C-SPC Preview the current candidate
C-M-k (evil) Go to previous candidate and preview.
C-M-j (evil) Go to next candidate and preview.

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 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.

3.2. Jump-to navigation

This module provides an interface to navigate within a project using projectile:

Keybind Description
SPC p f or SPC SPC Jump to file in project
SPC f f or SPC . Jump to file from current directory
SPC s i Jump to symbol in file

3.3. Project search & replace

This module provides interactive text search and replace using ripgrep.

Keybind Description
SPC s p Search project
SPC s P Search another project
SPC s d Search this directory
SPC s D Search another directory

Prefixing these keys with the universal argument (SPC u for evil users; 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 bang (!) 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 C-c C-e. After editing the changes can be committed with C-c C-c and aborted with C-c C-k (alternatively ZZ and ZQ, for evil users). It uses wgrep for grep searches, wdired for file searches, and occur for buffer searches.


3.4. In-buffer searching

This module provides some in buffer searching bindings:

  • <leader> s s (isearch)
  • <leader> s S (+vertico/search-symbol-at-point via consult-line)
  • <leader> s b (consult-line)

An occur-edit buffer can be opened from consult-line with C-c C-e.

3.5. Vertico integration for various completing commands

3.5.1. General

Keybind Description
M-x or SPC : Enhanced M-x
SPC Resume last Vertico session

3.5.2. Jump to files, buffers or projects

Evil keybind Non-evil keybind Description
SPC RET C-c s b Find bookmark
SPC f f or SPC . C-x C-f Browse from current directory
SPC p f or SPC SPC C-c p f Find file in project
SPC f r C-c f r Find recently opened file
SPC p p C-c p p Open another project
SPC b b or SPC , C-x b Switch to buffer in current workspace
SPC b B or SPC < C-x B Switch to buffer

<leader> b b and <leader> , support changing the workspace you’re selecting a buffer from via 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, or the last workspace by typing 0 SPC.

<leader> f f and <leader> . support exporting to a wdired buffer using C-c C-e.

3.5.3. Search

Keybind Description
<leader> p t List all TODO/FIXMEs in project
<leader> s b Search the current buffer
<leader> s d Search this directory
<leader> s D Search another directory
<leader> s i Search for symbol in current buffer
<leader> s p Search project
<leader> s P Search another project
<leader> s s Search the current buffer (incrementally)

3.6. Consult modifications

This module modifies the default keybindings used in consult-completing-read-multiple:

Keybind Description
TAB Select or deselect current candidate
RET Enters selected candidates (also toggles current candidate)

3.7. Marginalia

Keybind Description
M-A Cycle between annotation levels

3.8. 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 style dispatchers for more finegrained filtering, which you can use to further specify each space separated input in the following ways:

Input Description
!foo match without literal input foo
`bar or bar` match input bar as an initialism
=baz or baz= match only with literal input baz
~qux or qux~ match input qux with fuzzy/flex matching

4. Configuration

If you want to further configure this module, here are some good places to start:

  • Vertico provides several extentions that can be used to extend it’s interface
  • You can add more Marginalia annotation levels and change the existing ones by editing marginalia-annotator-registry
  • 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 through marginalia, and embark picks up on them.

5. Troubleshooting

There are no known problems with this module. Report one?

6. TODO Appendix

This module has no appendix yet. Write one?