This package provides various commands based on the Emacs completion function
completing-read
, in particular a more advanced buffer switching command
consult-buffer
and a Swiper-like
search command consult-line
.
The commands are compatible with completion-systems based on the standard Emacs API, e.g., the Emacs builtin Icomplete and Selectrum. If Icomplete is used, it is recommended to install Icomplete-vertical. The goal is to keep the completion-system specifics in this package to a minimum.
Note that there is the Marginalia
package, 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. Marginalia has been extracted from
Embark and Consult since both packages
provided minibuffer annotations. Embark provides local actions (like a context
menu), which can be executed while selecting a candidate in the minibuffer. For
example, when selecting a file, an action to delete the file is offered.
If you use Ivy or Helm, you probably don't need Consult, since both packages already bring their own rich set of additional commands.
consult-mark
consult-line
consult-outline
marginalia-mode
Most provided commands follow the naming scheme consult-<thing>
.
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 typeb SPC
,f SPC
,m SPC
andv SPC
in order to narrow to buffers, files, bookmarks and views respectively. In order to show ephemeral buffers pressSPC
- it works the same way asswitch-buffer
.consult-bookmark
: Select or create bookmark. You might prefer the more powerfulconsult-buffer
instead, which includes bookmarks.consult-recent-file
(-other-window
,-other-frame
): Select a recent files. You might prefer the more powerfulconsult-buffer
instead, which includes recent files.
consult-register
: Select from list of registers.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-apropos
: Replacement forapropos
with completion.
Note that there is the Marginalia
package, which provides marginalia-mode
. Enabling this mode annotates
completions with richer information (e.g. M-x
, describe-face
,
describe-symbol
, helpful-function
, …).
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 the minibuffer-history-variable is used.
consult-line
(-symbol-at-point
,-from-isearch
): Select from matching lines. Supports live preview and recursive editing. There are two variants, which search for the symbol at point and for the most recent isearch string respectively.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. Supports live preview, recursive editing and narrowing.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
.
consult-file-externally
: Select a file and open it externally, e.g. usingxdg-open
on Linux.consult-multi-occur
: Replacement formulti-occur
which usescompleting-read-multiple
.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-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
.consult-theme
: Select a theme and disable all currently enabled themes. Supports live preview of the theme while scrolling through the candidates.
Some of the 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 must
be explicitly enabled via consult-preview-mode
. Furthermore for each command,
a customizable variable is offered to selectively enable/disable preview.
Consult has special support to narrow to candidate subsets. 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/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
.
It is recommended to manage package configurations with use-package
. The
Consult package only provides commands and does not add any keybindings. In
order to use the enhanced commands, you must configure the keybindings yourself.
Note that there are three packages as of now: consult.el
,
consult-selectrum.el
and consult-flycheck.el
. Consult has been split such
that the main package consult.el
only depends on Emacs core components.
;; 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-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 i" . 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
;; Replace `multi-occur' with `consult-multi-occur', which is a drop-in replacement.
(fset 'multi-occur #'consult-multi-occur)
;; Configure other variables and modes in the :config section, after lazily loading the package
:config
;; 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 enable previews. Note that individual previews can be disabled
;; via customization variables.
(consult-preview-mode))
;; Enable Consult-Selectrum integration.
;; This package should be installed if Selectrum is used.
(use-package consult-selectrum
:demand t)
;; Optionally add the `consult-flycheck' command.
(use-package consult-flycheck
:bind (:map flycheck-command-map
("!" . consult-flycheck)))
Variable | Default | Description |
---|---|---|
consult-after-jump-hook | '(recenter) | Functions to call after jumping to a location |
consult-goto-line-numbers | t | Show line numbers for consult-goto-line |
consult-imenu-narrow | … | Narrowing keys for imenu |
consult-line-numbers-widen | t | Show absolute line numbers when narrowing is active. |
consult-mode-command-filter | … | Filter regexp for consult-mode-command |
consult-mode-histories | … | Mode-specific history variables |
consult-narrow-key | nil | Narrowing prefix key during completion |
consult-widen-key | nil | Widening key during completion |
consult-preview-buffer | t | Enable buffer preview during selection |
consult-preview-error | t | Enable error preview during selection |
consult-preview-flycheck | t | Enable flycheck error preview during selection |
consult-preview-flymake | t | Enable flymake diagnostic preview during selection |
consult-preview-global-mark | t | Enable global mark preview during selection |
consult-preview-line | t | Enable line preview during selection |
consult-preview-mark | t | Enable mark preview during selection |
consult-preview-outline | t | Enable outline preview during selection |
consult-preview-theme | t | Enable theme preview during selection |
consult-preview-yank | t | Enable yank preview during selection |
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 |
It is recommended to install the following package combination:
- consult: This package
- consult-flycheck: Provides the consult-flycheck command.
- consult-selectrum: Provides integration with Selectrum.
- selectrum or icomplete-vertical: Vertical completion systems
- marginalia: Annotations for the completion candidates
- embark: Action commands, which can act on the completion candidates
- orderless or prescient: Completion styles, cndidate filtering, Prescient also offers sorting.
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.
You probably guessed from the name that this package took inspiration from Counsel by Oleh Krehel. Some of the commands found in this package originated in the Selectrum wiki.
Code contributions:
Advice and useful discussions: