consult.el - Consulting completing-read
***************************************

— The Detailed Node Listing —

Available commands

Special features

Configuration

Indices

1 Introduction
**************

Consult provides various handy commands based on the Emacs completion
function completing-read
(https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html),
which allows to quickly select an item from a list of candidates with
completion.  Consult offers in particular a more advanced buffer
switching command ‘consult-buffer’ to switch to buffers and recently
opened files.  Various search commands are provided, like an
asynchronous ‘consult-grep’, and ‘consult-line’, which resembles Swiper
(https://github.com/abo-abo/swiper#swiper) or Helm-Swoop
(https://github.com/emacsorphanage/helm-swoop).  Some of the offered
commands are greatly enhanced versions of existing Emacs commands.  For
example the command ‘consult-imenu’ presents a flat list of the Imenu
with live preview and narrowing support.
Please take a look at the full list of commands.

   All Consult commands are compatible with completion systems based on
the standard Emacs ‘completing-read’ API, notably the default completion
system, Icomplete
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html),
Selectrum (https://github.com/raxod502/selectrum) and Embark
(https://github.com/oantolin/embark/), with which Consult works out of
the box.  If Icomplete is used, it is recommended to install
Icomplete-vertical (https://github.com/oantolin/icomplete-vertical) to
enjoy the enhanced visuals.  The completion system specifics in this
package are kept to a minimum.  The ability of the Consult commands to
work well with arbitrary completion systems is one of main advantages of
the package.  Consult fits well into existing setups and it helps you to
create a full completion environment out of small and independent
components.  Note that, if you use Ivy
(https://github.com/abo-abo/swiper#ivy) or Helm
(https://github.com/emacs-helm/helm), you probably don’t need Consult,
since both packages come with their own set of commands.

   There are the Marginalia (https://github.com/minad/marginalia/) and
Embark (https://github.com/oantolin/embark/) packages, which can be
combined with Consult.  Marginalia enriches the completion display with
annotations, for example documentation strings or file information.  The
versatile Embark packages provides local actions, comparable to a
context menu, which can be executed while selecting a candidate in the
minibuffer or in other contexts.  For example, when selecting from a
list of files, it offers an action to delete the file.  Additionally
Embark can also be used as a completion system by itself through its
live-updating completion buffer.  The Embark integration is
described later in greater detail.

2 Available commands
********************

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

   *TIP:* If you have Marginalia (https://github.com/minad/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.

2.1 Virtual Buffers
===================

   • ‘consult-buffer’ (‘-other-window’, ‘-other-frame’): Enhanced
     version of ‘switch-to-buffer’ with support for virtual buffers.
     Supports live preview of buffers and narrowing to the virtual
     buffer types.  You can type ‘f SPC’ in order to narrow to recent
     files.  Ephemeral buffers can be shown by pressing ‘SPC’ - 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 as shown in the example configuration).
        • Arbitrary other sources can be
          configured via ‘consult-buffer-sources’.
     By default only buffers are preview in order to ensure that
     ‘consult-buffer’ is fast, but it is possible to configure
     file and bookmark preview.
   • ‘consult-bookmark’: Select or create bookmark.  You might use the
     powerful ‘consult-buffer’ as an alternative, which can include a
     bookmark virtual buffer source.  But note that ‘consult-bookmark’
     supports preview of bookmarks and narrowing.
   • ‘consult-recent-file’: Select from recent files with preview.  You
     might prefer the powerful ‘consult-buffer’ instead, which can
     include recent files as a virtual buffer source.

2.2 Editing
===========

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

2.3 Register
============

   • ‘consult-register’: Select from list of registers.  The command
     supports narrowing to register types and preview of marker
     positions.  This command is useful to search the register contents.
     For quick access it is recommended to use ‘consult-register-load’
     or ‘consult-register-store’ or the built-in Emacs register
     commands.
   • ‘consult-register-format’: Supplementary register formatting
     function which can be used as ‘register-preview-function’ for an
     enhanced register formatting.  See the example configuration.
   • ‘consult-register-window’: Supplementary function which can be used
     as replacement for ‘register-preview’ for a better register window.
     See the example configuration.
   • ‘consult-register-load’: Utility command to quickly load a
     register.  The command either jumps to the register value or
     inserts it.
   • ‘consult-register-store’: Improved UI to store registers depending
     on the current context with an action menu.  With an active region,
     store/append/prepend the contents, optionally deleting the region
     when a prefix argument is given.  With a numeric prefix argument,
     store/add the number.  Otherwise store point, frameset, window or
     kmacro.  Usage examples:
        • ‘M-' x’: If no region is active, store point in register ‘x’.
          If a region is active, store the region in register ‘x’.
        • ‘M-' M-w x’: Store window configuration in register ‘x’.
        • ‘C-u 100 M-' x’: Store number in register ‘x’.

2.4 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
     (https://github.com/vspinu/imenu-anywhere).

2.5 Search
==========

   • ‘consult-line’: Enter search string and select from matching lines.
     Supports live preview and recursive editing.  The symbol at point
     and the recent Isearch string are added to the "future history" and
     can be accessed by pressing ‘M-n’.  When ‘consult-line’ is bound to
     the ‘isearch-mode-map’ and is invoked during a running Isearch, it
     will use the current Isearch string.
   • ‘consult-isearch’: During an Isearch session, this command picks a
     search string from history and continues the search with the newly
     selected string.  Outside of Isearch, the command allows to pick a
     string from the history and starts a new Isearch.  This command can
     be used as a drop-in replacement for ‘isearch-edit-string’.
   • ‘consult-multi-occur’: Replacement for ‘multi-occur’ which uses
     ‘completing-read-multiple’.
   • ‘consult-keep-lines’: Replacement for ‘keep/flush-lines’ which uses
     the current completion style for filtering the buffer.  The
     function updates the buffer while typing.  In particular, this
     function can be used to further narrow an exported Embark collect
     buffer with the same completion filtering as during
     ‘completing-read’.  If the input begins with the negation operator,
     i.e., ‘! SPC’, the filter matches the complement.  If a region is
     active, the filtering is restricted to that region.
   • ‘consult-focus-lines’: Temporarily hide lines by filtering them
     using the current completion style.  Call with ‘C-u’ prefix
     argument in order to show the hidden lines again.  If the input
     begins with the negation operator, i.e., ‘! SPC’, the filter
     matches the complement.  In contrast to ‘consult-keep-lines’ this
     function does not edit the buffer.  If a region is active, the
     focusing is restricted to that region.

2.6 Grep and Find
=================

   • ‘consult-grep’, ‘consult-ripgrep’, ‘consult-git-grep’: Search for
     regular expression in files.  Grep is invoked asynchronously, while
     you enter the search term.  You are required to enter at least
     ‘consult-async-min-input’ characters in order for the search to get
     started.  The input string is split into two parts, if the first
     character is a punctuation character, like ‘#’.  For example
     ‘#grep-regexp#filter-string’, is split at the second ‘#’.  The
     string ‘grep-regexp’ is passed to Grep, the ‘filter-string’ is
     passed to the _fast_ Emacs filtering to further narrow down the
     list of matches.  This is particularily useful if you are using an
     advanced completion style like orderless.  ‘consult-grep’ supports
     preview.  If the ‘consult-project-root-function’ is
     configured and returns non-nil,
     ‘consult-grep’ searches the current project directory.  Otherwise
     the ‘default-directory’ is searched.  If ‘consult-grep’ is invoked
     with prefix argument ‘C-u M-s g’, you can specify the directory
     manually.
   • ‘consult-find’, ‘consult-locate’: Find file by matching the path
     against a regexp.  Like ‘consult-grep’ either the project root or
     the current directory is used as root directory for the search.
     The input string is treated similarly to ‘consult-grep’, where the
     first part is passed to find, and the second part is used for Emacs
     filtering.  Note that the standard ‘find’ command uses wildcards in
     contrast to the popular ‘fd’, which uses regular expressions.  In
     case you want to use ‘fd’, you can either change the
     ‘consult-find-command’ configuration variable or define a small
     command as described in the Consult wiki
     (https://github.com/minad/consult/wiki).

2.7 Compilation errors
======================

   • ‘consult-compile-error’: Jump to a compilation error.  Supports
     live preview narrowing and and recursive editing.
   • ‘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’.

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

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

2.10 Miscellaneous
==================

   • ‘consult-apropos’: Replacement for ‘apropos’ with completion.
   • ‘consult-man’: Find Unix man page, via Unix ‘apropos’ or ‘man -k’.
     The selected man page is opened using the Emacs ‘man’ command.
   • ‘consult-file-externally’: Select a file and open it externally,
     e.g. using ‘xdg-open’ on Linux.
   • ‘consult-completion-in-region’: Function which can be used as
     ‘completion-in-region-function’.  This way, the minibuffer
     completion UI will be used for ‘completion-at-point’.  This
     function is particularily useful in combination with
     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.

3 Special features
******************

Consult enhances ‘completing-read’ with live previews of candidates,
additional narrowing capabilities to candidate subsets and
asynchronously generated candidate lists.  This functionality is
provided by the internal ‘consult--read’ function, which is used by most
Consult commands.  The ‘consult--read’ function is a thin wrapper around
‘completing-read’.  In order to support multiple candidate sources there
exists the high-level function ‘consult--multi’.  The architecture of
Consult allows it to work with different completion systems in the
backend, while still offering advanced features.

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

   Previews are enabled by default but can be disabled via the
‘consult-preview-key’ variable.  Furthermore it is possible to specify
keybindings which trigger the preview manually as shown in the
example configuration.  The default setting of
‘consult-preview-key’ is ‘any’ which means that the preview will be
triggered on any keypress when the selected candidate changes.  Each
command can be configured individually with its own ‘:preview-key’, such
that preview can be manual for some commands, for some commands
automatic and for some commands completely disabled.

3.2 Narrowing to subsets
========================

Consult has special support to narrow to candidate subsets.  This
functionality is useful if the list of candidates consists of candidates
of multiple types or candidates from multiple sources,
like the ‘consult-buffer’ command, which shows both buffers and
recently opened files.

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

   If which-key (https://github.com/justbur/emacs-which-key) is
installed, the possible narrowing keys are shown in the which-key window
after pressing the prefix key ‘consult-narrow-key’.  Furthermore there
is the ‘consult-narrow-help’ command which can be bound to a key in the
‘consult-narrow-map’ if this is desired, as shown in the example configuration.

3.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 grep
regular expression.  The grep process is executed in the background.
When modifying the grep regular expression, the background process is
terminated and a new process is started with the modified regular
expression.

   The matches, which have been found, can then be narrowed using the
installed Emacs completion-style.  This can be powerful if you are using
for example the ‘orderless’ completion style.

   This two-level filtering is possible by splitting the input string.
Part of the input string is treated as input to grep and part of the
input is used for filtering.  The input string is split at a punctuation
character, using a similar syntax as Perl regular expressions.

   Examples:

   • ‘#defun’: Search for "defun" using grep.
   • ‘#defun#consult’: Search for "defun" using grep, filter with the
     word "consult".
   • ‘/defun/consult’: It is also possible to use other punctuation
     characters.
   • ‘#to#’: Force searching for "to" using grep, since the grep pattern
     must be longer than ‘consult-async-min-input’ characters by
     default.
   • ‘#defun -- --invert-match#’: Pass argument ‘--invert-match’ to
     grep.

   For asynchronous processes like ‘find’ and ‘grep’, 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.

   There is an ephemeral error log buffer ‘_*consult-async-log*’ (note
the leading space), you can access the buffer using ‘consult-buffer’ and
‘switch-to-buffer’ by first pressing ‘SPC’ and then selecting the
buffer.

3.4 Multiple sources
====================

Consult allows combining multiple synchronous candidate sources.  This
feature is used by the ‘consult-buffer’ command to present buffer-like
candidates in a single menu for quick access.  By default
‘consult-buffer’ includes buffers, bookmarks, recent files and
project-specific buffers and files.  It is possible to configure the
list of sources via the ‘consult-buffer-sources’ variable.  Arbitrary
custom sources can be defined.

   As an example, the bookmark source is defined as follows:

     (defvar consult--source-bookmark
       `(:name     "Bookmark"
         :narrow   ?m
         :category bookmark
         :face     consult-bookmark
         :history  bookmark-history
         :items    ,#'bookmark-all-names
         :action   ,#'consult--bookmark-action))

   Required source fields:
   • ‘:category’ Completion category.
   • ‘:items’ List of strings to select from or function returning list
     of strings.

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

   The ‘:state’ and ‘:action’ fields of the sources deserve a longer
explanation.  The ‘:action’ function takes a single argument and is only
called after selection with the selected candidate, if the selection has
not been aborted.  This functionality is provided for convenience and
easy definition of sources.  The ‘:state’ field is more complicated and
general.  The ‘:state’ function is a constructor function without
arguments, which can perform some setup necessary for the preview.  It
must return a closure with two arguments: The first argument is the
candidate string, the second argument is the restore flag.  The state
function is called during preview, if a preview key has been pressed,
with the selected candidate or nil and the restore argument being nil.
Furthermore the state function is always called after selection with the
selected candidate or nil.  The state function is called with nil for
the candidate if for example the selection process has been aborted or
if the original preview state should be restored during preview.  The
restore flag is t for the final call.  The final call happens even if
preview is disabled.  For this reason you can also use the final call to
the state function in a similar way as ‘:action’.  You probably only
want to specify both ‘:state’ and ‘:action’ if ‘:state’ is purely
responsible for preview and ‘:action’ is then responsible for the real
action after selection.

   In order to avoid slowness, ‘consult-buffer’ only preview buffers by
default.  Loading recent files, bookmarks or views can result in
expensive operations.  However it is possible to configure the bookmark
and file sources to also perform preview.

     (nconc consult--source-bookmark (list :state #'consult--bookmark-preview))
     (nconc consult--source-file (list :state #'consult--file-preview))
     (nconc consult--source-project-file (list :state #'consult--file-preview))

   Sources can be added directly to the ‘consult-buffer-source’ list for
convenience.  For example views can be added to the list of virtual
buffers from a library like <https://github.com/minad/bookmark-view/>.

     ;; Configure new bookmark-view source
     (add-to-list 'consult-buffer-sources
                   (list :name     "View"
                         :narrow   ?v
                         :category 'bookmark
                         :face     'font-lock-keyword-face
                         :history  'bookmark-view-history
                         :action   #'consult--bookmark-jump
                         :items    #'bookmark-view-names)
                   'append)

     ;; Modify bookmark source, such that views are hidden
     (setq consult--source-bookmark
           (plist-put
            consult--source-bookmark :items
            (lambda ()
              (bookmark-maybe-load-default-file)
              (mapcar #'car
                      (seq-remove (lambda (x)
                                    (eq #'bookmark-view-handler
                                        (alist-get 'handler (cdr x))))
                                  bookmark-alist)))))

   Other useful sources allow the creation of terminal and eshell
buffers if they do not exist yet.

     (defun mode-buffer-exists-p (mode)
       (seq-some (lambda (buf)
                   (provided-mode-derived-p
                    (buffer-local-value 'major-mode buf)
                    mode))
                 (buffer-list)))

     (defvar eshell-source
       `(:category 'consult-new
         :face     'font-lock-constant-face
         :action   ,(lambda (_) (eshell))
         :items
         ,(lambda ()
            (unless (mode-buffer-exists-p 'eshell-mode)
              '("*eshell* (new)")))))

     (defvar term-source
       `(:category 'consult-new
         :face     'font-lock-constant-face
         :action
         ,(lambda (_)
            (ansi-term (or (getenv "SHELL") "/bin/sh")))
         :items
         ,(lambda ()
            (unless (mode-buffer-exists-p 'term-mode)
              '("*ansi-term* (new)")))))

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

   For more details, see the documentation of ‘consult-buffer’ and of
the internal ‘consult--multi’ API.  The ‘consult--multi’ function can be
used to create new multi-source commands, but is part of the internal
API as of now, since some details may still change.

3.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
(https://github.com/oantolin/embark) for an extensive description of its
capabilities.

   Actions are commands which can operate on the currently selected
candidate (or target in Embark terminology).  When completing files, for
example the ‘delete-file’ command is offered.  Embark also allows to to
execute arbitrary commands on the currently selected candidate via
‘M-x’.

   Furthermore Embark provides the ‘embark-collect-snapshot’ command,
which collects candidates and presents them in an Embark collect buffer,
where further actions can be applied to them.  A related feature is the
‘embark-export’ command, which allows to export candidate lists to a
buffer of a special type.  For example in the case of file completion, a
Dired buffer is opened.

   In the context of Consult, particularily exciting is the possibility
to export the matching lines from ‘consult-line’, ‘consult-outline’,
‘consult-mark’ and ‘consult-global-mark’.  The matching lines are
exported to an Occur buffer where they can be edited via the
‘occur-edit-mode’ (press key ‘e’).  Similarily, Embark supports
exporting the matches found by ‘consult-grep’, ‘consult-ripgrep’ and
‘consult-git-grep’ to a Grep buffer, where the matches across files can
be edited, if the wgrep (https://github.com/mhayashi1120/Emacs-wgrep)
package is installed.

4 Configuration
***************

Consult can be installed from MELPA (https://melpa.org/) via the Emacs
built-in package manager.  Alternatively it can be directly installed
from the development repository via other non-standard package managers.

   Note that there are two packages as of now: ‘consult’ and
‘consult-flycheck’.  ‘consult-flycheck’ is a separate package such that
the core ‘consult’ package only depends on Emacs core components.  The
‘consult’ package will work out of the box with the default completion,
Icomplete and Selectrum.

4.1 Use-package example
=======================

It is recommended to manage package configurations with the
‘use-package’ macro.  The Consult package only provides commands and
does not add any keybindings or modes.  Therefore the package is
non-intrusive but requires a little setup effort.  In order to use the
Consult commands, it is advised to add keybindings for commands which
are accessed often.  Rarely used commands can be invoked via ‘M-x’.
Feel free to only bind the commands you consider useful to your
workflow.

   *NOTE:* There is the Consult wiki
(https://github.com/minad/consult/wiki), where additional configuration
examples can be contributed.

     ;; Example configuration for Consult
     (use-package consult
       ;; Replace bindings. Lazily loaded due by `use-package'.
       :bind (;; C-c bindings (mode-specific-map)
              ("C-c h" . consult-history)
              ("C-c m" . consult-mode-command)
              ("C-c b" . consult-bookmark)
              ("C-c k" . consult-kmacro)
              ;; C-x bindings (ctl-x-map)
              ("C-x M-:" . consult-complex-command)     ;; orig. repeat-complet-command
              ("C-x b" . consult-buffer)                ;; orig. switch-to-buffer
              ("C-x 4 b" . consult-buffer-other-window) ;; orig. switch-to-buffer-other-window
              ("C-x 5 b" . consult-buffer-other-frame)  ;; orig. switch-to-buffer-other-frame
              ;; Custom M-# bindings for fast register access
              ("M-#" . consult-register-load)
              ("M-'" . consult-register-store)          ;; orig. abbrev-prefix-mark (unrelated)
              ("C-M-#" . consult-register)
              ;; Other custom bindings
              ("M-y" . consult-yank-pop)                ;; orig. yank-pop
              ("<help> a" . consult-apropos)            ;; orig. apropos-command
              ;; M-g bindings (goto-map)
              ("M-g g" . consult-goto-line)             ;; orig. goto-line
              ("M-g M-g" . consult-goto-line)           ;; orig. goto-line
              ("M-g o" . consult-outline)
              ("M-g m" . consult-mark)
              ("M-g k" . consult-global-mark)
              ("M-g i" . consult-imenu)
              ("M-g I" . consult-project-imenu)
              ;; M-s bindings (search-map)
              ("M-s f" . consult-find)
              ("M-s L" . consult-locate)
              ("M-s g" . consult-grep)
              ("M-s G" . consult-git-grep)
              ("M-s r" . consult-ripgrep)
              ("M-s l" . consult-line)
              ("M-s m" . consult-multi-occur)
              ("M-s k" . consult-keep-lines)
              ("M-s u" . consult-focus-lines)
              ;; Isearch integration
              ("M-s e" . consult-isearch)
              :map isearch-mode-map
              ("M-e" . consult-isearch)                 ;; orig. isearch-edit-string
              ("M-s e" . consult-isearch)               ;; orig. isearch-edit-string
              ("M-s l" . consult-line))                 ;; required by consult-line to detect isearch

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

       ;; Optionally configure the register formatting. This improves the register
       ;; preview for `consult-register', `consult-register-load',
       ;; `consult-register-store' and the Emacs built-ins.
       (setq register-preview-delay 0
             register-preview-function #'consult-register-format)

       ;; Optionally tweak the register preview window.
       ;; This adds zebra stripes, sorting and hides the mode line of the window.
       (advice-add #'register-preview :override #'consult-register-window)

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

       ;; Optionally configure preview. Note that the preview-key can also be
       ;; configured on a per-command basis via `consult-config'. The default value
       ;; is 'any, such that any key triggers the preview.
       ;; (setq consult-preview-key 'any)
       ;; (setq consult-preview-key (kbd "M-p"))
       ;; (setq consult-preview-key (list (kbd "<S-down>") (kbd "<S-up>")))

       ;; Optionally configure the narrowing key.
       ;; Both < and C-+ work reasonably well.
       (setq consult-narrow-key "<") ;; (kbd "C-+")

       ;; Optionally make narrowing help available in the minibuffer.
       ;; Probably not needed if you are using which-key.
       ;; (define-key consult-narrow-map (vconcat consult-narrow-key "?") #'consult-narrow-help)

       ;; Optionally configure a function which returns the project root directory.
       ;; There are multiple reasonable alternatives to chose from:
       ;; * projectile-project-root
       ;; * vc-root-dir
       ;; * project-roots
       ;; * locate-dominating-file
       (autoload 'projectile-project-root "projectile")
       (setq consult-project-root-function #'projectile-project-root)
       ;; (setq consult-project-root-function
       ;;       (lambda ()
       ;;         (when-let (project (project-current))
       ;;           (car (project-roots project)))))
       ;; (setq consult-project-root-function #'vc-root-dir)
       ;; (setq consult-project-root-function
       ;;       (lambda () (locate-dominating-file "." ".git")))
     )

     ;; Compilation mode integration
     (use-package compile
       :bind (:map compilation-minor-mode-map
              ("e" . consult-compile-error)
              :map compilation-mode-map
              ("e" . consult-compile-error)))

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

4.2 Custom variables
====================

*TIP:* If you have Marginalia (https://github.com/minad/marginalia)
installed, type ‘M-x customize-variable RET ^consult’ to see all
Consult-specific customizable variables with their current values and
abbreviated description.  Alternatively, type ‘C-h a ^consult’ to get an
overview of all Consult variables and functions with their descriptions.

Variable                        Default            Description
-----------------------------------------------------------------------------------------------------------
consult-after-jump-hook         ’(recenter)        Functions to call after jumping to a location
consult-async-default-split     "#"                Separator character used for splitting #async#filter
consult-async-input-debounce    0.25               Input debounce for asynchronous commands
consult-async-input-throttle    0.5                Input throttle for asynchronous commands
consult-async-min-input         3                  Minimum numbers of letters needed for async process
consult-async-refresh-delay     0.25               Refresh delay for asynchronous commands
consult-bookmark-narrow         ...                Narrowing configuration for ‘consult-bookmark’
consult-buffer-filter           ...                Filter for ‘consult-buffer’
consult-buffer-sources          ...                List of virtual buffer sources
consult-config                  nil                Invididual command option configuration
consult-find-command            "find ..."         Command line arguments for find
consult-fontify-max-size        1048576            Buffers larger than this limit are not fontified
consult-fontify-preserve        t                  Preserve fontification for line-based commands.
consult-git-grep-command        ’(...)             Command line arguments for git-grep
consult-goto-line-numbers       t                  Show line numbers for ‘consult-goto-line’
consult-grep-max-colums         250                Maximal number of columns of the matching lines
consult-grep-command            "grep ..."         Command line arguments for grep
consult-imenu-config            ...                Mode-specific configuration for ‘consult-imenu’
consult-line-numbers-widen      t                  Show absolute line numbers when narrowing is active.
consult-line-point-placement    ’match-beginning   Placement of the point used by ‘consult-line’
consult-locate-command          "locate ..."       Command line arguments for locate
consult-mode-command-filter     ...                Filter for ‘consult-mode-command’
consult-mode-histories          ...                Mode-specific history variables
consult-narrow-key              nil                Narrowing prefix key during completion
consult-preview-key             ’any               Keys which triggers preview
consult-preview-max-count       10                 Maximum number of files to keep open during preview
consult-preview-max-size        10485760           Files larger than this size are not previewed
consult-preview-raw-size        102400             Files larger than this size are previewed in raw form
consult-project-root-function   nil                Function which returns current project root
consult-register-narrow         ...                Narrowing configuration for ‘consult-register’
consult-ripgrep-command         "rg ..."           Command line arguments for ripgrep
consult-themes                  nil                List of themes to be presented for selection
consult-widen-key               nil                Widening key during completion

4.3 Fine-tuning of individual commands
======================================

*NOTE:* Consult allows fine-grained customization of individual
commands.  This configuration feature is made available for experienced
users with special requirements.

   Commands allow flexible, individual customization by setting the
‘consult-config’ list.  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 at
any time.

   Useful options are:
   • ‘:prompt’ set the prompt string
   • ‘:preview-key’ set the preview key, default is
     ‘consult-preview-key’
   • ‘:initial’ set the initial input
   • ‘:default’ set the default value
   • ‘:history’ set the history variable symbol
   • ‘:add-history’ add items to the future history, for example symbol
     at point
   • ‘:sort’ enable or disable sorting

     ;; Set preview for `consult-buffer' to key `M-p'
     ;; and disable preview for `consult-theme' completely.
     ;; For `consult-line' specify multiple keybindings.
     ;; Note that you should bind the <S-up> and <S-down> in the
     ;; `minibuffer-local-completion-map' or `selectrum-minibuffer-map'
     ;; to the commands which select the previous or next candidate.
     (setq consult-config `((consult-theme :preview-key nil)
                            (consult-buffer :preview-key ,(kbd "M-p"))
                            (consult-line :preview-key (list ,(kbd "<S-down>") ,(kbd "<S-up>")))))

   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. Create your own buffer multi sources for
     ‘consult-buffer’.
  3. Modify ‘consult-config’ in order to change the ‘consult--read’
     settings.
  4. Create advices to modify some internal behavior.
  5. Write or propose a patch.

5 Recommended packages
**********************

It is recommended to install the following package combination:

   • consult: This package
   • consult-flycheck: Provides the consult-flycheck command
   • selectrum (https://github.com/raxod502/selectrum) or
     icomplete-vertical
     (https://github.com/oantolin/icomplete-vertical): Vertical
     completion systems
   • marginalia (https://github.com/minad/marginalia): Annotations for
     the completion candidates
   • embark and embark-consult (https://github.com/oantolin/embark):
     Action commands, which can act on the completion candidates
   • orderless (https://github.com/oantolin/orderless): Completion
     style, Flexible candidate filtering
   • prescient (https://github.com/raxod502/prescient.el):
     Frecency-based candidate sorting, also offers filtering

   There exist more packages related to Consult which provide wider
integration with the Emacs ecosystem.  You may want to install some of
these packages too depending on your personal preferences.

   • which-key (https://github.com/justbur/emacs-which-key): Helpful
     mode showing keybindings, also shows the Consult narrowing keys
   • wgrep (https://github.com/mhayashi1120/Emacs-wgrep): Editing of
     grep buffers, can be used together with ‘consult-grep’ via Embark
   • bookmark-view (https://github.com/minad/bookmark-view): Store
     window configuration as bookmarks, integrates with ‘consult-buffer’
   • flyspell-correct (https://github.com/d12frosted/flyspell-correct):
     Apply spelling corrections by selecting via ‘completing-read’
   • consult-notmuch (https://codeberg.org/jao/consult-notmuch): Access
     the Notmuch (https://notmuchmail.org/) email system using Consult
   • consult-spotify (https://codeberg.org/jao/espotify): Access the
     Spotify API and control your local music player.

   Note that all packages are independent and can potentially be
exchanged with alternative components, since there exist no hard
dependencies.  Furthermore it is possible to get started with only
default completion and Consult and add more components later to the mix,
e.g., using Selectrum for enhanced minibuffer completion or Embark for
actions.

6 Bug reports
*************

If you find a bug or suspect that there is a problem with Consult,
please check first that you have *updated all the relevant packages* to
the newest version.  This includes Selectrum, Icomplete-vertical,
Embark, Orderless and Prescient in case you are using any of those
packages.

   Please provide the necessary important information with your bug
report, e.g., the Emacs version, your operating system and the package
manager you are using.  Try to reproduce the issue by starting a
barebone Emacs instance with ‘emacs -Q’ on the command line.  Then
execute the following code in the scratch buffer.  This way we can
exclude side effects due to configuration settings.

     ;; Minimal setup using Selectrum
     (package-initialize)
     (require 'consult)
     (require 'selectrum)
     (selectrum-mode)
     (setq completion-styles '(substring))

     ;; Minimal setup using the default completion system
     (package-initialize)
     (require 'consult)
     (setq completion-styles '(substring))

7 Contributions
***************

Consult is intended to be a community effort, please participate in the
discussions.  Contributions are welcome.  If you have a proposal, take a
look first at the Consult issue tracker
(https://github.com/consult/issues) and the Consult wishlist
(https://github.com/minad/consult/issues/6).  For small configuration or
command snippets you may want to share, there is the Consult wiki
(https://github.com/minad/consult/wiki).

8 Acknowledgements
******************

You probably guessed from the name that this package took inspiration
from Counsel (https://github.com/abo-abo/swiper#counsel) by Oleh Krehel.
Some of the Consult commands originated in the Selectrum wiki
(https://github.com/raxod502/selectrum/wiki/Useful-Commands).  The
commands have been rewritten and greatly enhanced in comparison to the
wiki versions.  In particular all Selectrum-specific code has been
removed, such that the commands are compatible with the
‘completing-read’ API.

   Code contributions:
   • Omar Antolín Camarena (https://github.com/oantolin/)
   • Sergey Kostyaev (https://github.com/s-kostyaev/)
   • okamsn (https://github.com/okamsn/)
   • Clemens Radermacher (https://github.com/clemera/)
   • Tom Fitzhenry (https://github.com/tomfitzhenry/)
   • jakanakaevangeli (https://github.com/jakanakaevangeli)
   • inigoserna (https://github.com/inigoserna/)
   • Adam Spiers (https://github.com/aspiers/)
   • Omar Polo (https://github.com/omar-polo)
   • Augusto Stoffel (https://github.com/astoff)
   • Jose A Ortega Ruiz (https://codeberg.org/jao/)

   Advice and useful discussions:
   • Clemens Radermacher (https://github.com/clemera/)
   • Omar Antolín Camarena (https://github.com/oantolin/)
   • Protesilaos Stavrou (https://gitlab.com/protesilaos/)
   • Steve Purcell (https://github.com/purcell/)
   • Adam Porter (https://github.com/alphapapa/)
   • Manuel Uberti (https://github.com/manuel-uberti/)
   • Tom Fitzhenry (https://github.com/tomfitzhenry/)
   • Howard Melman (https://github.com/hmelman/)

9 Indices
*********