doomemacs/modules/completion/selectrum

completion/selectrum

• Description
  • Module Flags
  • Plugins
• Prerequisites
• Features
  • Jump-to navigation
  • Project search & replace
  • In-buffer searching
  • Selectrum integration for various completing commands
    • General
    • Jump to files, buffers or projects
    • Search
  • Orderless filtering

Description

This module provides Selectrum integration for a variety of Emacs commands, as well as a unified interface for project search and replace, powered by ripgrep.

TODO

Module Flags

• +prescient Enables prescient filtering and sorting for Selectrum searches instead of orderless.
• +icons Adds icons to file and buffer category completion selections.

Plugins

vertico (+vertico, experimental for the moment) selectrum consult embark embark-consult marginalia orderless (unless +prescient) wgrep prescient (+prescient) consult-flycheck (:checkers syntax) all-the-icons-completion (+icons)

Prerequisites

This module has no prerequisites.

Features

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:

Jump-to navigation

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

https://assets.doomemacs.org/completion/selectrum/projectile.png

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

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

https://assets.doomemacs.org/completion/selectrum/search.png

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 `!` is equivalent to the universal argument for the previous commands.

---

These keybindings are available while a search is active:

Keybind	Description
C-;, <leader> a	Open an embark-act menu to chose a useful action
C-c C-;	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-M-j	Scroll down and preview.
C-M-k	Scroll up and preview.
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/selectrum/search-replace.png

In-buffer searching

This module provides some in buffer searching bindings:

• SPC s s (isearch)
• SPC s S (+selectrum/search-symbol-at-point via consult-line)
• SPC s b (consult-line)

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

Selectrum integration for various completing commands

General

Keybind	Description
M-x, SPC :	Enhanced M-x
SPC '	Resume last Selectrum session

Jump to files, buffers or projects

Keybind	Description
SPC RET	Find bookmark
SPC f f, SPC .	Browse from current directory
SPC p f, SPC SPC	Find file in project
SPC f r	Find recently opened file
SPC p p	Open another project
SPC b b, SPC ,	Switch to buffer in current workspace
SPC b B, SPC <	Switch to buffer

SPC b b and SPC , 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.

SPC f f and SPC . support exporting to a wdired buffer using C-c C-e.

Search

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

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