To install this package, run in Emacs:
M-x package-install RET consult RET
Consult provides practical commands based on the Emacs completion function
completing-read. Completion allows you to quickly select an item from a list of
candidates. Consult offers in particular an advanced buffer switching command
consult-buffer to switch between buffers and recently opened files. Furthermore
Consult provides multiple search commands, an asynchronous
consult-line, which resembles Swiper. Some of the Consult
commands are enhanced versions of built-in Emacs commands. For example the
consult-imenu presents a flat list of the Imenu with live preview,
grouping and narrowing. Please take a look at the full list of commands.
Consult is fully compatible with completion systems based on the standard Emacs
completing-read API, notably the default completion system, Vertico,
Icomplete/Icomplete-vertical, Selectrum and Embark.
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. Note that, if you use Ivy or Helm, you probably don't need Consult, since both packages bring their own Consult-like functionality.
You can combine the complementary packages Marginalia, Embark and 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 in other contexts. For example, when selecting from a list of files, Embark offers an action to delete the file. Additionally Embark offers a completion system by itself through its live-updating collect buffer. The section Embark integration documents in greater detail how Consult and Embark work together.
Most Consult commands follow the meaningful naming scheme
Many commands implement a little known but convenient Emacs feature called
"future history", which guesses what input the user wants. At a command prompt
M-n and typically Consult will insert the symbol or thing at point into
TIP: If you have 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
-other-frame): Enhanced version of
switch-to-bufferwith support for virtual buffers. Supports live preview of buffers and narrowing to the virtual buffer types. You can type
f SPCin order to narrow to recent files. Press
SPCto show ephemeral buffers. Supported narrowing keys:
consult-bookmark: Select or create bookmark. You might use the powerful
consult-bufferas an alternative, which can include a bookmark virtual buffer source. But note that
consult-bookmarksupports preview of bookmarks and narrowing.
consult-recent-file: Select from recent files with preview. You might prefer the powerful
consult-bufferinstead, which can include recent files as a virtual buffer source. The
recentf-modeenables tracking of recent files.
consult-yank-from-kill-ring: Enhanced version of
yankto select an item from the
kill-ring. The selected text previewed as overlay in the buffer.
consult-yank-pop: Enhanced version of
yank-popwith DWIM-behavior, which either replaces the last
yankby cycling through the
kill-ring, or if there has not been a last
kill-ring. The selected text previewed as overlay in the buffer.
consult-yank-pop, but always replaces the last
yankwith an item from the
consult-kmacro: Select macro from the macro ring and execute it.
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-storeor the built-in Emacs register commands.
register-preview-functionto this function for an enhanced register formatting. See the example configuration.
register-previewwith this function for a better register window. See the 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, 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
M-' M-w x: Store window configuration in register
C-u 100 M-' x: Store number in register
consult-goto-line: Jump to line number enhanced with live preview. This is a drop-in replacement for
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 narrowing to a heading level, live preview and recursive editing.
consult-imenu: Jump to imenu item in the current buffer. Supports live preview, recursive editing and narrowing.
consult-imenu-multi: 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.
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 pressing
consult-lineis bound to the
isearch-mode-mapand is invoked during a running Isearch, it will use the current Isearch string.
consult-line-multi: Search across multiple buffers. By default search across project buffers. If invoked with a prefix argument search across all buffers. Behaves like
consult-isearch: During an Isearch session, this command picks a search string from history and continues the search with the newly selected string. Outside of Isearch, the command allows you to pick a string from the history and starts a new Isearch.
consult-isearchacts as a drop-in replacement for
consult-multi-occur: Replacement for
consult-keep-lines: Replacement for
keep/flush-lineswhich uses the current completion style for filtering the buffer. The function updates the buffer while typing. In particular
consult-keep-linescan narrow down an exported Embark collect buffer further, relying on the same completion filtering as
completing-read. If the input begins with the negation operator, i.e.,
! SPC, the filter matches the complement. If a region is active, the region restricts the filtering.
consult-focus-lines: Temporarily hide lines by filtering them using the current completion style. Call with
C-uprefix argument in order to show the hidden lines again. If the input begins with the negation operator, i.e.,
! SPC, the filter matches the complement. In contrast to
consult-keep-linesthis function does not edit the buffer. If a region is active, the region restricts the filtering.
consult-git-grep: Search for regular expression in files. Consult invokes Grep asynchronously, while you enter the search term. After at least
consult-async-min-inputcharacters, the search gets started. Consult splits the input string into two parts, if the first character is a punctuation character, like
#. For example
#grep-regexps#filter-string, is split at the second
#. The string
grep-regexpsis passed to Grep. If you enter multiple regular expressions separated by space only lines matching all regular expressions are shown. In order to match space literally, escape the space with a backslash. The
filter-stringis passed to the fast Emacs filtering to further narrow down the list of matches. This is particularly useful if you are using an advanced completion style like orderless.
consult-grepsupports preview. If the
consult-project-root-functionis configured and returns non-nil,
consult-grepsearches the current project directory. Otherwise the
default-directoryis searched. If
consult-grepis invoked with prefix argument
C-u M-s g, you can specify the directory manually.
consult-locate: Find file by matching the path against a regexp. Like for
consult-grep,either the project root or the current directory is the root directory for the search. The input string is treated similarly to
consult-grep, where the first part is passed to find, and the second part is used for Emacs filtering.
consult-compile-error: Jump to a compilation error. Supports live preview narrowing and recursive editing.
consult-flymake: Jump to flymake diagnostic. Supports live preview and recursive editing. The command supports narrowing. Press
n SPCto only show errors, warnings and notes respectively.
consult-flycheck: Jump to flycheck error, similar to
consult-flymake. This command requires the installation of the additional
consult-flycheckpackage since the main
consultpackage only depends on Emacs core components.
consult-xref: Integration with xref. This function can be set as as
consult-complex-command: Select a command from the
command-history. This command is a
repeat-complex-commandand is also a replacement for the
command-historycommand from chistory.el.
consult-history: Insert a string from the current buffer history. You can invoke this command from the minibuffer. In that case
consult-historyuses the history stored in the
consult-minor-mode-menu: Enable/disable minor mode. Supports narrowing to on/off/local/global modes by pressing
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 keys
consult-org-heading: Similar to
consult-outline, for Org buffers. Supports narrowing by heading level, priority and TODO state, as well as live preview and recursive editing.
consult-org-agenda: Jump to an agenda heading. Supports narrowing by heading level, priority and TODO state, as well as live preview and recursive editing.
consult-apropos: Replacement for
consult-man: Find Unix man page, via Unix
consult-manopens the selected man page using the Emacs
consult-file-externally: Select a file and open it externally, e.g. using
consult-theme: Select a theme and disable all currently enabled themes. Supports live preview of the theme while scrolling through the candidates.
consult-preview-at-point-mode: Command and minor mode which previews the candidate at point in the
*Completions*buffer. This is mainly relevant if you use the default
*Completions*UI or if you want to enable preview in Embark Collect buffers.
consult-completion-in-region: This function can be set as
completion-in-region-function. Then the minibuffer completion UI will be used
completion-at-point. This function is particularly useful in combination
with Vertico or Icomplete, since these UIs do not provide their own
completion-in-region-function. Selectrum already comes with its own function
consult-completion-in-region. If you use the default
UI, note that
consult-completion-in-region is not useful.
;; Use `consult-completion-in-region' if Vertico is enabled. ;; Otherwise use the default `completion--in-region' function. (setq completion-in-region-function (lambda (&rest args) (apply (if vertico-mode #'consult-completion-in-region #'completion--in-region) args)))
consult-completion-in-region, you may prefer to see the
completions directly in the buffer as a small popup. In that case, I
recommend either the Corfu or the Company package. There is a technical
consult-completion-in-region in combination with Lsp-mode or Eglot.
The Lsp server relies on the input at point, in order to generate refined
candidate strings. Since the completion is transferred from the original
buffer to the minibuffer, the server does not receive the updated input. Lsp
completion should work with Corfu or Company though, which perform the
completion directly in the original buffer.
consult-completing-read-multiple: Enhanced drop-in replacement for
completing-read-multiplewhich works better for long candidates. You can select/deselect multiple candidates by pressing
RET. Afterwards the selections are confirmed by pressing
completing-read with live previews of candidates, additional
narrowing capabilities to candidate groups and asynchronously generated
candidate lists. The internal
consult--read function, which is used by most
Consult commands, is a thin wrapper around
completing-read and provides the
special functionality. In order to support multiple candidate sources there
exists the high-level function
consult--multi. The architecture of Consult
allows it to work with different completion systems in the backend, while still
offering advanced features.
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
Consult enables previews by default. You can disable them by adjusting 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
any which means that Consult triggers
the preview immediately on any key press when the selected candidate changes.
You can configure each command individually with its own
following settings are possible:
(:debounce 0.5 any)
(list :debounce 0.5 (kbd "M-."))
A safe recommendation is to leave automatic immediate previews enabled in general and disable the automatic preview only for commands, where the preview may be expensive due to file loading.
(consult-customize consult-ripgrep consult-git-grep consult-grep consult-bookmark consult-recent-file consult-xref consult--source-file consult--source-project-file consult--source-bookmark :preview-key (kbd "M-."))
In this case one may wonder what the difference is between using an Embark
action on the current candidate in comparison to a manually triggered preview.
The main difference is that the files opened by manual preview are closed again
after the completion session. Furthermore during preview some functionality is
disabled to improve the performance, see for example
consult-preview-excluded-hooks. Files larger than
are previewed literally without syntax highlighting and without changing the
Delaying the preview is particularly useful for
consult-theme, since the theme
preview is a little bit slow. The delay can result in a smoother UI.
;; Preview on any key press, but delay 0.5s (consult-customize consult-theme :preview-key '(:debounce 0.5 any)) ;; Preview immediately on M-., on up/down after 0.5s, on any other key after 1s (consult-customize consult-theme :preview-key (list (kbd "M-.") :debounce 0.5 (kbd "<up>") (kbd "<down>") :debounce 1 any))
Consult has special support for candidate groups. If the completion UI supports
the grouping functionality, the UI separates the groups with thin lines and
shows group titles. As of now, Vertico, Selectrum and Icomplete-vertical
provide support. Grouping 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.
Note that you can disable the group titles by setting the
:group property of
the corresponding command to nil using the
By entering a narrowing prefix or by pressing a narrowing key it is possible to
restrict the completion candidates to a certain candidate group. When you use
consult-buffer command, you can enter the prefix
b SPC to restrict list of
candidates to buffers only. 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
consult-narrow-key, the possible narrowing keys can be shown
C-h. When pressing
C-h after some prefix key, the
prefix-help-command is invoked, which shows the keybinding help window by
default. As a more compact alternative, there is the
command which can be bound to a key, for example
C-h in the
consult-narrow-map, as shown in the example configuration. If which-key is
installed, the narrowing keys are automatically shown in the which-key window
after pressing the
Consult has support for asynchronous generation of candidate lists. This
feature is used for search commands like
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 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. There are multiple splitting styles available, configured in
perl. The default
splitting style is configured with the variable
semicolon splitting styles, the first word before the comma
or semicolon is passed to grep, the remaining string is used for filtering. The
nil splitting style does not perform any splitting, the whole input is passed
perl splitting style splits the input string at a punctuation character,
using a similar syntax as Perl regular expressions.
#defun: Search for "defun" using grep.
#consult embark: Search for both "consult" and "embark" 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 than
consult-async-min-inputcharacters by default.
#defun -- --invert-match#: Pass argument
Asynchronous processes like
grep create an error log buffer
_*consult-async* (note the leading space), which is useful for
troubleshooting. 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.
Multiple synchronous candidate sources can be combined. This feature
is used by the
consult-buffer command to present buffer-like candidates in a
single menu for quick access. By default
consult-buffer includes buffers,
bookmarks, recent files and project-specific buffers and files. It is possible
to configure the list of sources via the
Arbitrary custom sources can be defined.
As an example, the bookmark source is defined as follows:
(defvar consult--source-bookmark `(:name "Bookmark" :narrow ?m :category bookmark :face consult-bookmark :history bookmark-history :items ,#'bookmark-all-names :action ,#'consult--bookmark-action))
Required source fields:
:itemsList of strings to select from or function returning list of strings.
Optional source fields:
:nameName of the source, used for narrowing, group titles and annotations.
:narrowNarrowing character or
(character . string)pair.
:preview-keyPreview key or keys which trigger preview.
:enabledFunction which must return t if the source is enabled.
:hiddenWhen t candidates of this source are hidden by default.
:faceFace used for highlighting the candidates.
:annotateAnnotation function called for each candidate, returns string.
:historyName of history variable to add selected candidate.
:defaultMust be t if the first item of the source is the default value.
:actionAction function called with the selected candidate.
:stateState constructor for the source, must return the state function.
:action fields of the sources deserve a longer explanation.
:action function takes a single argument and is only called after
selection with the selected candidate, if the selection has not been aborted.
This functionality is provided for convenience and easy definition of sources.
:state field is more complicated and general. The
:state function is a
constructor function without arguments, which can perform some setup
necessary for the preview. It must return a closure with two arguments: The
first argument is the candidate string, the second argument is the restore
flag. The state function is called during preview, if a preview key has been
pressed, with the selected candidate or nil and the restore argument being
nil. Furthermore the state function is always called after selection with the
selected candidate or nil. The state function is called with nil for the
candidate if for example the selection process has been aborted or if the
original preview state should be restored during preview. The restore flag is
t for the final call. The final call happens even if preview is disabled. For
this reason you can also use the final call to the state function in a similar
:action. You probably only want to specify both
:state is purely responsible for preview and
:action is then
responsible for the real action after selection.
In order to avoid slowness,
consult-buffer only preview buffers by default.
Loading recent files, bookmarks or views can result in expensive operations.
However it is possible to configure the bookmark and file sources to also
(consult-customize consult--source-file consult--source-project-file consult--source-bookmark :preview-key (kbd "M-."))
Sources can be added directly to the
consult-buffer-source list for
convenience. For example views can be added to the list of virtual buffers
from a library like https://github.com/minad/bookmark-view/.
;; Configure new bookmark-view source (add-to-list 'consult-buffer-sources (list :name "View" :narrow ?v :category 'bookmark :face 'font-lock-keyword-face :history 'bookmark-view-history :action #'consult--bookmark-jump :items #'bookmark-view-names) 'append) ;; Modify bookmark source, such that views are hidden (setq consult--source-bookmark (plist-put consult--source-bookmark :items (lambda () (bookmark-maybe-load-default-file) (mapcar #'car (seq-remove (lambda (x) (eq #'bookmark-view-handler (alist-get 'handler (cdr x)))) bookmark-alist)))))
Other useful sources allow the creation of terminal and eshell buffers if they do not exist yet.
(defun mode-buffer-exists-p (mode) (seq-some (lambda (buf) (provided-mode-derived-p (buffer-local-value 'major-mode buf) mode)) (buffer-list))) (defvar eshell-source `(:category 'consult-new :face 'font-lock-constant-face :action ,(lambda (_) (eshell)) :items ,(lambda () (unless (mode-buffer-exists-p 'eshell-mode) '("*eshell* (new)"))))) (defvar term-source `(:category 'consult-new :face 'font-lock-constant-face :action ,(lambda (_) (ansi-term (or (getenv "SHELL") "/bin/sh"))) :items ,(lambda () (unless (mode-buffer-exists-p 'term-mode) '("*ansi-term* (new)"))))) (add-to-list 'consult-buffer-sources 'eshell-source 'append) (add-to-list 'consult-buffer-sources 'term-source 'append)
For more details, see the documentation of
consult-buffer and of the
consult--multi API. The
consult--multi function can be used to
create new multi-source commands, but is part of the internal API as of now,
since some details may still change.
NOTE: 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. With Embark you can execute arbitrary commands
on the currently selected candidate via
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
exports 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, particularly exciting is the possibility to export
the matching lines from
consult-global-mark. The matching lines are exported to an Occur buffer where
they can be edited via the
occur-edit-mode (press key
Embark supports exporting the matches found by
consult-git-grep to a Grep buffer, where the matches
across files can be edited, if the wgrep package is installed. The two
workflows are symmetric.
occur-edit-modefor editing of matches in buffer.
wgrepfor editing of all matches.
There is the Consult wiki, where additional configuration examples can be contributed.
IMPORTANT: It is strongly recommended that you enable lexical binding in your configuration. Consult uses a functional programming style, relying on lambdas and lexical closures. For this reason many Consult-related snippets require lexical binding.
The Consult package only provides commands and does not add any keybindings or
modes. Therefore the package is non-intrusive but requires a little setup
effort. In order to use the Consult commands, it is advised to add keybindings
for commands which are accessed often. Rarely used commands can be invoked via
M-x. Feel free to only bind the commands you consider useful to your workflow.
The configuration shown here relies on the
use-package macro, which is a
convenient tool to manage package configurations.
NOTE: There is the Consult wiki, where you can contribute additional configuration examples.
;; Example configuration for Consult (use-package consult ;; Replace bindings. Lazily loaded due by `use-package'. :bind (;; C-c bindings (mode-specific-map) ("C-c h" . consult-history) ("C-c m" . consult-mode-command) ("C-c b" . consult-bookmark) ("C-c k" . consult-kmacro) ;; C-x bindings (ctl-x-map) ("C-x M-:" . consult-complex-command) ;; orig. repeat-complex-command ("C-x b" . consult-buffer) ;; orig. switch-to-buffer ("C-x 4 b" . consult-buffer-other-window) ;; orig. switch-to-buffer-other-window ("C-x 5 b" . consult-buffer-other-frame) ;; orig. switch-to-buffer-other-frame ;; Custom M-# bindings for fast register access ("M-#" . consult-register-load) ("M-'" . consult-register-store) ;; orig. abbrev-prefix-mark (unrelated) ("C-M-#" . consult-register) ;; Other custom bindings ("M-y" . consult-yank-pop) ;; orig. yank-pop ("<help> a" . consult-apropos) ;; orig. apropos-command ;; M-g bindings (goto-map) ("M-g e" . consult-compile-error) ("M-g f" . consult-flymake) ;; Alternative: consult-flycheck ("M-g g" . consult-goto-line) ;; orig. goto-line ("M-g M-g" . consult-goto-line) ;; orig. goto-line ("M-g o" . consult-outline) ;; Alternative: consult-org-heading ("M-g m" . consult-mark) ("M-g k" . consult-global-mark) ("M-g i" . consult-imenu) ("M-g I" . consult-imenu-multi) ;; M-s bindings (search-map) ("M-s f" . consult-find) ("M-s F" . consult-locate) ("M-s g" . consult-grep) ("M-s G" . consult-git-grep) ("M-s r" . consult-ripgrep) ("M-s l" . consult-line) ("M-s L" . consult-line-multi) ("M-s m" . consult-multi-occur) ("M-s k" . consult-keep-lines) ("M-s u" . consult-focus-lines) ;; Isearch integration ("M-s e" . consult-isearch) :map isearch-mode-map ("M-e" . consult-isearch) ;; orig. isearch-edit-string ("M-s e" . consult-isearch) ;; orig. isearch-edit-string ("M-s l" . consult-line) ;; needed by consult-line to detect isearch ("M-s L" . consult-line-multi)) ;; needed by consult-line to detect isearch ;; Enable automatic preview at point in the *Completions* buffer. ;; This is relevant when you use the default completion UI, ;; and not necessary for Vertico, Selectrum, etc. :hook (completion-list-mode . consult-preview-at-point-mode) ;; The :init configuration is always executed (Not lazy) :init ;; Optionally configure the register formatting. This improves the register ;; preview for `consult-register', `consult-register-load', ;; `consult-register-store' and the Emacs built-ins. (setq register-preview-delay 0 register-preview-function #'consult-register-format) ;; Optionally tweak the register preview window. ;; This adds thin lines, sorting and hides the mode line of the window. (advice-add #'register-preview :override #'consult-register-window) ;; Optionally replace `completing-read-multiple' with an enhanced version. (advice-add #'completing-read-multiple :override #'consult-completing-read-multiple) ;; Use Consult to select xref locations with preview (setq xref-show-xrefs-function #'consult-xref xref-show-definitions-function #'consult-xref) ;; Configure other variables and modes in the :config section, ;; after lazily loading the package. :config ;; Optionally configure preview. The default value ;; is 'any, such that any key triggers the preview. ;; (setq consult-preview-key 'any) ;; (setq consult-preview-key (kbd "M-.")) ;; (setq consult-preview-key (list (kbd "<S-down>") (kbd "<S-up>"))) ;; For some commands and buffer sources it is useful to configure the ;; :preview-key on a per-command basis using the `consult-customize' macro. (consult-customize consult-theme :preview-key '(:debounce 0.2 any) consult-ripgrep consult-git-grep consult-grep consult-bookmark consult-recent-file consult-xref consult--source-file consult--source-project-file consult--source-bookmark :preview-key (kbd "M-.")) ;; Optionally configure the narrowing key. ;; Both < and C-+ work reasonably well. (setq consult-narrow-key "<") ;; (kbd "C-+") ;; Optionally make narrowing help available in the minibuffer. ;; You may want to use `embark-prefix-help-command' or which-key instead. ;; (define-key consult-narrow-map (vconcat consult-narrow-key "?") #'consult-narrow-help) ;; Optionally configure a function which returns the project root directory. ;; There are multiple reasonable alternatives to chose from. ;;;; 1. project.el (project-roots) (setq consult-project-root-function (lambda () (when-let (project (project-current)) (car (project-roots project))))) ;;;; 2. projectile.el (projectile-project-root) ;; (autoload 'projectile-project-root "projectile") ;; (setq consult-project-root-function #'projectile-project-root) ;;;; 3. vc.el (vc-root-dir) ;; (setq consult-project-root-function #'vc-root-dir) ;;;; 4. locate-dominating-file ;; (setq consult-project-root-function (lambda () (locate-dominating-file "." ".git"))) )
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.
|consult-after-jump-hook||Functions to call after jumping to a location|
|consult-async-input-debounce||Input debounce for asynchronous commands|
|consult-async-input-throttle||Input throttle for asynchronous commands|
|consult-async-min-input||Minimum numbers of letters needed for async process|
|consult-async-refresh-delay||Refresh delay for asynchronous commands|
|consult-async-split-style||Splitting style used for async commands|
|consult-async-split-styles-alist||Available splitting styles used for async commands|
|consult-bookmark-narrow||Narrowing configuration for
|consult-buffer-sources||List of virtual buffer sources|
|consult-crm-prefix||Prefix string for CRM candidates|
|consult-find-args||Command line arguments for find|
|consult-fontify-max-size||Buffers larger than this limit are not fontified|
|consult-fontify-preserve||Preserve fontification for line-based commands.|
|consult-git-grep-args||Command line arguments for git-grep|
|consult-goto-line-numbers||Show line numbers for
|consult-grep-max-columns||Maximal number of columns of the matching lines|
|consult-grep-args||Command line arguments for grep|
|consult-imenu-config||Mode-specific configuration for
|consult-line-numbers-widen||Show absolute line numbers when narrowing is active.|
|consult-line-point-placement||Placement of the point used by
|consult-locate-args||Command line arguments for locate|
|consult-man-args||Command line arguments for man|
|consult-mode-histories||Mode-specific history variables|
|consult-narrow-key||Narrowing prefix key during completion|
|consult-preview-key||Keys which triggers preview|
|consult-preview-max-count||Maximum number of files to keep open during preview|
|consult-preview-max-size||Files larger than this size are not previewed|
|consult-preview-raw-size||Files larger than this size are previewed in raw form|
|consult-project-root-function||Function which returns current project root|
|consult-register-narrow||Narrowing configuration for
|consult-ripgrep-args||Command line arguments for ripgrep|
|consult-themes||List of themes to be presented for selection|
|consult-widen-key||Widening key during completion|
NOTE: Consult supports fine-grained customization of individual commands. This configuration feature exists for experienced users with special requirements. There is the Consult wiki, where we collect further configuration examples.
Commands and buffer sources allow flexible, individual customization by using
consult-customize macro. You can override any option passed to the internal
consult--read API. The Consult wiki already contains a numerous useful
configuration examples. Note that since
consult--read is part of the internal
API, options could be removed, replaced or renamed in future versions of the
Useful options are:
:promptset the prompt string
:preview-keyset the preview key, default is
:initialset the initial input
:defaultset the default value
:historyset the history variable symbol
:add-historyadd items to the future history, for example symbol at point
:sortenable or disable sorting
:groupset to nil to disable candidate grouping and titles.
:inherit-input-methodset to non-nil to inherit the input method.
(consult-customize ;; Disable preview for `consult-theme' completely. consult-theme :preview-key nil ;; Set preview for `consult-buffer' to key `M-.' consult-buffer :preview-key (kbd "M-.") ;; For `consult-line' change the prompt and specify multiple preview ;; keybindings. Note that you should bind <S-up> and <S-down> in the ;; `minibuffer-local-completion-map' or `vertico-map' to the commands which ;; select the previous or next candidate. consult-line :prompt "Search: " :preview-key (list (kbd "<S-down>") (kbd "<S-up>")))
Generally it is possible to modify commands for your individual needs by the following techniques:
consult-customizein order to change the command or source settings.
It is highly recommended to install the following package combination:
There exist packages which integrate Consult with special programs or with other packages in the Emacs ecosystem. You may want to install some of them depending on your personal preferences.
Not directly related to Consult, but maybe still of interest are the following
packages. These packages should work well with Consult, follow a similar spirit or
offer functionality based on
completion-at-pointusing small popups.
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 default completion and Consult and add more components later to the mix. For example Embark can be omitted if action support is not desired.
The Selectrum repository provides a set of scripts which allow experimenting
with multiple package combinations of completion systems and Consult. After
cloning the repository, you can execute the scripts with
./run.sh <package-combo.el>. The scripts do not modify your existing Emacs
configuration, but create a separate Emacs configuration in
If you find a bug or suspect that there is a problem with Consult, please carry out the following steps:
icomplete-modeis enabled. Furthermore both
helm-modemust be disabled.
completion-stylesvariable is properly configured. Try to set
completion-stylesto a list including
emacs -Qon the command line. Execute the following minimal code snippets in the scratch buffer. This way we can exclude side effects due to configuration settings. If other packages are relevant to reproduce the issue, include them in the minimal configuration snippet.
Minimal setup with Vertico for
(package-initialize) (require 'consult) (require 'vertico) (vertico-mode) (setq completion-styles '(substring))
Minimal setup with the default completion system for
(package-initialize) (require 'consult) (setq completion-styles '(substring))
Please provide the necessary important information with your bug report:
When evaluating Consult-related code snippets you should enable lexical binding. Consult often uses a functional programming style, relying on lambdas and lexical closures.
Consult is a community effort, please participate in the discussions. Contributions are welcome, but you may want to discuss potential contributions first. Since this package is part of GNU ELPA contributions require a copyright assignment to the FSF.
If you have a proposal, take a look at the Consult issue tracker and the Consult wishlist. There exists a rich set of prior feature discussions. You can contribute to the Consult wiki, in case you want to share small configuration or command snippets.
You probably guessed from the name that this package took inspiration from Counsel by Oleh Krehel. Some of the Consult commands originated in the Counsel package or the Selectrum wiki. The commands have been rewritten and greatly enhanced in comparison to the original versions.
Advice and useful discussions:
Authors of supplementary