GNU ELPA - consult

• consult-buffer: 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. Press SPC to show ephemeral buffers. Supported narrowing keys:
  • b Buffers
  • SPC Hidden buffers
  • * Modified buffers
  • f Files (Requires recentf-mode)
  • r File registers
  • m Bookmarks
  • p Project
  • B Project buffers
  • F Project files
  • R Project roots
  • Custom other sources configured in consult-buffer-sources.
• consult-buffer-other-window, consult-buffer-other-frame, consult-buffer-other-tab: Variants of consult-buffer.
• consult-project-buffer: Variant of consult-buffer restricted to buffers and recent files of the current project. You can add custom sources to consult-project-buffer-sources. The command may prompt you for a project if you invoke it from outside a project.
• consult-bookmark: Select or create bookmark. To select bookmarks you might use the consult-buffer as an alternative, which can include a bookmark virtual buffer source. 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. The recentf-mode enables tracking of recent files.

• consult-yank-from-kill-ring: Enhanced version of yank 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 consults 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.

• 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-load, consult-register-store or the built-in Emacs register commands.
• consult-register-format: Set register-preview-function to this function for an enhanced register formatting. Used automatically by consult-register-window.
• consult-register-window: Replace register-preview with 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 x.
  • M-' M-w x: Store window configuration in register x.
  • C-u 100 M-' x: Store number in register x.

• consult-goto-line: Jump to line number enhanced with live preview. This is a drop-in replacement for goto-line. Enter a line number to jump to the first column of the given line. Alternatively enter line:column in order to jump to a specific column.
• 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 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-line-multi: Search dynamically across multiple buffers. By default search across project buffers. If invoked with a prefix argument search across all buffers. The candidates are computed on demand based on the input. The command behaves like consult-grep, but operates on buffers instead of files.
• 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 consult-keep-lines can 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-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 region restricts the filtering.

• consult-grep, consult-ripgrep, 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-input characters, the search gets started. Consult splits the input string into two parts, if the first character is a punctuation character, like #. For example #regexps#filter-string, is split at the second #. The string regexps is passed to Grep. Note that Consult transforms Emacs regular expressions to expressions understand by the search program. Always use Emacs regular expressions at the prompt. 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-string is 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-grep supports preview. consult-grep searches the current project directory if a project is found. Otherwise the default-directory is searched. If consult-grep is invoked with prefix argument C-u M-s g, you can specify one or more comma-separated files and directories manually. If invoked with two prefix arguments C-u C-u M-s g, you can first select a project if you are not yet inside a project.
• consult-find, consult-fd, 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. Prefix arguments to consult-find work just like those for the consult grep commands.

• 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 e SPC, w SPC, n SPC to only show errors, warnings and notes respectively.
• consult-xref: Integration with xref. This function can be set as xref-show-xrefs-function and xref-show-definitions-function.

• consult-complex-command: Select a command from the command-history. This command is a completing-read version of repeat-complex-command and is also a replacement for the command-history command from chistory.el.
• consult-history: Insert a string from the current buffer history, for example the Eshell or Comint history. You can also invoke this command from the minibuffer. In that case consult-history uses the history stored in the minibuffer-history-variable. If you prefer completion-at-point, take a look at cape-history from the Cape package.
• consult-isearch-history: 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-isearch-history acts as a drop-in replacement for isearch-edit-string.

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

• consult-org-heading: Variant of consult-imenu or consult-outline for Org buffers. The headline and its ancestors headlines are separated by slashes. Supports narrowing by heading level, priority and TODO keyword, as well as live preview and recursive editing.
• consult-org-agenda: Jump to an Org agenda heading. Supports narrowing by heading level, priority and TODO keyword, as well as live preview and recursive editing.

• consult-man: Find Unix man page, via Unix apropos or man -k. consult-man opens the selected man page using the Emacs man command. Supports live preview of the theme while scrolling through the candidates.
• consult-info: Full text search through info pages. If the command is invoked from within an *info* buffer, it will search through the current manual. You may want to create your own consult-info-* commands which search through a predefined set of info pages. You can use the function consult-info-define to define commands consult-info-emacs, consult-info-completion, consult-info-org, and so on:

(consult-info-define "emacs" "efaq" "elisp" "cl" "compat" "eshell")
(consult-info-define 'completion
		     "vertico" "consult" "marginalia" "orderless"
		     "embark" "corfu" "cape" "tempel")
(consult-info-define "org")
(consult-info-define "gnus")
(consult-info-define "magit")

• 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 previews the candidate at point in the *Completions* buffer. This mode is relevant if you use Mct or the default *Completions* UI.

• consult-completion-in-region: In case you don't use Corfu as your in-buffer completion UI, this function can be set as completion-in-region-function. Then your minibuffer completion UI (e.g., Vertico or Icomplete) will be used for completion-at-point.

  (setq completion-in-region-function #'consult-completion-in-region)
  

  Instead of consult-completion-in-region, you may prefer to see the completions directly in the buffer as a small popup. In that case, I recommend the Corfu package. There is a technical limitation of consult-completion-in-region in combination with the Lsp modes. 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. In contrast, in-buffer Lsp completion for example via Corfu works properly since the completion takes place directly in the original buffer.

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:

• Automatic and immediate 'any
• Automatic and delayed (list :debounce 0.5 'any)
• Manual and immediate "M-."
• Manual and delayed (list :debounce 0.5 "M-.")
• Disabled nil

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-man
 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 hooks listed in consult-preview-allowed-hooks are executed. This variable applies to find-file-hook, change-major-mode-hook and mode hooks, e.g., prog-mode-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.

;; local modes added to prog-mode hooks
(add-to-list 'consult-preview-allowed-hooks 'hl-todo-mode)
(add-to-list 'consult-preview-allowed-hooks 'elide-head-mode)
;; enabled global modes
(add-to-list 'consult-preview-allowed-hooks 'global-org-modern-mode)
(add-to-list 'consult-preview-allowed-hooks 'global-hl-todo-mode)

Files larger than consult-preview-partial-size are previewed partially. 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))

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.

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:

• #defun: Search for "defun" using grep.
• #consult embark: Search for both "consult" and "embark" using grep in any order.
• #first.*second: Search for "first" followed by "second" using grep.
• #\(consult\|embark\): Search for "consult" or "embark" using grep. Note the usage of Emacs-style regular expressions.
• #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.

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:

• : 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 static and asynchronous 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. The consult-buffer-sources variable configures the list of sources. Arbitrary custom sources can be added to this list.

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

Either the :items or the :async source field is required:

• :items List of strings to select from or function returning list of strings. The strings can carry metadata in text properties, which is then available to the :annotate, :action and :state functions. The list can also consist of pairs, with the string in the car used for display and the cdr the actual candidate.
• :async Alternative to :items for asynchronous sources. See the docstring for details.

Optional source fields:

• :name Name of the source, used for narrowing, group titles and annotations.
• :narrow Narrowing character, (char . string) pair or list of pairs.
• :category Completion category.
• :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 Function called with the selected candidate.
• :new Function called with new candidate name, only if :require-match is nil.
• :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 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, the following source lists all Org buffers and lets you create new ones.

(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 ()
	  (consult--buffer-query :mode 'org-mode :as #'consult--buffer-pair))))

(add-to-list 'consult-buffer-sources 'org-source 'append)

One can create similar sources for other major modes. See the Consult wiki for many additional source examples. See also the documentation of consult-buffer and of the internal consult--multi API. The function consult--multi can be used to create new multi-source commands.

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.

• 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.
• consult-find -> embark-export to dired-mode buffer -> wdired-change-to-wdired-mode for editing.

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. While the configuration example is long, it consists essentially of key bindings only, such that the risk of interference with other Emacs functionality is minimized.

In order to use the Consult commands, it is recommended 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 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 t b" . consult-buffer-other-tab)    ;; orig. switch-to-buffer-other-tab
	 ("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)                  ;; Alternative: consult-fd
	 ("M-s c" . 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

  ;; Tweak the register preview for `consult-register-load',
  ;; `consult-register-store' and the built-in commands.  This improves the
  ;; register formatting, adds thin separator lines, register sorting and hides
  ;; the window mode line.
  (advice-add #'register-preview :override #'consult-register-window)
  (setq register-preview-delay 0.5)

  ;; 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-man
   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.
  ;; (keymap-set consult-narrow-map (concat consult-narrow-key " ?") #'consult-narrow-help)
)

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.

Multiple Consult search commands like consult-grep try to discover the current project and search in the project top level directory by default, if a project is found. Otherwise they fall back to the default-directory. By default, Consult uses the Emacs built-in project discovery support (project-current and project-root). It is possible to configure alternative methods via the customization variable consult-project-function.

;; 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. Disable project support
(setq consult-project-function nil)

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:

• :prompt set the prompt string
• :preview-key set the preview key, default is consult-preview-key
• :initial set the initial input
• :initial-narrow set the initial narrow key
• :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 to disable candidate grouping and titles.
• :inherit-input-method set 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 "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.

If you have a completion source that's both dynamic and expensive to generate, completing-read may not be the best choice. Instead, consult--read serves as a thin wrapper around completing-read that provides this functionality. For example, consider the following slow script that splits its input on space:

#!/usr/bin/env bash
# simulate work
sleep .1
# generate completion candidates
printf "%s\n" "$*" | tr " " "\n" | sort

Let's assume this script is callable as testibus hello world. To have Consult use it for completion, use consult--process-collection:

(consult--read
 (consult--process-collection
  (lambda (input) (list "testibus" (string-trim input))))
 :prompt "run testibus: ")

If the completion candidates are generated by Lisp instead, use consult--dynamic-collection:

(consult--read
 (consult--dynamic-collection
  (lambda (input)
    (sleep-for 0.1) ;; Simulate work
    (split-string input nil t)))
 :prompt "run testibus: ")

consult--dynamic-collection can take a function with a callback such that the completion UI can update for long running computations.

(consult--read
 (consult--dynamic-collection
  (lambda (input callback)
    (dotimes (i 3)
      (sleep-for 0.1) ;; Simulate work
      (funcall callback (mapcar (lambda (s) (format "%s%s" s i))
				(split-string input nil t))))))
 :prompt "run testibus: ")

The asynchronous completion collections consult--dynamic-collection and consult--process-collection can be used for consult--multi sources. Specify them as :async field of the source plist.

Implementing live preview requires the definition of a state or preview function as defined by consult--with-preview. The preview function receives the candidate and some action to perform (e.g., 'preview). In its simplest form supporting live preview, it looks something like this:

(defun testibus--preview (action cand)
  (pcase action
    ('preview
     (with-current-buffer-window " *testibus*" 'action nil
       (erase-buffer)
       (insert (format "input: %s\n" cand))))))

See the docstring of consult--with-preview for the lifecycle of the action argument. Once defined, we can use this preview function in consult--read:

(consult--read
 (consult--dynamic-collection
  (lambda (input callback)
    (dotimes (i 3)
      (sleep-for 0.1) ;; Simulate work
      (funcall callback (mapcar (lambda (s) (format "%s%s" s i))
				(split-string input nil t))))))
 :prompt "run testibus: "
 :state #'testibus--preview)