consult.el - Consulting completing-read
Introduction
This package provides various handy commands based on the Emacs completion
function completing-read
, which allows to quickly select from a list of
candidates. Consult offers in particular a more advanced buffer switching
command consult-buffer
which allows to select from buffers, recent files and
more. Various search commands are provided, like an asynchronous consult-grep
,
and consult-line
, which resembles Swiper or Helm-Swoop. Please take a look at
the full list of commands!
All Consult commands are compatible with completion systems based on the
standard Emacs completing-read
API, notably the default completion system,
Icomplete, Selectrum and Embark. If Icomplete is used, it is recommended to
install Icomplete-vertical. The completion system specifics in this package are
kept to a minimum. The ability of the Consult commands to work well with
arbitrary completion systems is one main advantage of the package. This property
allows Consult to fit well into existing setups and it helps you to create a
full completion environment out of small and independent components. Note that,
if you use Ivy or Helm, you probably don’t need Consult, since both packages
already bring their own rich set of additional commands.
There are the Marginalia and Embark packages, which can be combined with
Consult. The marginalia-mode
enriches the completion display with annotations.
The annotations show for example documentation strings or file information. The
versatile Embark packages provides local actions, comparable to a context menu,
which can be executed while selecting a candidate in the minibuffer or in other
contexts. For example, when selecting from a list of files, an action to delete
the file is offered. Embark offers more than local actions and can also be used
as a completion system through its live-updating candidate collect buffer. The
Embark integration is described later in greater detail.
Screenshots
consult-grep
consult-imenu
consult-line
Available commands
Most provided commands follow the meaningful naming scheme consult-<thing>
.
TIP: If you have Marginalia installed and heavy annotators enabled, 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
consult-buffer
(-other-window
,-other-frame
): Enhanced version ofswitch-to-buffer
with support for virtual buffers. Supports live preview and recursive editing while previewing. The command supports narrowing. You can typef SPC
in order to narrow to recent files. Ephemeral buffers can be shown by pressingSPC
- it works the same way asswitch-buffer
. Supported narrowing keys:- b Buffers
- f Files
- m Bookmarks
- p Project (only available if
consult-project-root-function
is configured as shown in the example configuration) - v Views (only available if
consult-view-*-function
is configured as shown in the example configuration)
consult-bookmark
: Select or create bookmark. You might consider the powerfulconsult-buffer
instead as an alternative, which includes bookmarks. Howeverconsult-bookmark
supports preview of bookmarks and narrowing.consult-recent-file
(-other-window
,-other-frame
): Select a recent files. You might prefer the more powerfulconsult-buffer
instead, which includes recent files.
Editing
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 it is recommended to use the built-in Emacs commands likejump-to-register
. There is also the supplementary functionconsult-register-preview
which can be used asregister-preview-function
for a consistent display. See the example configuration for how theconsult-register-preview
function is meant to be used.consult-yank
,consult-yank-pop
: Enhanced version ofyank
andyank-pop
which allows selecting from the kill-ring. Live preview is supported when selecting from the kill-ring.consult-kmacro
: Select macro from the macro ring and execute it.consult-keep-lines
,consult-flush-lines
: Replacements forkeep-lines
andflush-lines
which use the current completion style for filtering the buffer. The function updates the buffer while typing. In particular, this function can be used to further narrow an exported Embark collect buffer with the same completion filtering as duringcompleting-read
.
Navigation
consult-goto-line
: Jump to line number enhanced with live preview. This is a drop-in replacement forgoto-line
.consult-mark
: Jump to a marker in themark-ring
. Supports live preview and recursive editing.consult-global-mark
: Jump to a marker in theglobal-mark-ring
. Supports live preview and recursive editing.consult-outline
: Jump to a heading of the outline. Supports live preview and recursive editing.consult-imenu
: Jump to imenu item in the current buffer. Supports live preview, recursive editing and narrowing.consult-project-imenu
: Jump to imenu item in project buffers, with the same major mode as the current buffer. Supports live preview, recursive editing and narrowing. This feature has been inspired by imenu-anywhere.
Search
consult-line
: Enter search string and select from matching lines. Supports live preview and recursive editing. The symbol at point and the recent isearch string are added to the “future history” and can be accessed by pressingM-n
.consult-multi-occur
: Replacement formulti-occur
which usescompleting-read-multiple
.consult-grep
,consult-ripgrep
,consult-git-grep
: Search for regular expression in current directory. Grep is invoked asynchronously, while you enter the search term. You are required to enter at leastconsult-async-min-input
characters in order for the search to get started. The input string is split into two parts, if the first character is a punctuation character, like#
. For example#grep-regexp#filter-string
, is split at the second#
. The string “grep-regexp” is passed to Grep, the “filter-string” is passed to the fast Emacs filtering to further narrow down the list of matches. This is particularily useful if you are using an advanced completion style like orderless.consult-grep
supports preview. Ifconsult-project-root-function
is configured and the function returns non-nil,consult-grep
searches the current project directory. Otherwise thedefault-directory
is searched. Ifconsult-grep
is invoked with prefix argument, you can specify the directory manually, i.e.,C-u M-g r
.consult-find
,consult-locate
: Find file by matching the path against a regexp. Likeconsult-grep
either the project root or the current directory is used as root directory for the search. The input string is treated similarly toconsult-grep
, where the first part is passed to find, and the second part is used for Emacs filtering. Note thatfind
uses wildcards, e.g. enter*consult*
, to find all files containing the string “consult”. In case you want to use another search utility likefd
, you can write wrapper commandmy-fdfind
as shown in the example configuration.
Compilation errors
consult-error
: Jump to an error. Supports live preview and recursive editing. In contrast toconsult-flycheck
it shows the line and is more general since it is not tied to a specific backend.consult-flycheck
: Jump to flycheck error. Supports live preview and recursive editing. The command supports narrowing. Presse SPC
,w SPC
,i SPC
to only show errors, warnings and infos respectively. This command requires to install the additionalconsult-flycheck.el
package since the mainconsult.el
package only depends on Emacs core components.consult-flymake
: Jump to Flymake diagnostic, likeconsult-flycheck
.
Histories
consult-complex-command
: Select a command from thecommand-history
. This command is acompleting-read
version ofrepeat-complex-command
and can also be considered a replacement for thecommand-history
command from chistory.el.consult-history
: Insert a string from the current buffer history. This command can be invoked from the minibuffer. In that case the history stored in theminibuffer-history-variable
is used.
Major and minor modes
consult-minor-mode-menu
: Enable/disable minor mode. Supports narrowing to on/off/local/global modes by pressingi/o/l/g SPC
respectively.consult-mode-command
: Run a command from the currently active minor or major modes. Supports narrowing to local-minor/global-minor/major mode via the keysl/g/m
.
Miscellaneous
consult-apropos
: Replacement forapropos
with completion.consult-man
: Find Unix man page, via Unixapropos
orman -k
. The selected man page is opened using the Emacsman
command.consult-file-externally
: Select a file and open it externally, e.g. usingxdg-open
on Linux.consult-completion-in-region
: Function which can be used ascompletion-in-region-function
. This way, the minibuffer completion UI will be used forcompletion-at-point
. This function is particularily useful in combination with Icomplete-vertical, since Icomplete does not provide its owncompletion-in-region-function
. In contrast, Selectrum already comes with its own function.consult-theme
: Select a theme and disable all currently enabled themes. Supports live preview of the theme while scrolling through the candidates.
Special features
Consult enhances completing-read
with live previews of candidates, additional
narrowing capabilities to candidate subsets and asynchronously generated
candidate lists. This functionality is provided by the internal consult--read
function, which is used by most Consult commands. The consult--read
function
is a thin wrapper around completing-read
. This allows Consult to work with
different completion systems in the backend, while still offering more advanced
features.
Live previews
Some Consult commands support live previews. For example when you scroll
through the items of consult-line
, the buffer will scroll to the
corresponding position. It is possible to jump back and forth between the
minibuffer and the buffer to perform recursive editing while the search is
ongoing.
Previews are enabled by default but can be disabled via the
consult-preview-key
variable. Furthermore it is possible to specify
keybindings which trigger the preview manually as shown in the example
configuration. The default setting of consult-preview-key
is =’any= which
means that the preview will be triggered on any keypress when the selected
candidate changes. Each command can be configured individually with its own
:preview-key
, such that preview can be manual for some commands, for some
commands automatic and for some commands completely disabled.
Narrowing to subsets
Consult has special support to narrow to candidate subsets. This functionality
is useful if the list of candidates consists of candidates of multiple types or
candidates from multiple sources, like the consult-buffer
command, which
shows both buffers and recently opened files.
When you use the consult-buffer
command, you can press b SPC
and the list
of candidates will be restricted such that only buffers are shown. If you press
DEL
afterwards, the full candidate list will be shown again. Furthermore a
narrowing prefix key and a widening key can be configured which can be pressed
to achieve the same effect, see the configuration variables
consult-narrow-key
and consult-widen-key
.
If which-key is installed, the possible narrowing keys are shown in the
which-key window after pressing the prefix key consult-narrow-key
.
Furthermore there is the consult-narrow-help
command which can be bound to a
key in the consult-narrow-map
if this is desired, as shown in the example
configuration.
Asynchronous candidate lists
Consult has support for asynchronous generation of candidate lists. This
feature is used for example by consult-grep
, where the list of matches is
generated dynamically while the user is typing a grep regular expression. The
grep process is executed in the background. When modifying the grep regular
expression, the background process is terminated and a new process is started
with the modified regular expression.
The matches, which have been found, can then be narrowed using the installed
Emacs completion-style. This can be very powerful if you are using for example
the orderless
completion style.
This two-level filtering is possible by splitting the input string. Part of the input string is treated as input to grep and part of the input is used for filtering. The input string is split at a punctuation character, using a similar syntax as Perl regular expressions.
Examples:
#defun
: Search for “defun” using grep.#defun#consult
: Search for “defun” using grep, filter with the word “consult”./defun/consult
: It is also possible to use other punctuation characters.#to#
: Force searching for “to” using grep, since the grep pattern must be longer thanconsult-async-min-input
characters by default.#defun -- --invert-match#
: Pass argument--invert-match
to grep.
For asynchronous processes like find
and grep
, the prompt has a small
indicator showing the process status:
:
the usual prompt colon, before input is provided.*
with warning face, the process is running.:
with success face, success, process exited with an error code of zero.!
with error face, failure, process exited with a nonzero error code.;
with error face, interrupted, for example if more input is provided.
There is an ephemeral error log buffer _*consult-async-stderr*
(note the leading space!),
you can access the buffer using consult-buffer
and switch-to-buffer
by first pressing SPC
and then selecting the buffer.
Integration with Embark
NOTE: Please install the embark-consult
package from MELPA, which provides
Consult-specific Embark actions and the Occur buffer export.
Embark is a versatile package which offers context dependent actions, comparable to a context menu. See the Embark manual for an extensive description of its capabilities.
Actions are commands which can operate on the currently selected candidate (or
target in Embark terminology). When completing files, for example the
delete-file
command is offered. Embark also allows to to execute arbitrary
commands on the currently selected candidate via M-x
.
Furthermore Embark provides the embark-collect-snapshot
command, which
collects candidates and presents them in an Embark collect buffer, where
further actions can be applied to them. A related feature is the
embark-export
command, which allows to export candidate lists to a buffer of
a special type. For example in the case of file completion, a Dired buffer is
opened.
In the context of Consult, particularily exciting is the possibility to export
the matching lines from consult-line
, consult-outline
, consult-mark
and
consult-global-mark
. The matching lines are exported to an Occur buffer where
they can be edited via the occur-edit-mode
(press key e
). Similarily,
Embark supports exporting the matches found by consult-grep
,
consult-ripgrep
and consult-git-grep
to a Grep buffer, where the matches
across files can be edited, if the wgrep package is installed.
Configuration
Consult can be installed from MELPA via the Emacs built-in package manager. Alternatively it can be directly installed from the development repository via other non-standard package managers.
It is recommended to manage package configurations with the excellent
use-package
macro. The Consult package only provides commands and does not add
any keybindings or modes. In order to use the Consult commands, you must
configure the keybindings yourself. As a result, the package is not intrusive
but requires a little setup effort. Feel free to only bind the commands you
consider useful to your workflow!
Note that there are two packages as of now: consult
and consult-flycheck
.
consult-flycheck
is a separate package such that the core consult
package
only depends on Emacs core components. The consult
package will work out of
the box with the default completion, Icomplete and Selectrum.
Example configuration
;; Example configuration for Consult
(use-package consult
;; Replace bindings. Lazily loaded due by `use-package'.
:bind (("C-x M-:" . consult-complex-command)
("C-c h" . consult-history)
("C-c m" . consult-mode-command)
("C-c k" . consult-keep-lines)
("C-c C-k" . consult-flush-lines)
("C-x b" . consult-buffer)
("C-x 4 b" . consult-buffer-other-window)
("C-x 5 b" . consult-buffer-other-frame)
("C-x r x" . consult-register)
("C-x r b" . consult-bookmark)
("M-g g" . consult-goto-line)
("M-g M-g" . consult-goto-line)
("M-g o" . consult-outline) ;; "M-s o" is a good alternative.
("M-g l" . consult-line) ;; "M-s l" is a good alternative.
("M-g m" . consult-mark) ;; I recommend to bind Consult navigation
("M-g k" . consult-global-mark) ;; commands under the "M-g" prefix.
("M-g r" . consult-git-grep) ;; or consult-grep, consult-ripgrep
("M-g f" . consult-find) ;; or consult-locate, my-fdfind
("M-g i" . consult-project-imenu) ;; or consult-imenu
("M-g e" . consult-error)
("M-s m" . consult-multi-occur)
("M-y" . consult-yank-pop)
("<help> a" . consult-apropos))
;; The :init configuration is always executed (Not lazy!)
:init
;; Custom command wrappers. It is generally encouraged to write your own
;; commands based on the Consult commands. Some commands have arguments which
;; allow tweaking. Furthermore global configuration variables can be set
;; locally in a let-binding.
(defun my-fdfind (&optional dir)
(interactive "P")
(let ((consult-find-command '("fdfind" "--color=never" "--full-path")))
(consult-find dir)))
;; Replace `multi-occur' with `consult-multi-occur', which is a drop-in replacement.
(fset 'multi-occur #'consult-multi-occur)
;; Configure register preview function.
;; This gives a consistent display for both `consult-register' and
;; the register preview when editing registers.
(setq register-preview-delay 0
register-preview-function #'consult-register-preview)
;; Configure other variables and modes in the :config section, after lazily loading the package
:config
;; Configure preview. Note that the preview-key can also be configured on a
;; per-command basis via `consult-config'.
;; The default value is 'any, such that any key triggers the preview.
;; (setq consult-preview-key 'any)
;; (setq consult-preview-key (kbd "M-p"))
;; (setq consult-preview-key (list (kbd "<S-down>") (kbd "<S-up>")))
;; Optionally configure narrowing key.
;; Both < and C-+ work reasonably well.
(setq consult-narrow-key "<") ;; (kbd "C-+")
;; Optionally make narrowing help available in the minibuffer.
;; Probably not needed if you are using which-key.
;; (define-key consult-narrow-map (vconcat consult-narrow-key "?") #'consult-narrow-help)
;; Optional configure a view library to be used by `consult-buffer'.
;; The view library must provide two functions, one to open the view by name,
;; and one function which must return a list of views as strings.
;; Example: https://github.com/minad/bookmark-view/
;; (setq consult-view-open-function #'bookmark-jump
;; consult-view-list-function #'bookmark-view-names)
;; Optionally configure a function which returns the project root directory
(autoload 'projectile-project-root "projectile")
(setq consult-project-root-function #'projectile-project-root))
;; Optionally add the `consult-flycheck' command.
(use-package consult-flycheck
:bind (:map flycheck-command-map
("!" . consult-flycheck)))
Customizable variables
TIP: If you have Marginalia installed, type M-x customize-variable RET
^consult
to see all Consult-specific customizable variables with their current
values and abbreviated description! Alternatively, type C-h a ^consult
to get
an overview of all Consult variables and functions with their descriptions.
Variable | Default | Description |
---|---|---|
consult-after-jump-hook | ‘(recenter) | Functions to call after jumping to a location |
consult-async-default-split | ”#” | Separator character used for splitting #async#filter |
consult-async-input-debounce | 0.25 | Input debounce for asynchronous commands |
consult-async-input-throttle | 0.5 | Input throttle for asynchronous commands |
consult-async-min-input | 3 | Minimum numbers of letters needed for async process |
consult-async-refresh-delay | 0.25 | Refresh delay for asynchronous commands |
consult-bookmark-narrow | … | Narrowing configuration for consult-bookmark |
consult-buffer-filter | … | Filter for consult-buffer |
consult-config | nil | Invididual command option configuration |
consult-find-command | ’(…) | Command line arguments for find |
consult-fontify-max-size | 1048576 | Buffers larger than this limit are not fontified |
consult-git-grep-command | ’(…) | Command line arguments for git-grep |
consult-goto-line-numbers | t | Show line numbers for consult-goto-line |
consult-grep-command | ’(…) | Command line arguments for grep |
consult-imenu-narrow | … | Mode-specific narrowing keys for consult-imenu |
consult-imenu-toplevel | … | Mode-specific toplevel names used by consult-imenu |
consult-line-numbers-widen | t | Show absolute line numbers when narrowing is active. |
consult-line-point-placement | ‘match-beginning | Placement of the point used by consult-line |
consult-locate-command | ’(…) | Command line arguments for locate |
consult-mode-command-filter | … | Filter for consult-mode-command |
consult-mode-histories | … | Mode-specific history variables |
consult-narrow-key | nil | Narrowing prefix key during completion |
consult-preview-key | ‘any | Keys which triggers preview |
consult-preview-max-count | 10 | Maximum number of files to keep open during preview |
consult-preview-max-size | 10485760 | Size limit for previewed files |
consult-project-root-function | nil | Function which returns current project root |
consult-register-narrow | … | Narrowing configuration for consult-register |
consult-ripgrep-command | ’(…) | Command line arguments for ripgrep |
consult-themes | nil | List of themes to be presented for selection |
consult-view-list-function | nil | Function which returns a list of view names as strings |
consult-view-open-function | nil | Function to open a view by name |
consult-widen-key | nil | Widening key during completion |
Fine-tuning of individual commands
NOTE: Consult allows fine-grained customization of individual commands. This configuration feature is made available for experienced users with special requirements.
Commands allow flexible, individual customization by setting the
consult-config
list. You can override any option passed to the internal
consult--read
API. Note that since consult--read
is part of the internal
API, options could be removed, replaced or renamed at any time.
Useful options are:
:preview-key
set the preview key, default isconsult-preview-key
:initial
set the initial input:default
set the default value:history
set the history variable symbol:add-history
add items to the future history, for example symbol at point:sort
enable or disable sorting
;; Set preview for `consult-buffer' to key `M-p'
;; and disable preview for `consult-theme' completely.
;; For `consult-line' specify multiple keybindings.
;; Note that you should bind the <S-up> and <S-down> in the
;; `minibuffer-local-completion-map' or `selectrum-minibuffer-map'
;; to the commands which select the previous or next candidate!
(setq consult-config `((consult-theme :preview-key nil)
(consult-buffer :preview-key ,(kbd "M-p"))
(consult-line :preview-key (list ,(kbd "<S-down>") ,(kbd "<S-up>")))))
Generally it is possible to modify commands for your individual needs by the following techniques:
- Create your own wrapper function which passes modified arguments to the Consult functions.
- Modify
consult-config
in order to change theconsult--read
settings. - Create advices to modify some internal behavior.
- Write or propose a patch!
Recommended packages
It is recommended to install the following package combination:
- consult: This package
- consult-flycheck: Provides the consult-flycheck command
- selectrum or icomplete-vertical: Vertical completion systems
- marginalia: Annotations for the completion candidates
- embark and embark-consult: Action commands, which can act on the completion candidates
- orderless: Completion style, Flexible candidate filtering
- prescient: Frecency-based candidate sorting, also offers filtering
Additional recommended packages for wider integration:
- which-key: Helpful mode showing keybindings, also shows the Consult narrowing keys
- wgrep: Editing of grep buffers, can be used together with
consult-grep
via Embark
Note that all packages are independent and can potentially be exchanged with alternative components, since there exist no hard dependencies. Furthermore it is possible to get started with only Selectrum and Consult and add more components later to the mix.
Acknowledgements
You probably guessed from the name that this package took inspiration from
Counsel by Oleh Krehel. Some of the Consult commands originated in the Selectrum
wiki. The commands have been rewritten and greatly enhanced in comparison to the
wiki versions. In particular all Selectrum-specific code has been removed, such
that the commands are compatible with the completing-read
API.
Consult is intended to be a community effort, please participate in the discussions. Contributions are very welcome. If you have a proposal, take a look at the Consult wishlist.
Code contributions:
- Omar Antolín Camarena
- Sergey Kostyaev
- okamsn
- Clemens Radermacher
- Tom Fitzhenry
- jakanakaevangeli
- inigoserna
- Adam Spiers
- Omar Polo
Advice and useful discussions: