/consult

consult.el - Consulting completing-read

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

consult.el - Consulting completing-read

https://melpa.org/packages/consult-badge.svg

Introduction

This package provides various commands based on the Emacs completion function completing-read, in particular a more advanced buffer switching command consult-buffer which allows to select from buffers, recent files and more. Furthermore various search commands are provided, like consult-grep and consult-line, which resembles Swiper.

The commands are compatible with completion systems based on the standard Emacs completing-read API, notably the default completion system, Icomplete, Selectrum and Embark’s live-occur. If Icomplete is used, it is recommended to install Icomplete-vertical. The completion system specifics in this package are kept to a minimum.

There are the Marginalia and Embark packages, which can be combined with Consult. The marginalia-mode enriches the completion display with annotations. The annotations show for example documentation strings or file information. Embark provides local actions (like a context menu), which can be executed while selecting a candidate in the minibuffer. For example, when selecting a file, an action to delete the file is offered.

Note: If you use Ivy or Helm, you probably don’t need Consult, since both packages already bring their own rich set of additional commands.

Screenshots

consult-grep

https://github.com/minad/consult/blob/main/images/consult-grep.gif?raw=true

consult-mark

https://github.com/minad/consult/blob/main/images/consult-mark.png?raw=true

consult-line

https://github.com/minad/consult/blob/main/images/consult-line.png?raw=true

consult-outline

https://github.com/minad/consult/blob/main/images/consult-outline.png?raw=true

marginalia-mode

https://github.com/minad/marginalia/blob/main/marginalia-mode.png?raw=true

Available commands

Most provided commands follow the naming scheme consult-<thing>.

Tip: If you have Marginalia installed and heavy annotators enabled, 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 and recursive editing while previewing. The command supports narrowing. You can type f SPC in order to narrow to recent files. Ephemeral buffers can be shown by pressing SPC - it works the same way as switch-buffer. Supported narrowing keys:
    • b Buffers
    • f Files
    • m Bookmarks
    • p Project (only available if consult-project-root-function is configured)
    • v Views (only available if consult-view-*-function is configured)
  • consult-bookmark: Select or create bookmark. You might consider the powerful consult-buffer instead as an alternative, which includes bookmarks. However consult-bookmark supports preview of bookmarks and narrowing.
  • consult-recent-file (-other-window, -other-frame): Select a recent files. You might prefer the more powerful consult-buffer instead, which includes recent files.

Editing

  • consult-register: Select from list of registers.
  • consult-yank, consult-yank-pop: Enhanced version of yank and yank-pop which allows selecting from the kill-ring. Live preview is supported when selecting from the kill-ring.
  • consult-kmacro: Select macro from the macro ring and execute it.

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 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.
  • consult-multi-occur: Replacement for multi-occur which uses completing-read-multiple.
  • consult-grep, consult-ripgrep, consult-git-grep: Search for regular expression in current directory. 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 consult-project-root-function is configured and the function returns non-nil, consult-grep searches the current project directory. Otherwise the default-directory is searched. If consult-grep is invoked with prefix argument, you can specify the directory manually, i.e., C-u M-g r.
  • 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 find uses wildcards, e.g. enter *consult*, to find all files containing the string “consult”. In case you want to use another search utility like fd, you can write wrapper command my-fdfind (see below in the configuration example).

Compilation errors

  • consult-error: Jump to an error. Supports live preview and recursive editing. In contrast to consult-flycheck it shows the line and is more general since it is not tied to a specific backend.
  • consult-flycheck: Jump to flycheck error. Supports live preview and recursive editing. The command supports narrowing. Press e SPC, w SPC, i SPC to only show errors, warnings and infos respectively. This command requires to install the additional consult-flycheck.el package since the main consult.el package only depends on Emacs core components.
  • consult-flymake: Jump to Flymake diagnostic, like consult-flycheck.

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.

Minor and Major 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.

Miscellaneous

  • consult-apropos: Replacement for apropos with completion.
  • 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 Icomplete-vertical, since Icomplete does not provide its own completion-in-region-function. In contrast, Selectrum already comes with its own function.
  • consult-theme: Select a theme and disable all currently enabled themes. Supports live preview of the theme while scrolling through the candidates.

Special 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 option. Furthermore it is possible to define a keybinding to trigger the preview manually. Each command can be configured individually with its own :preview-key, such that for some commands preview is manual, for some automatic and for some completely disabled.

Narrowing to subsets

Consult has special support to narrow to candidate subsets. When you use the consult-buffer command, you can press b SPC and the list of candidates will be restricted such that only buffers are shown. If you press DEL afterwards, the full candidate list will be shown again. Furthermore a narrowing/widening key can be configured which can be pressed to achieve the same effect, see the configuration variables consult-narrow-key and consult-widen-key.

Asynchronous candidates and filtering

Consult has support for asynchronous generation of candidate lists. This feature is used for example by consult-grep, where the list of matches is generated dynamically while the user is typing a grep regular expression. Furthermore the found matches can then be narrowed using the installed Emacs completion-style, which can be very powerful if you are using for example the orderless completion style. This is possible since part of the input string is treated as input to grep and part of the input is used for filtering. 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.

Installation

NOTE: If you are using Selectrum, you MUST install the packages selectrum, consult and consult-selectrum!

It is recommended to manage package configurations with use-package. The Consult package only provides commands and does not add any keybindings. In order to use the enhanced commands, you must configure the keybindings yourself.

Note that there are three packages as of now: consult.el, consult-selectrum.el and consult-flycheck.el. Consult has been split such that the main package consult.el only depends on Emacs core components.

Example configuration

;; Example configuration for Consult
(use-package consult
  ;; Replace bindings. Lazily loaded due by `use-package'.
  :bind (("C-x M-:" . consult-complex-command)
         ("C-c h" . consult-history)
         ("C-c m" . consult-mode-command)
         ("C-x b" . consult-buffer)
         ("C-x 4 b" . consult-buffer-other-window)
         ("C-x 5 b" . consult-buffer-other-frame)
         ("C-x r x" . consult-register)
         ("C-x r b" . consult-bookmark)
         ("M-g g" . consult-goto-line)
         ("M-g M-g" . consult-goto-line)
         ("M-g o" . consult-outline)       ;; "M-s o" is a good alternative.
         ("M-g l" . consult-line)          ;; "M-s l" is a good alternative.
         ("M-g m" . consult-mark)          ;; I recommend to bind Consult navigation
         ("M-g k" . consult-global-mark)   ;; commands under the "M-g" prefix.
         ("M-g r" . consult-git-grep)      ;; or consult-grep, consult-ripgrep
         ("M-g f" . consult-find)          ;; or consult-locate, my-fdfind
         ("M-g i" . consult-project-imenu) ;; or consult-imenu
         ("M-g e" . consult-error)
         ("M-s m" . consult-multi-occur)
         ("M-y" . consult-yank-pop)
         ("<help> a" . consult-apropos))

  ;; The :init configuration is always executed (Not lazy!)
  :init

  ;; Custom command wrappers. It is generally encouraged to write your own
  ;; commands based on the Consult commands. Some commands have arguments which
  ;; allow tweaking. Furthermore global configuration variables can be set
  ;; locally in a let-binding.
  (defun my-fdfind (&optional dir)
    (interactive "P")
    (let ((consult-find-command '("fdfind" "--color=never" "--full-path")))
      (consult-find dir)))

  ;; Replace `multi-occur' with `consult-multi-occur', which is a drop-in replacement.
  (fset 'multi-occur #'consult-multi-occur)

  ;; Configure other variables and modes in the :config section, after lazily loading the package
  :config

  ;; Configure preview. Note that the preview-key can also be configured on a
  ;; per-command basis via `consult-config'.
  ;; (setq consult-preview-key 'any) ;; any key triggers preview, the default

  ;; Optionally configure narrowing key.
  ;; Both < and C-+ work reasonably well.
  (setq consult-narrow-key "<") ;; (kbd "C-+")
  ;; Optionally make narrowing help available in the minibuffer.
  ;; Probably not needed if you are using which-key.
  ;; (define-key consult-narrow-map (vconcat consult-narrow-key "?") #'consult-narrow-help)

  ;; Optional configure a view library to be used by `consult-buffer'.
  ;; The view library must provide two functions, one to open the view by name,
  ;; and one function which must return a list of views as strings.
  ;; Example: https://github.com/minad/bookmark-view/
  ;; (setq consult-view-open-function #'bookmark-jump
  ;;       consult-view-list-function #'bookmark-view-names)

  ;; Optionally configure a function which returns the project root directory
  (autoload 'projectile-project-root "projectile")
  (setq consult-project-root-function #'projectile-project-root))

;; Enable Consult-Selectrum integration.
;; This package should be installed if Selectrum is used.
(use-package consult-selectrum
  :after selectrum
  :demand t)

;; Optionally add the `consult-flycheck' command.
(use-package consult-flycheck
  :bind (:map flycheck-command-map
              ("!" . consult-flycheck)))

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

VariableDefaultDescription
consult-after-jump-hook‘(recenter)Functions to call after jumping to a location
consult-async-default-split”#”Separator character used for splitting #async#filter
consult-async-input-debounce0.25Input debounce for asynchronous commands
consult-async-input-throttle0.5Input throttle for asynchronous commands
consult-async-min-input3Minimum numbers of letters needed for async process
consult-async-refresh-delay0.25Refresh delay for asynchronous commands
consult-bookmark-narrow…Narrowing configuration for consult-bookmark
consult-buffer-filter…Filter for consult-buffer
consult-confignilInvididual command option configuration
consult-find-command’(…)Command line arguments for find
consult-fontify-limit1048576Buffers larger than this limit are not fontified
consult-git-grep-command’(…)Command line arguments for git-grep
consult-goto-line-numberstShow line numbers for consult-goto-line
consult-grep-command’(…)Command line arguments for grep
consult-imenu-narrow…Mode-specific narrowing keys for consult-imenu
consult-imenu-toplevel…Mode-specific toplevel names used by consult-imenu
consult-line-numbers-widentShow absolute line numbers when narrowing is active.
consult-line-point-placement‘match-beginningPlacement of the point used by consult-line
consult-locate-command’(…)Command line arguments for locate
consult-mode-command-filter…Filter for consult-mode-command
consult-mode-histories…Mode-specific history variables
consult-narrow-keynilNarrowing prefix key during completion
consult-preview-key‘anyKey which triggers preview
consult-preview-max-count10Maximum number of files to keep open during preview
consult-preview-max-size10485760Size limit for previewed files
consult-project-root-functionnilFunction which returns current project root
consult-ripgrep-command’(…)Command line arguments for ripgrep
consult-themesnilList of themes to be presented for selection
consult-view-list-functionnilFunction which returns a list of view names as strings
consult-view-open-functionnilFunction to open a view by name
consult-widen-keynilWidening key during completion

Configuration of individual commands

Note: This configuration feature is made available for experienced users, in case fine-grained control for each individual command is needed.

Commands allow flexible, individual customization by setting the consult-config list. You can override any option passed to the internal consult--read API, for example :preview-key, :initial, :default, :history or :sort. Note that since consult--read is part of the internal API, options could be removed, replaced or renamed at any time.

;; Set preview for `consult-buffer' to key `M-p'
;; and disable preview for `consult-theme' completely.
(setq consult-config `((consult-theme :preview-key nil)
                       (consult-buffer :preview-key ,(kbd "M-p"))))

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

  1. Create your own wrapper function which passes modified arguments to the Consult functions.
  2. Modify consult-config in order to change the consult--read settings.
  3. Create advices to modify some internal behavior.
  4. Write or propose a patch!

Related packages

NOTE: If you are using Selectrum, you MUST install the packages selectrum, consult and consult-selectrum!

It is recommended to install the following package combination:

  • consult: This package
  • consult-flycheck: Provides the consult-flycheck command
  • consult-selectrum: Provides integration with Selectrum
  • selectrum or icomplete-vertical: Vertical completion systems
  • marginalia: Annotations for the completion candidates
  • embark: Action commands, which can act on the completion candidates
  • orderless: Completion style, Flexible candidate filtering
  • prescient: Frecency-based candidate sorting, also offers filtering

Note that all packages are independent and can potentially be exchanged with alternative components, since there exist no hard dependencies. Furthermore it is possible to get started with only Selectrum and Consult and add more components later to the mix.

Acknowledgements

You probably guessed from the name that this package took inspiration from Counsel by Oleh Krehel. Some of the commands found in this package originated in the Selectrum wiki.

Code contributions:

Advice and useful discussions: