Consult

#+title: consult.el - Search and navigate via completing-read #+author: Daniel Mendler #+language: en #+export_file_name: consult.texi #+texinfo_dir_category: Emacs misc features #+texinfo_dir_title: Consult: (consult). #+texinfo_dir_desc: Useful commands built on completing-read.

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a> #+html: <a href="https://elpa.gnu.org/packages/consult.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/consult.svg"/></a> #+html: <a href="https://elpa.gnu.org/devel/consult.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/consult.svg"/></a> #+html: <a href="https://melpa.org/#/consult"><img alt="MELPA" src="https://melpa.org/packages/consult-badge.svg"/></a> #+html: <a href="https://stable.melpa.org/#/consult"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/consult-badge.svg"/></a>

Consult provides search and navigation commands based on the Emacs completion function [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html][completing-read]] documented in the [[info:elisp#Minibuffer Completion][Elisp manual]]. Completion allows you to quickly select an item from a list of candidates. Consult offers asynchronous and interactive =consult-grep= and =consult-ripgrep= commands, and the line-based search command =consult-line=. Furthermore Consult provides an advanced buffer switching command =consult-buffer= to switch between buffers, recently opened files, bookmarks and buffer-like candidates from other sources. Some of the Consult commands are enhanced versions of built-in Emacs commands. For example the command =consult-imenu= presents a flat list of the Imenu with [[#live-previews][live preview]], [[#narrowing-and-grouping][grouping and narrowing]]. Please take a look at the [[#available-commands][full list of commands]].

Consult is fully compatible with completion systems centered around the standard Emacs =completing-read= API, [[https://github.com/minad/vertico][Vertico]], [[https://github.com/protesilaos/mct][Mct]], and the built-in default completion system and Icomplete.

This package keeps the completion system specifics to a minimum. The ability of the Consult commands to work well with arbitrary completion systems is one of the main advantages of the package. Consult fits well into existing setups and it helps you to create a full completion environment out of small and independent components.

You can combine the complementary packages [[https://github.com/minad/marginalia][Marginalia]], [[https://github.com/oantolin/embark][Embark]] and [[https://github.com/oantolin/orderless][Orderless]] with Consult. Marginalia enriches the completion display with annotations, e.g., documentation strings or file information. The versatile Embark package provides local actions, comparable to a context menu. These actions operate on the selected candidate in the minibuffer or at point in normal buffers. For example, when selecting from a list of files, Embark offers an action to delete the file. Additionally Embark offers a facility to collect completion candidates in a collect buffer. The section [[#embark-integration][Embark integration]] documents in detail how Consult and Embark work together.

#+toc: headlines 8

• Screenshots :noexport:

#+caption: consult-grep [[https://github.com/minad/consult/blob/screenshots/consult-grep.gif?raw=true]] Fig. 1: Command =consult-git-grep=

#+caption: consult-imenu [[https://github.com/minad/consult/blob/screenshots/consult-imenu.png?raw=true]] Fig. 2: Command =consult-imenu=

#+caption: consult-line [[https://github.com/minad/consult/blob/screenshots/consult-line.png?raw=true]] Fig. 3: Command =consult-line=

• Available commands :properties: :custom_id: available-commands :description: Navigation, search, editing commands and more :end: #+cindex: commands

Most Consult commands follow the meaningful naming scheme =consult-<thing>=. Many commands implement a little known but convenient Emacs feature called "future history", which guesses what input the user wants. At a command prompt type =M-n= and typically Consult will insert the symbol or thing at point into the input.

TIP: If you have [[https://github.com/minad/marginalia][Marginalia]] annotators activated, type =M-x ^consult= to see all Consult commands with their abbreviated description. Alternatively, type =C-h a ^consult= to get an overview of all Consult variables and functions with their descriptions.

** Virtual Buffers :properties: :description: Buffers, bookmarks and recent files :end: #+cindex: virtual buffers

#+findex: consult-buffer #+findex: consult-buffer-other-window #+findex: consult-buffer-other-frame #+findex: consult-buffer-other-tab #+findex: consult-project-buffer #+findex: consult-recent-file #+findex: consult-bookmark

• =consult-buffer=: Enhanced version of =switch-to-buffer= with support for virtual buffers. Supports live preview of buffers and narrowing to the virtual buffer types. You can type =f SPC= in order to narrow to recent files. Press =SPC= to show ephemeral buffers. Supported narrowing keys:
  • b Buffers
  • SPC Hidden buffers
  • • Modified buffers
  • o Buffers from other frames/tabs
  • f Files (Requires =recentf-mode=)
  • r File and buffer registers
  • m Bookmarks
  • p Project
  • B Project buffers
  • F Project files
  • R Project roots
  • Custom [[#multiple-sources][other sources]] configured in =consult-buffer-sources=. By default, buffers from all frames are taken into account. The buffers which are taken into account, can be customized by the variable =consult-buffer-list-function=. Other buffers are available by pressing =o SPC=.
• =consult-buffer-other-window=, =consult-buffer-other-frame=, =consult-buffer-other-tab=: Variants of =consult-buffer=.
• =consult-project-buffer=: Variant of =consult-buffer= restricted to buffers and recent files of the current project. You can add custom sources to =consult-project-buffer-sources=. The command may prompt you for a project if you invoke it from outside a project.
• =consult-bookmark=: Select or create bookmark. To select bookmarks you might use the =consult-buffer= as an alternative, which can include a bookmark virtual buffer source. Note that =consult-bookmark= supports preview of bookmarks and narrowing.
• =consult-recent-file=: Select from recent files with preview. You might prefer the powerful =consult-buffer= instead, which can include recent files as a virtual buffer source. The =recentf-mode= enables tracking of recent files.

** Editing :properties: :description: Commands useful for editing :end: #+cindex: editing

#+findex: consult-yank-pop #+findex: consult-yank-from-kill-ring #+findex: consult-yank-replace #+findex: consult-kmacro

• =consult-yank-from-kill-ring=: Enhanced version of =yank= to select an item from the =kill-ring=. The selected text previewed as overlay in the buffer.
• =consult-yank-pop=: Enhanced version of =yank-pop= with DWIM-behavior, which either replaces the last =yank= by cycling through the =kill-ring=, or if there has not been a last =yank= consults the =kill-ring=. The selected text previewed as overlay in the buffer.
• =consult-yank-replace=: Like =consult-yank-pop=, but always replaces the last =yank= with an item from the =kill-ring=.
• =consult-kmacro=: Select macro from the macro ring and execute it.

** Register :properties: :description: Searching through registers and fast access :end: #+cindex: register

#+findex: consult-register #+findex: consult-register-load #+findex: consult-register-store #+findex: consult-register-format #+findex: consult-register-window

• =consult-register=: Select from list of registers. The command supports narrowing to register types and preview of marker positions. This command is useful to search the register contents. For quick access use the commands =consult-register-load=, =consult-register-store= or the built-in Emacs register commands.
• =consult-register-format=: Set =register-preview-function= to this function for an enhanced register formatting. Used automatically by =consult-register-window=.
• =consult-register-window=: Replace =register-preview= with this function for a better register window. See the [[#use-package-example][example configuration]].
• =consult-register-load=: Utility command to quickly load a register. The command either jumps to the register value or inserts it.
• =consult-register-store=: Improved UI to store registers depending on the current context with an action menu. With an active region, store/append/prepend the contents, optionally deleting the region when a prefix argument is given. With a numeric prefix argument, store/add the number. Otherwise store point, file, buffer, frameset, window or kmacro. Usage examples:
  • =M-' x=: If no region is active, store point in register =x=. If a region is active, store the region in register =x=.
  • =M-' M-w x=: Store window configuration in register =x=.
  • =C-u 100 M-' x=: Store number in register =x=.

** Navigation :properties: :description: Mark rings, outlines and imenu :end: #+cindex: navigation

#+findex: consult-goto-line #+findex: consult-mark #+findex: consult-global-mark #+findex: consult-outline #+findex: consult-imenu #+findex: consult-imenu-multi

• =consult-goto-line=: Jump to line number enhanced with live preview. This is a drop-in replacement for =goto-line=. Enter a line number to jump to the first column of the given line. Alternatively enter =line:column= in order to jump to a specific column.
• =consult-mark=: Jump to a marker in the =mark-ring=. Supports live preview and recursive editing.
• =consult-global-mark=: Jump to a marker in the =global-mark-ring=. Supports live preview and recursive editing.
• =consult-outline=: Jump to a heading of the outline. Supports