consult.el - Consulting completing-read

Table of Contents

Next:   [Contents][Index]

consult.el - Consulting completing-read

Consult provides search and navigation commands based on the Emacs completion function completing-read. Completion allows you to quickly select an item from a list of candidates. Consult offers asynchronous and interactive ‘consult-grep’ and ‘consult-ripgrep’ commands, and the line-based search command ‘consult-line’. Furthermore Consult provides an advanced buffer switching command ‘consult-buffer’ to switch between buffers, recently opened files, bookmarks and buffer-like candidates from other sources. Some of the Consult commands are enhanced versions of built-in Emacs commands. For example the command ‘consult-imenu’ presents a flat list of the Imenu with live preview, grouping and narrowing. Please take a look at the full list of commands.

Consult is fully compatible with completion systems centered around the standard Emacs ‘completing-read’ API, notably the default completion system, Vertico, Mct, and Icomplete.

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

You can combine the complementary packages 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 at point in normal buffers. For example, when selecting from a list of files, Embark offers an action to delete the file. Additionally Embark offers a facility to collect completion candidates in a collect buffer. The section Embark integration documents in greater detail how Consult and Embark work together.


Next: , Previous: , Up: Top   [Contents][Index]

1 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.


Next: , Up: Available commands   [Contents][Index]

1.1 Virtual Buffers


Next: , Previous: , Up: Available commands   [Contents][Index]

1.2 Editing


Next: , Previous: , Up: Available commands   [Contents][Index]

1.3 Register


Next: , Previous: , Up: Available commands   [Contents][Index]

1.4 Navigation


Next: , Previous: , Up: Available commands   [Contents][Index]

1.5 Search


Next: , Previous: , Up: Available commands   [Contents][Index]

1.6 Grep and Find


Next: , Previous: , Up: Available commands   [Contents][Index]

1.7 Compilation


Next: , Previous: , Up: Available commands   [Contents][Index]

1.8 Histories


Next: , Previous: , Up: Available commands   [Contents][Index]

1.9 Modes


Next: , Previous: , Up: Available commands   [Contents][Index]

1.10 Org Mode


Next: , Previous: , Up: Available commands   [Contents][Index]

1.11 Help

(defun consult-info-emacs ()
  "Search through Emacs info pages."
  (interactive)
  (consult-info "emacs" "efaq" "elisp" "cl" "compat"))

(defun consult-info-org ()
  "Search through the Org info page."
  (interactive)
  (consult-info "org"))

(defun consult-info-completion ()
  "Search through completion info pages."
  (interactive)
  (consult-info "vertico" "consult" "marginalia" "orderless" "embark"
                "corfu" "cape" "tempel"))

Previous: , Up: Available commands   [Contents][Index]

1.12 Miscellaneous


Next: , Previous: , Up: Top   [Contents][Index]

2 Special features

Consult enhances ‘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.


Next: , Up: Special features   [Contents][Index]

2.1 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.

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 ‘consult-preview-key’ is ‘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 ‘:preview-key’. The following settings are possible:

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. Internally, Consult uses the value of ‘this-command’ to determine the ‘:preview-key’ customized. This means that if you wrap a ‘consult-*’ command within your own function or command, you will also need to add the name of your custom command to the ‘consult-customize’ call in order for it to be considered.

(consult-customize
 consult-ripgrep consult-git-grep consult-grep
 consult-bookmark consult-recent-file consult-xref
 consult--source-bookmark consult--source-file-register
 consult--source-recent-file consult--source-project-recent-file
 ;; my/command-wrapping-consult    ;; disable auto previews inside my command
 :preview-key '(:debounce 0.4 any) ;; Option 1: Delay preview
 ;; :preview-key "M-.")            ;; Option 2: Manual preview

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. During preview some functionality is disabled to improve the performance, see for example the customization variables ‘consult-preview-variables’ and ‘consult-preview-allowed-hooks’. Only the hooks listed in ‘consult-preview-allowed-hooks’ are executed when a file is opened (‘find-file-hook’). In order to enable additional font locking during preview, add the corresponding hooks to the allow list. The following code demonstrates this for org-modern and hl-todo.

(add-to-list 'consult-preview-allowed-hooks 'global-org-modern-mode-check-buffers)
(add-to-list 'consult-preview-allowed-hooks 'global-hl-todo-mode-check-buffers)

Files larger than ‘consult-preview-raw-size’ are previewed literally without syntax highlighting and without changing the major mode. Delaying the preview is also useful for ‘consult-theme’, since the theme preview is slow. The delay results in a smoother UI experience.

;; 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
                   '("M-."
                     :debounce 0.5 "<up>" "<down>"
                     :debounce 1 any))

Next: , Previous: , Up: Special features   [Contents][Index]

2.2 Narrowing and grouping

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. 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 ‘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’ 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 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’.


Next: , Previous: , Up: Special features   [Contents][Index]

2.3 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 regular expression. The grep process is executed in the background. When modifying the 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: ‘nil’, ‘comma’, ‘semicolon’ and ‘perl’. The default splitting style is configured with the variable consult-async-split-style.

With the ‘comma’ and ‘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 to grep.

The ‘perl’ splitting style splits the input string at a punctuation character, using a similar syntax as Perl regular expressions.

Examples:

Asynchronous processes like ‘find’ and ‘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:


Next: , Previous: , Up: Special features   [Contents][Index]

2.4 Multiple sources

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 ‘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:

Optional source fields:

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 general. The ‘:state’ function is a constructor function without arguments, which can perform some setup necessary for the preview. It must return a closure which takes an ACTION and a CANDIDATE argument. See the docstring of ‘consult--with-preview’ for more details about the ACTION argument.

By default, ‘consult-buffer’ previews buffers, bookmarks and files. Loading recent files or bookmarks can result in expensive operations. However it is possible to configure a manual preview as follows.

(consult-customize
 consult--source-bookmark consult--source-file-register
 consult--source-recent-file consult--source-project-recent-file
 :preview-key "M-.")

Sources can be added directly to the ‘consult-buffer-source’ list for convenience. For example views/perspectives can be added to the list of virtual buffers from a library like 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-action
                    :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)))))

Another useful source lists all Org buffers and lets you create new ones. One can create similar sources for other major modes, e.g., for Eshell.

(defvar org-source
  (list :name     "Org Buffer"
        :category 'buffer
        :narrow   ?o
        :face     'consult-buffer
        :history  'buffer-name-history
        :state    #'consult--buffer-state
        :new
        (lambda (name)
          (with-current-buffer (get-buffer-create name)
            (insert "#+title: " name "\n\n")
            (org-mode)
            (consult--buffer-action (current-buffer))))
        :items
        (lambda ()
          (mapcar #'buffer-name
                  (seq-filter
                   (lambda (x)
                     (eq (buffer-local-value 'major-mode x) 'org-mode))
                   (buffer-list))))))

(add-to-list 'consult-buffer-sources 'org-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.


Previous: , Up: Special features   [Contents][Index]

2.5 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. With Embark you can execute arbitrary commands on the currently selected candidate via ‘M-x’.

Furthermore Embark provides the ‘embark-collect’ 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-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’). Similarly, 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. These three workflows are symmetric.


Next: , Previous: , Up: Top   [Contents][Index]

3 Configuration

Consult can be installed from ELPA or 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 relies on lambdas and lexical closures. For this reason many Consult-related snippets require lexical binding.


Next: , Up: Configuration   [Contents][Index]

3.1 Use-package example

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 in `mode-specific-map'
         ("C-c M-x" . consult-mode-command)
         ("C-c h" . consult-history)
         ("C-c k" . consult-kmacro)
         ("C-c m" . consult-man)
         ("C-c i" . consult-info)
         ([remap Info-search] . consult-info)
         ;; C-x bindings in `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
         ("C-x r b" . consult-bookmark)            ;; orig. bookmark-jump
         ("C-x p b" . consult-project-buffer)      ;; orig. project-switch-to-buffer
         ;; 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
         ;; M-g bindings in `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 in `search-map'
         ("M-s d" . consult-find)
         ("M-s D" . 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 k" . consult-keep-lines)
         ("M-s u" . consult-focus-lines)
         ;; Isearch integration
         ("M-s e" . consult-isearch-history)
         :map isearch-mode-map
         ("M-e" . consult-isearch-history)         ;; orig. isearch-edit-string
         ("M-s e" . consult-isearch-history)       ;; 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
         ;; Minibuffer history
         :map minibuffer-local-map
         ("M-s" . consult-history)                 ;; orig. next-matching-history-element
         ("M-r" . consult-history))                ;; orig. previous-matching-history-element

  ;; Enable automatic preview at point in the *Completions* buffer. This is
  ;; relevant when you use the default completion UI.
  :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.5
        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 "M-.")
  ;; (setq consult-preview-key '("S-<down>" "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-bookmark consult--source-file-register
   consult--source-recent-file consult--source-project-recent-file
   ;; :preview-key "M-."
   :preview-key '(:debounce 0.4 any))

  ;; Optionally configure the narrowing key.
  ;; Both < and C-+ work reasonably well.
  (setq consult-narrow-key "<") ;; "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)

  ;; By default `consult-project-function' uses `project-root' from project.el.
  ;; Optionally configure a different project root function.
  ;;;; 1. project.el (the default)
  ;; (setq consult-project-function #'consult--default-project--function)
  ;;;; 2. vc.el (vc-root-dir)
  ;; (setq consult-project-function (lambda (_) (vc-root-dir)))
  ;;;; 3. locate-dominating-file
  ;; (setq consult-project-function (lambda (_) (locate-dominating-file "." ".git")))
  ;;;; 4. projectile.el (projectile-project-root)
  ;; (autoload 'projectile-project-root "projectile")
  ;; (setq consult-project-function (lambda (_) (projectile-project-root)))
  ;;;; 5. No project support
  ;; (setq consult-project-function nil)
)

Next: , Previous: , Up: Configuration   [Contents][Index]

3.2 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.

VariableDescription
consult-after-jump-hookFunctions to call after jumping to a location
consult-async-input-debounceInput debounce for asynchronous commands
consult-async-input-throttleInput throttle for asynchronous commands
consult-async-min-inputMinimum numbers of letters needed for async process
consult-async-refresh-delayRefresh delay for asynchronous commands
consult-async-split-styleSplitting style used for async commands
consult-async-split-styles-alistAvailable splitting styles used for async commands
consult-bookmark-narrowNarrowing configuration for ‘consult-bookmark
consult-buffer-filterFilter for ‘consult-buffer
consult-buffer-sourcesList of virtual buffer sources
consult-find-argsCommand line arguments for find
consult-fontify-max-sizeBuffers larger than this limit are not fontified
consult-fontify-preservePreserve fontification for line-based commands.
consult-git-grep-argsCommand line arguments for git-grep
consult-goto-line-numbersShow line numbers for ‘consult-goto-line
consult-grep-max-columnsMaximal number of columns of the matching lines
consult-grep-argsCommand line arguments for grep
consult-imenu-configMode-specific configuration for ‘consult-imenu
consult-line-numbers-widenShow absolute line numbers when narrowing is active.
consult-line-start-from-topStart the ‘consult-line’ search from the top
consult-locate-argsCommand line arguments for locate
consult-man-argsCommand line arguments for man
consult-mode-command-filterFilter for ‘consult-mode-command
consult-mode-historiesMode-specific history variables
consult-narrow-keyNarrowing prefix key during completion
consult-point-placementPlacement of the point when jumping to matches
consult-preview-keyKeys which triggers preview
consult-preview-allowed-hooksList of ‘find-file’ hooks to enable during preview
consult-preview-excluded-filesRegexps matched against file names during preview
consult-preview-max-countMaximum number of files to keep open during preview
consult-preview-max-sizeFiles larger than this size are not previewed
consult-preview-raw-sizeFiles larger than this size are previewed in raw form
consult-preview-variablesAlist of variables to bind during preview
consult-project-buffer-sourcesList of virtual project buffer sources
consult-project-functionFunction which returns current project root
consult-register-prefixPrefix string for register keys during completion
consult-ripgrep-argsCommand line arguments for ripgrep
consult-themesList of themes to be presented for selection
consult-widen-keyWidening key during completion
consult-yank-rotateRotate kill ring

Previous: , Up: Configuration   [Contents][Index]

3.3 Fine-tuning of individual commands

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 the ‘consult-customize’ macro. You can override any option passed to the internal ‘consult--read’ API. Note that since ‘consult--read’ is part of the internal API, options could be removed, replaced or renamed in future versions of the package.

Useful options are:

(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 "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 '("S-<down>" "S-<up>"))

The configuration values are evaluated at runtime, just before the completion session is started. Therefore you can use for example ‘thing-at-point’ to adjust the initial input or the future history.

(consult-customize
 consult-line
 :add-history (seq-some #'thing-at-point '(region symbol)))

(defalias 'consult-line-thing-at-point 'consult-line)

(consult-customize
 consult-line-thing-at-point
 :initial (thing-at-point 'symbol))

Generally it is possible to modify commands for your individual needs by the following techniques:

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

Next: , Previous: , Up: Top   [Contents][Index]

4 Recommended packages

I use and recommend this combination of packages:

There exist many other fine completion UIs beside Vertico, which are supported by Consult. Give them a try and find out which interaction model fits best for you.

Note that all packages are independent and can 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 you can omit Marginalia if you don’t need annotations. I highly recommend the Embark package, but in order to familiarize yourself with the other components, you can first start without it - or you could use with Embark right away and add the other components later on.


Next: , Previous: , Up: Top   [Contents][Index]

5 Auxiliary packages

You can integrate Consult with special programs or with other packages in the wider Emacs ecosystem. You may want to install some of theses packages depending on your preferences and requirements.

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.


Next: , Previous: , Up: Top   [Contents][Index]

6 Bug reports

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

  1. Search through the issue tracker if your issue has been reported before (and has been resolved eventually) in the meantime.
  2. Remove all packages involved in the suspected bug from your installation.
  3. Reinstall the newest version of all relevant packages. Updating alone is not sufficient, since package.el is known to cause miscompilation. The list of packages includes Consult, Compat, Vertico or other completion UIs, Marginalia, Embark and Orderless.
  4. Either use the default completion UI or ensure that exactly one of ‘vertico-mode’, ‘mct-mode’, or ‘icomplete-mode’ is enabled. The unsupported modes ‘selectrum-mode’, ‘ivy-mode’, ‘helm-mode’, ‘ido-mode’ and ‘ido-ubiquitous-mode’ must be disabled.
  5. Ensure that the ‘completion-styles’ variable is properly configured. Try to set ‘completion-styles’ to a list including ‘substring’ or ‘orderless’.
  6. Try to reproduce the issue by starting a bare bone 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 Vertico for ‘emacs -Q’:

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

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

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

Please provide the necessary important information with your bug report:

When evaluating Consult-related code snippets you should enable lexical binding. Consult often relies on lambdas and lexical closures.


Next: , Previous: , Up: Top   [Contents][Index]

7 Contributions

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 have been many prior feature discussions. Please search through the issue tracker, maybe your issue or feature request has already been discussed. You can contribute to the Consult wiki, in case you want to share small configuration or command snippets.


Next: , Previous: , Up: Top   [Contents][Index]

8 Acknowledgments

This package took inspiration from Counsel by Oleh Krehel. Some of the Consult commands originated in the Counsel package or the wiki of the Selectrum package. This package exists only thanks to the help of these great contributors and thanks to the feedback of many users. Thank you!

Code contributions:

Advice and useful discussions:

Authors of supplementary ‘consult-*’ packages:


Previous: , Up: Top   [Contents][Index]

9 Indices


Next: , Up: Indices   [Contents][Index]

9.1 Function index

Jump to:   C  
Index Entry  Section

C
consult-bookmark: Virtual Buffers
consult-buffer: Virtual Buffers
consult-buffer-other-frame: Virtual Buffers
consult-buffer-other-window: Virtual Buffers
consult-compile-error: Compilation
consult-completion-in-region: Miscellaneous
consult-complex-command: Histories
consult-find: Grep and Find
consult-flymake: Compilation
consult-focus-lines: Search
consult-git-grep: Grep and Find
consult-global-mark: Navigation
consult-goto-line: Navigation
consult-grep: Grep and Find
consult-history: Histories
consult-imenu: Navigation
consult-imenu-multi: Navigation
consult-info: Help
consult-isearch-history: Histories
consult-keep-lines: Search
consult-kmacro: Editing
consult-line: Search
consult-line-multi: Search
consult-locate: Grep and Find
consult-man: Help
consult-mark: Navigation
consult-minor-mode-menu: Modes
consult-mode-command: Modes
consult-org-agenda: Org Mode
consult-org-heading: Org Mode
consult-outline: Navigation
consult-preview-at-point: Miscellaneous
consult-preview-at-point-mode: Miscellaneous
consult-project-buffer: Virtual Buffers
consult-recent-file: Virtual Buffers
consult-register: Register
consult-register-format: Register
consult-register-load: Register
consult-register-store: Register
consult-register-window: Register
consult-ripgrep: Grep and Find
consult-theme: Miscellaneous
consult-xref: Compilation
consult-yank-from-kill-ring: Editing
consult-yank-pop: Editing
consult-yank-replace: Editing

Jump to:   C  

Previous: , Up: Indices   [Contents][Index]

9.2 Concept index

Jump to:   A   C   E   F   G   H   L   M   N   P   R   S   U   V  
Index Entry  Section

A
asynchronous search: Asynchronous search

C
commands: Available commands
compilation errors: Compilation
customization: Custom variables

E
editing: Editing
embark: Embark integration

F
find: Grep and Find

G
grep: Grep and Find

H
history: Histories

L
locate: Grep and Find

M
major mode: Modes
minor mode: Modes
multiple sources: Multiple sources

N
narrowing: Narrowing and grouping
navigation: Navigation

P
preview: Live previews

R
register: Register

S
search: Search

U
use-package: Use-package example

V
virtual buffers: Virtual Buffers

Jump to:   A   C   E   F   G   H   L   M   N   P   R   S   U   V