consult.el - Consulting completing-read

Introduction

Consult provides various practical commands based on the Emacs completion function completing-read, which allows to quickly select an item from a list of candidates with completion. Consult offers in particular an advanced buffer switching command consult-buffer to switch between buffers and recently opened files. Multiple search commands are provided, an asynchronous consult-grep and consult-ripgrep, and consult-line, which resembles Swiper. 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 preview and narrowing support. 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, Icomplete, Selectrum, Vertico and Embark. In case you like to use Icomplete, it is recommended to enable a vertical display mode. recommended. On Emacs 28, Icomplete offers the built-in icomplete-vertical-mode and on earlier Emacs versions you can install the external Icomplete-vertical package.

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 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 come with their own set of commands.

There are the Marginalia and Embark packages, which can be combined 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 can be executed 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 can also be used as a completion system by itself through its live-updating collect buffer. The Embark integration is described later in greater detail.

Screenshots

Fig. 1: Command consult-git-grep

Fig. 2: Command consult-imenu

Fig. 3: Command consult-line

Available 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 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

consult-buffer (-other-window, -other-frame): 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. Ephemeral buffers can be shown by pressing SPC. Supported narrowing keys:
- b Buffers
- f Files (Requires recentf-mode)
- m Bookmarks
- p Project (only available if consult-project-root-function is configured as shown in the example configuration).
- Arbitrary other sources can be configured via consult-buffer-sources.
By default only buffers are preview in order to ensure that consult-buffer is fast, but it is possible to configure file and bookmark preview.
consult-bookmark: Select or create bookmark. You might use the powerful consult-buffer as an alternative, which can include a bookmark virtual buffer source. But 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. Note that recentf-mode should be enabled in order to track recent files.

Editing

consult-yank-from-kill-ring: Enhanced version of yank which allows 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 allows to select an item from 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

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 consult-register-load or consult-register-store or the built-in Emacs register commands.
consult-register-format: Supplementary register formatting function which can be used as register-preview-function for an enhanced register formatting. See the example configuration.
consult-register-window: Supplementary function which can be used as replacement for register-preview 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 x.
- M-' M-w x: Store window configuration in register x.
- C-u 100 M-' x: Store number in register x.

Navigation

consult-goto-line: Jump to line number enhanced with live preview. This is a drop-in replacement for goto-line.
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-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 pressing M-n. When consult-line is bound to the isearch-mode-map and is invoked during a running Isearch, it will use the current Isearch string.
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 to pick a string from the history and starts a new Isearch. This command can be used as a drop-in replacement for isearch-edit-string.
consult-multi-occur: Replacement for multi-occur which uses completing-read-multiple.
consult-keep-lines: Replacement for keep/flush-lines which uses 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 during completing-read. If the input begins with the negation operator, i.e., ! SPC, the filter matches the complement. If a region is active, the filtering is restricted to that region.
consult-focus-lines: Temporarily hide lines by filtering them using the current completion style. Call with C-u prefix 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-lines this function does not edit the buffer. If a region is active, the focusing is restricted to that region.

Grep and Find

consult-grep, consult-ripgrep, consult-git-grep: Search for regular expression in files. Grep is invoked asynchronously, while you enter the search term. You are required to enter at least consult-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. If the consult-project-root-function is configured and returns non-nil, consult-grep searches the current project directory. Otherwise the default-directory is searched. If consult-grep is invoked with prefix argument C-u M-s g, you can specify the directory manually.
consult-find, consult-locate: Find file by matching the path against a regexp. Like consult-grep either the project root or the current directory is used as 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. Note that the standard find command uses wildcards in contrast to the popular fd, which uses regular expressions. In case you want to use fd, you can either change the consult-find-command configuration variable or define a small command as described in the Consult wiki.

Compilation

consult-compile-error: Jump to a compilation error. Supports live preview narrowing and and recursive editing.
consult-flymake: Jump to flymake diagnostic. Supports live preview and recursive editing. The command supports narrowing. Press e SPC, w SPC, n SPC to 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-flycheck package since the main consult package only depends on Emacs core components.
consult-xref: Integration with xref. This function can be set as as xref-show-xrefs-function and xref-show-definitions-function.

Histories

consult-complex-command: Select a command from the command-history. This command is a completing-read version of repeat-complex-command and can also be considered a replacement for the command-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.

Modes

consult-minor-mode-menu: Enable/disable minor mode. Supports narrowing to on/off/local/global modes by pressing i/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 keys l/g/m.

Org Mode

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.

Miscellaneous

consult-apropos: Replacement for apropos with completion.
consult-man: Find Unix man page, via Unix apropos or man -k. The selected man page is opened using the Emacs man command.
consult-file-externally: Select a file and open it externally, e.g. using xdg-open on Linux.
consult-completion-in-region: Function which can be used as completion-in-region-function. This way, the minibuffer completion UI will be used for completion-at-point. This function is particularily 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. However you may not want to transfer the completion at point into the minibuffer and prefer to see the completions directly in the buffer as a small popup. In that case you can either use the Corfu or the Company package.
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 and consult-preview-at-point-mode: Command and minor mode which allows preview 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.

Special features

Consult enhances completing-read with live previews of candidates, additional narrowing capabilities to candidate groups 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. 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.

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 and grouping

Consult has special support for candidate groups which are separated by separator lines with titles if supported by the completion system. As of now, Selectrum, Vertico and Icomplete-vertical provide support. 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. Note that the group titles can be disabled by setting the :group property of the corresponding command to using the consult-customize macro.

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 the consult-buffer command, you can enter the prefix b SPC and the list of candidates will be restricted 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 configuration variables consult-narrow-key and consult-widen-key.

After pressing consult-narrow-key, the possible narrowing keys can be shown by pressing 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 consult-narrow-help command which can be bound to a key, for example ? or 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-narrow-key.

Asynchronous search

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 consult-async-split-styles-alist: space, comma, semicolon and perl. The default splitting style is configured with the variable consult-async-split-style.

For the space=/=comma=/=semicolon splitting styles, the first word before the space/comma/semicolon is passed to grep, the remaining string is used for filtering.

For the perl splitting style, 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 than consult-async-min-input characters by default.
#defun -- --invert-match#: Pass argument --invert-match to grep.

For asynchronous processes like find and grep, there is an error log buffer _*consult-async* (note the leading space). 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 sources

Consult allows combining multiple synchronous candidate sources. 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 consult-buffer-sources variable. 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:

:category Completion category.
:items List of strings to select from or function returning list of strings.

Optional source fields:

:name Name of the source, used for narrowing, group titles and annotations.
:narrow Narrowing character or (character . string) pair.
:preview-key Preview key or keys which trigger preview.
:enabled Function which must return t if the source is enabled.
:hidden When t candidates of this source are hidden by default.
:face Face used for highlighting the candidates.
:annotate Annotation function called for each candidate, returns string.
:history Name of history variable to add selected candidate.
:default Must be t if the first item of the source is the default value.
:action Action function called with the selected candidate.
:state State constructor for the source, must return the state function.
Other source fields can be added specifically to the use case.

The :state and :action fields of the sources deserve a longer explanation. The :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. The :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 way as :action. You probably only want to specify both :state and :action if :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 perform preview.

(dolist (src '(consult--source-file consult--source-project-file consult--source-bookmark))
  (set src (plist-put (symbol-value src) :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 internal 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.

Embark integration

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. 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. The two workflows are symmetric.

consult-line -> embark-export to occur-mode buffer -> occur-edit-mode for editing of matches in buffer.
consult-grep -> embark-export to grep-mode buffer -> wgrep for editing of all matches.

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.

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.

Use-package example

It is recommended to manage package configurations with the use-package macro. 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.

NOTE: There is the Consult wiki, where additional configuration examples can be contributed.

;; 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)
         ("M-g m" . consult-mark)
         ("M-g k" . consult-global-mark)
         ("M-g i" . consult-imenu)
         ("M-g I" . consult-project-imenu)
         ;; M-s bindings (search-map)
         ("M-s f" . consult-find)
         ("M-s L" . 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 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))                 ;; required 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 Selectrum, Vertico 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)

  ;; 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-ripgrep consult-git-grep consult-grep consult-bookmark consult-recent-file
   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")))
)

Custom 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-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-async-split-style	‘perl	Splitting style used for async commands
consult-async-split-styles-alist	…	Availabla splitting styles used for async commands
consult-bookmark-narrow	…	Narrowing configuration for `consult-bookmark`
consult-buffer-filter	…	Filter for `consult-buffer`
consult-buffer-sources	…	List of virtual buffer sources
consult-find-command	“find …”	Command line arguments for find
consult-fontify-max-size	1048576	Buffers larger than this limit are not fontified
consult-fontify-preserve	t	Preserve fontification for line-based commands.
consult-git-grep-command	’(…)	Command line arguments for git-grep
consult-goto-line-numbers	t	Show line numbers for `consult-goto-line`
consult-grep-max-colums	250	Maximal number of columns of the matching lines
consult-grep-command	“grep …”	Command line arguments for grep
consult-imenu-config	…	Mode-specific configuration for `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-line-start-from-top	nil	Start the `consult-line` search from the top
consult-locate-command	“locate …”	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	Files larger than this size are not previewed
consult-preview-raw-size	102400	Files larger than this size are previewed in raw form
consult-project-root-function	nil	Function which returns current project root
consult-register-narrow	…	Narrowing configuration for `consult-register`
consult-ripgrep-command	“rg …”	Command line arguments for ripgrep
consult-themes	nil	List of themes to be presented for selection
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 and buffer sources allow flexible, individual customization by using the consult-customize macro. You can override any option passed to the internal consult--read API. The Consult wiki already contains a few 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 package.

Useful options are:

:prompt set the prompt string
:preview-key set the preview key, default is consult-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
:group set to nil in order to disable candidate grouping and titles.

(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', `selectrum-minibuffer-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:

Use consult-customize in order to change the command or source settings.
Create your own wrapper function which passes modified arguments to the Consult functions.
Create your own buffer multi sources for consult-buffer.
Create advices to modify some internal behavior.
Write or propose a patch.

Recommended packages

It is highly recommended to install the following package combination:

consult: This package
selectrum, vertico or icomplete-vertical: Vertical completion systems (Icomplete-vertical is only needed for Emacs 27, built-in on Emacs 28)
marginalia: Annotations for the completion candidates
embark and embark-consult: Action commands, which can act on the completion candidates
orderless: Completion style which offers flexible candidate filtering

There exist a few 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.

consult-flycheck: Provides the consult-flycheck command.
consult-lsp: Integration with LSP-Mode (Language Server Protocol).
consult-notmuch: Access the Notmuch email system using Consult.
consult-recoll: Access the Recoll desktop full-text search using Consult.
consult-spotify: Access the Spotify API and control your local music player.
affe: Asynchronous Fuzzy Finder for Emacs (uses Consult under the hood).

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 completing-read.

corfu, company: Completion systems for completion-at-point using small popups.
bookmark-view: Store window configuration as bookmarks, possible integration with consult-buffer.
flyspell-correct: Apply spelling corrections by selecting via completing-read.
wgrep: Editing of grep buffers, can be used together with consult-grep via embark-export.
prescient: Sorts completion candidates according to frecency (Selectrum-specific, Orderless is recommended instead).

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 including various completion systems and Consult. After cloning the Selectrum repository, the scripts can be executed with cd selectrum/test; ./run.sh <package-combo.el>. The scripts do not modify your existing Emacs configuration, but create a separate Emacs configuration in /tmp.

Bug reports

If you find a bug or suspect that there is a problem with Consult, please carry out the following steps:

Check first that all the relevant packages are updated to the newest version. This includes Consult, Selectrum, Vertico, Icomplete-vertical, Marginalia, Embark, Orderless and Prescient in case you are using any of those packages.
Ensure that either icomplete-mode, selectrum-mode or vertico-mode is enabled. Furthermore ivy-mode and helm-mode must be disabled.
Ensure that the completion-styles variable is properly configured. Try to set completion-styles to a list including substring or orderless.
Try to reproduce the issue by starting a barebone Emacs instance with emacs -Q on 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 Selectrum for emacs -Q:

(package-initialize)
(require 'consult)
(require 'selectrum)
(selectrum-mode)
(setq completion-styles '(substring))

Minimal setup with Vertico for emacs -Q:

(package-initialize)
(require 'consult)
(require 'vertico)
(vertico-mode)
(setq completion-styles '(substring))

Minimal setup with the default completion system for emacs -Q:

(package-initialize)
(require 'consult)
(setq completion-styles '(substring))

Please provide the necessary important information with your bug report:

The minimal configuration snippet used to reproduce the issue.
The full stack trace in case the bug triggers an exception.
Your Emacs version, since bugs are often version-dependant.
Your operating system, since Emacs builds vary between Linux, Mac and Windows.
The package manager, e.g., straight.el or package.el, used to install the Emacs packages. This information is helpful to exclude update issues.
If you are using Evil or other special packages which change Emacs on a fundamental level. There have been Evil-related problems before, which are fixed now.

When evaluating Consult-related code snippets it is required to enable lexical binding. Consult uses a functional programming style, relying on lambdas and lexical closures.

Contributions

Consult is intended to be a community effort, please participate in the discussions. Contributions are welcome, but it is recommended to discuss potential contributions first. Since it is planned to submit the package to GNU ELPA, copyright assigments to the FSF are a requirement for contributions.

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.

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 Counsel package or the Selectrum wiki. The commands have been rewritten and greatly enhanced in comparison to the original versions. In particular all Selectrum-specific code has been removed, such that the commands are compatible with the completing-read API.

Code contributions:

Advice and useful discussions:

Authors of supplementary consult-* packages:

zetagon / consult Goto Github PK

consult's Introduction