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.

Plugins

selectrum consult embark embark-consult marginalia orderless (unless +prescient) wgrep prescient (+prescient) consult-flycheck (:checkers syntax)

Prerequisites

This module has no prerequisites.

Features

Selectrum and friends modify and use the built-in completing-read function, used by any function that requires completion. Due to this the full scope of these packages is too large to cover here, so 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

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

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