{"id":13443149,"url":"https://github.com/minad/consult","last_synced_at":"2025-05-14T15:07:20.012Z","repository":{"id":37243160,"uuid":"316068494","full_name":"minad/consult","owner":"minad","description":":mag: consult.el - Consulting completing-read","archived":false,"fork":false,"pushed_at":"2025-05-12T14:10:25.000Z","size":6794,"stargazers_count":1391,"open_issues_count":0,"forks_count":117,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-05-12T15:29:45.599Z","etag":null,"topics":["completion","emacs"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minad.png","metadata":{"files":{"readme":"README.org","changelog":"CHANGELOG.org","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"minad","liberapay":"minad","custom":"https://www.paypal.me/danielmendler"}},"created_at":"2020-11-25T22:36:24.000Z","updated_at":"2025-05-12T15:23:34.000Z","dependencies_parsed_at":"2023-10-20T20:53:22.734Z","dependency_job_id":"87811916-087b-46e7-96d0-6074fb0fe552","html_url":"https://github.com/minad/consult","commit_stats":{"total_commits":2188,"total_committers":32,"mean_commits":68.375,"dds":"0.029250457038391242","last_synced_commit":"fa249d5dd7212e5ae1fa51c086d8f1197d738ef4"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fconsult","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fconsult/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fconsult/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minad%2Fconsult/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minad","download_url":"https://codeload.github.com/minad/consult/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254169583,"owners_count":22026213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["completion","emacs"],"created_at":"2024-07-31T03:01:56.765Z","updated_at":"2025-05-14T15:07:19.996Z","avatar_url":"https://github.com/minad.png","language":"Emacs Lisp","readme":"#+title: consult.el - Consulting completing-read\n#+author: Daniel Mendler\n#+language: en\n#+export_file_name: consult.texi\n#+texinfo_dir_category: Emacs misc features\n#+texinfo_dir_title: Consult: (consult).\n#+texinfo_dir_desc: Useful commands built on completing-read.\n\n#+html: \u003ca href=\"https://www.gnu.org/software/emacs/\"\u003e\u003cimg alt=\"GNU Emacs\" src=\"https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://elpa.gnu.org/packages/consult.html\"\u003e\u003cimg alt=\"GNU ELPA\" src=\"https://elpa.gnu.org/packages/consult.svg\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://elpa.gnu.org/devel/consult.html\"\u003e\u003cimg alt=\"GNU-devel ELPA\" src=\"https://elpa.gnu.org/devel/consult.svg\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://melpa.org/#/consult\"\u003e\u003cimg alt=\"MELPA\" src=\"https://melpa.org/packages/consult-badge.svg\"/\u003e\u003c/a\u003e\n#+html: \u003ca href=\"https://stable.melpa.org/#/consult\"\u003e\u003cimg alt=\"MELPA Stable\" src=\"https://stable.melpa.org/packages/consult-badge.svg\"/\u003e\u003c/a\u003e\n\nConsult provides search and navigation commands based on the Emacs completion\nfunction [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html][completing-read]]. Completion allows you to quickly select an item from a\nlist of candidates. Consult offers asynchronous and interactive =consult-grep= and\n=consult-ripgrep= commands, and the line-based search command =consult-line=.\nFurthermore Consult provides an advanced buffer switching command =consult-buffer=\nto switch between buffers, recently opened files, bookmarks and buffer-like\ncandidates from other sources. Some of the Consult commands are enhanced\nversions of built-in Emacs commands. For example the command =consult-imenu=\npresents a flat list of the Imenu with [[#live-previews][live preview]], [[#narrowing-and-grouping][grouping and narrowing]].\nPlease take a look at the [[#available-commands][full list of commands]].\n\nConsult is fully compatible with completion systems centered around the standard\nEmacs =completing-read= API, notably the default completion system, [[https://github.com/minad/vertico][Vertico]], [[https://github.com/protesilaos/mct][Mct]],\nand [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html][Icomplete]].\n\nThis package keeps the completion system specifics to a minimum. The ability of\nthe Consult commands to work well with arbitrary completion systems is one of\nthe main advantages of the package. Consult fits well into existing setups and\nit helps you to create a full completion environment out of small and\nindependent components.\n\nYou can combine the complementary packages [[https://github.com/minad/marginalia/][Marginalia]], [[https://github.com/oantolin/embark/][Embark]] and [[https://github.com/oantolin/orderless][Orderless]] with\nConsult. Marginalia enriches the completion display with annotations, e.g.,\ndocumentation strings or file information. The versatile Embark package provides\nlocal actions, comparable to a context menu. These actions operate on the\nselected candidate in the minibuffer or at point in normal buffers. For example,\nwhen selecting from a list of files, Embark offers an action to delete the file.\nAdditionally Embark offers a facility to collect completion candidates in a\ncollect buffer. The section [[#embark-integration][Embark integration]] documents in detail how Consult\nand Embark work together.\n\n#+toc: headlines 8\n\n* Screenshots :noexport:\n\n#+caption: consult-grep\n[[https://github.com/minad/consult/blob/screenshots/consult-grep.gif?raw=true]]\nFig. 1: Command =consult-git-grep=\n\n#+caption: consult-imenu\n[[https://github.com/minad/consult/blob/screenshots/consult-imenu.png?raw=true]]\nFig. 2: Command =consult-imenu=\n\n#+caption: consult-line\n[[https://github.com/minad/consult/blob/screenshots/consult-line.png?raw=true]]\nFig. 3: Command =consult-line=\n\n* Available commands\n:properties:\n:custom_id: available-commands\n:description: Navigation, search, editing commands and more\n:end:\n#+cindex: commands\n\nMost Consult commands follow the meaningful naming scheme =consult-\u003cthing\u003e=.\nMany commands implement a little known but convenient Emacs feature called\n\"future history\", which guesses what input the user wants. At a command prompt\ntype =M-n= and typically Consult will insert the symbol or thing at point into\nthe input.\n\n*TIP:* If you have [[https://github.com/minad/marginalia][Marginalia]] annotators activated, type =M-x ^consult= to see\nall Consult commands with their abbreviated description. Alternatively, type\n=C-h a ^consult= to get an overview of all Consult variables and functions with\ntheir descriptions.\n\n** Virtual Buffers\n:properties:\n:description: Buffers, bookmarks and recent files\n:end:\n#+cindex: virtual buffers\n\n#+findex: consult-buffer\n#+findex: consult-buffer-other-window\n#+findex: consult-buffer-other-frame\n#+findex: consult-buffer-other-tab\n#+findex: consult-project-buffer\n#+findex: consult-recent-file\n#+findex: consult-bookmark\n- =consult-buffer=: Enhanced version of =switch-to-buffer= with support for virtual\n  buffers. Supports live preview of buffers and narrowing to the virtual buffer\n  types. You can type =f SPC= in order to narrow to recent files. Press =SPC= to\n  show ephemeral buffers. Supported narrowing keys:\n  - b Buffers\n  - SPC Hidden buffers\n  - * Modified buffers\n  - f Files (Requires =recentf-mode=)\n  - r File registers\n  - m Bookmarks\n  - p Project\n  - B Project buffers\n  - F Project files\n  - R Project roots\n  - Custom [[#multiple-sources][other sources]] configured in =consult-buffer-sources=.\n- =consult-buffer-other-window=, =consult-buffer-other-frame=,\n  =consult-buffer-other-tab=: Variants of =consult-buffer=.\n- =consult-project-buffer=: Variant of =consult-buffer= restricted to buffers and\n  recent files of the current project. You can add custom sources to\n  =consult-project-buffer-sources=. The command may prompt you for a project if\n  you invoke it from outside a project.\n- =consult-bookmark=: Select or create bookmark. To select bookmarks you might use the\n  =consult-buffer= as an alternative, which can include a bookmark virtual buffer\n  source. Note that =consult-bookmark= supports preview of bookmarks and\n  narrowing.\n- =consult-recent-file=: Select from recent files with preview.\n  You might prefer the powerful =consult-buffer= instead, which can include\n  recent files as a virtual buffer source. The =recentf-mode= enables tracking of\n  recent files.\n\n** Editing\n:properties:\n:description: Commands useful for editing\n:end:\n#+cindex: editing\n\n#+findex: consult-yank-pop\n#+findex: consult-yank-from-kill-ring\n#+findex: consult-yank-replace\n#+findex: consult-kmacro\n- =consult-yank-from-kill-ring=: Enhanced version of =yank= to select an item\n  from the =kill-ring=. The selected text previewed as overlay in the buffer.\n- =consult-yank-pop=: Enhanced version of =yank-pop= with DWIM-behavior, which\n  either replaces the last =yank= by cycling through the =kill-ring=, or if there\n  has not been a last =yank= consults the =kill-ring=. The selected text previewed\n  as overlay in the buffer.\n- =consult-yank-replace=: Like =consult-yank-pop=, but always replaces the last\n  =yank= with an item from the =kill-ring=.\n- =consult-kmacro=: Select macro from the macro ring and execute it.\n\n** Register\n:properties:\n:description: Searching through registers and fast access\n:end:\n#+cindex: register\n\n#+findex: consult-register\n#+findex: consult-register-load\n#+findex: consult-register-store\n#+findex: consult-register-format\n#+findex: consult-register-window\n- =consult-register=: Select from list of registers. The command\n  supports narrowing to register types and preview of marker positions. This\n  command is useful to search the register contents. For quick access use the\n  commands =consult-register-load=, =consult-register-store= or the built-in Emacs\n  register commands.\n- =consult-register-format=: Set =register-preview-function= to this function for\n  an enhanced register formatting. Used automatically by =consult-register-window=.\n- =consult-register-window=: Replace =register-preview= with this function for a\n  better register window. See the [[#use-package-example][example configuration]].\n- =consult-register-load=: Utility command to quickly load a register.\n  The command either jumps to the register value or inserts it.\n- =consult-register-store=: Improved UI to store registers depending on the current\n  context with an action menu. With an active region, store/append/prepend the\n  contents, optionally deleting the region when a prefix argument is given.\n  With a numeric prefix argument, store/add the number. Otherwise store point,\n  file, buffer, frameset, window or kmacro. Usage examples:\n  * =M-' x=: If no region is active, store point in register =x=.\n    If a region is active, store the region in register =x=.\n  * =M-' M-w x=: Store window configuration in register =x=.\n  * =C-u 100 M-' x=: Store number in register =x=.\n\n** Navigation\n:properties:\n:description: Mark rings, outlines and imenu\n:end:\n#+cindex: navigation\n\n#+findex: consult-goto-line\n#+findex: consult-mark\n#+findex: consult-global-mark\n#+findex: consult-outline\n#+findex: consult-imenu\n#+findex: consult-imenu-multi\n- =consult-goto-line=: Jump to line number enhanced with live preview. This is a\n  drop-in replacement for =goto-line=. Enter a line number to jump to the first\n  column of the given line. Alternatively enter =line:column= in order to jump to\n  a specific column.\n- =consult-mark=: Jump to a marker in the =mark-ring=. Supports live\n  preview and recursive editing.\n- =consult-global-mark=: Jump to a marker in the =global-mark-ring=.\n  Supports live preview and recursive editing.\n- =consult-outline=: Jump to a heading of the outline. Supports narrowing\n  to a heading level, live preview and recursive editing.\n- =consult-imenu=: Jump to imenu item in the current buffer. Supports\n  live preview, recursive editing and narrowing.\n- =consult-imenu-multi=: Jump to imenu item in project buffers, with\n  the same major mode as the current buffer. Supports live preview,\n  recursive editing and narrowing. This feature has been inspired by\n  [[https://github.com/vspinu/imenu-anywhere][imenu-anywhere]].\n\n** Search\n:properties:\n:description: Line search, grep and file search\n:end:\n#+cindex: search\n\n#+findex: consult-line\n#+findex: consult-line-multi\n#+findex: consult-keep-lines\n#+findex: consult-focus-lines\n- =consult-line=: Enter search string and select from matching lines.\n  Supports live preview and recursive editing. The symbol at point and the\n  recent Isearch string are added to the \"future history\" and can be accessed\n  by pressing =M-n=. When =consult-line= is bound to the =isearch-mode-map= and\n  is invoked during a running Isearch, it will use the current Isearch string.\n- =consult-line-multi=: Search dynamically across multiple buffers. By default\n  search across project buffers. If invoked with a prefix argument search across\n  all buffers. The candidates are computed on demand based on the input. The\n  command behaves like =consult-grep=, but operates on buffers instead of files.\n- =consult-keep-lines=: Replacement for =keep/flush-lines= which uses the current\n  completion style for filtering the buffer. The function updates the buffer\n  while typing. In particular =consult-keep-lines= can narrow down an exported\n  Embark collect buffer further, relying on the same completion filtering as\n  ~completing-read~. If the input begins with the negation operator, i.e., ~! SPC~,\n  the filter matches the complement. If a region is active, the region restricts\n  the filtering.\n- =consult-focus-lines=: Temporarily hide lines by filtering them using the\n  current completion style. Call with =C-u= prefix argument in order to show the\n  hidden lines again. If the input begins with the negation operator, i.e., ~!\n  SPC~, the filter matches the complement. In contrast to =consult-keep-lines= this\n  function does not edit the buffer. If a region is active, the region restricts\n  the filtering.\n\n** Grep and Find\n:properties:\n:description: Searching through the filesystem\n:end:\n#+cindex: grep\n#+cindex: find\n#+cindex: locate\n\n#+findex: consult-grep\n#+findex: consult-ripgrep\n#+findex: consult-git-grep\n#+findex: consult-find\n#+findex: consult-fd\n#+findex: consult-locate\n- =consult-grep=, =consult-ripgrep=, =consult-git-grep=: Search for regular expression\n  in files. Consult invokes Grep asynchronously, while you enter the search\n  term. After at least =consult-async-min-input= characters, the search gets\n  started. Consult splits the input string into two parts, if the first\n  character is a punctuation character, like =#=. For example\n  =#regexps#filter-string=, is split at the second =#=. The string =regexps= is passed\n  to Grep. Note that Consult transforms Emacs regular expressions to expressions\n  understand by the search program. Always use Emacs regular expressions at the\n  prompt. If you enter multiple regular expressions separated by space only\n  lines matching all regular expressions are shown. In order to match space\n  literally, escape the space with a backslash. The =filter-string= is passed to\n  the /fast/ Emacs filtering to further narrow down the list of matches. This is\n  particularly useful if you are using an advanced completion style like\n  orderless. =consult-grep= supports preview. =consult-grep= searches the current\n  [[#project-support][project directory]] if a project is found. Otherwise the =default-directory= is\n  searched. If =consult-grep= is invoked with prefix argument =C-u M-s g=, you can\n  specify one or more comma-separated files and directories manually. If invoked\n  with two prefix arguments =C-u C-u M-s g=, you can first select a project if you\n  are not yet inside a project.\n- =consult-find=, =consult-fd=, =consult-locate=: Find file by matching the path\n  against a regexp. Like for =consult-grep=, either the project root or the\n  current directory is the root directory for the search. The input string is\n  treated similarly to =consult-grep=, where the first part is passed to find, and\n  the second part is used for Emacs filtering. Prefix arguments to =consult-find=\n  work just like those for the consult grep commands.\n\n** Compilation\n:properties:\n:description: Jumping to references and compilation errors\n:end:\n#+cindex: compilation errors\n\n#+findex: consult-compile-error\n#+findex: consult-flymake\n#+findex: consult-xref\n- =consult-compile-error=: Jump to a compilation error or grep search result.\n  Supports live preview narrowing and recursive editing.\n- =consult-flymake=: Jump to Flymake diagnostic. Supports live preview and\n  recursive editing. The command supports narrowing. Press =e SPC=, =w SPC=, =n SPC=\n  to only show errors, warnings and notes respectively.\n- =consult-xref=: Integration with xref. This function can be set as\n  =xref-show-xrefs-function= and =xref-show-definitions-function=.\n\n** Histories\n:properties:\n:description: Navigating histories\n:end:\n#+cindex: history\n\n#+findex: consult-complex-command\n#+findex: consult-history\n#+findex: consult-isearch-history\n- =consult-complex-command=: Select a command from the\n  =command-history=. This command is a =completing-read= version of\n  =repeat-complex-command= and is also a replacement for the =command-history=\n  command from chistory.el.\n- =consult-history=: Insert a string from the current buffer history, for example\n  the Eshell or Comint history. You can also invoke this command from the\n  minibuffer. In that case =consult-history= uses the history stored in the\n  =minibuffer-history-variable=. If you prefer =completion-at-point=, take a look at\n  =cape-history= from the [[https://github.com/minad/cape][Cape]] package.\n- =consult-isearch-history=: During an Isearch session, this command picks a\n  search string from history and continues the search with the newly selected\n  string. Outside of Isearch, the command allows you to pick a string from the\n  history and starts a new Isearch. =consult-isearch-history= acts as a drop-in\n  replacement for =isearch-edit-string=.\n\n** Modes\n:properties:\n:description: Toggling minor modes and executing commands\n:end:\n#+cindex: minor mode\n#+cindex: major mode\n\n#+findex: consult-minor-mode-menu\n#+findex: consult-mode-command\n- =consult-minor-mode-menu=: Enable/disable minor mode. Supports\n  narrowing to on/off/local/global modes by pressing =i/o/l/g SPC=\n  respectively.\n- =consult-mode-command=: Run a command from the currently active minor or major\n  modes. Supports narrowing to local-minor/global-minor/major mode via the keys\n  =l/g/m=.\n\n** Org Mode\n:properties:\n:description: Org-specific commands\n:end:\n\n#+findex: consult-org-heading\n#+findex: consult-org-agenda\n- =consult-org-heading=: Variant of =consult-imenu= or =consult-outline= for Org\n  buffers. The headline and its ancestors headlines are separated by slashes.\n  Supports narrowing by heading level, priority and TODO keyword, as well as live\n  preview and recursive editing.\n- =consult-org-agenda=: Jump to an Org agenda heading. Supports narrowing by\n  heading level, priority and TODO keyword, as well as live preview and\n  recursive editing.\n** Help\n:properties:\n:description: Searching through help\n:end:\n\n#+findex: consult-info\n#+findex: consult-info-define\n#+findex: consult-man\n- =consult-man=: Find Unix man page, via Unix =apropos= or =man -k=. =consult-man= opens\n  the selected man page using the Emacs =man= command. Supports live preview of\n  the theme while scrolling through the candidates.\n- =consult-info=: Full text search through info pages. If the command is invoked\n  from within an ~*info*~ buffer, it will search through the current manual. You\n  may want to create your own =consult-info-*= commands which search through a\n  predefined set of info pages. You can use the function =consult-info-define= to\n  define commands =consult-info-emacs=, =consult-info-completion=, =consult-info-org=,\n  and so on:\n#+begin_src emacs-lisp\n(consult-info-define \"emacs\" \"efaq\" \"elisp\" \"cl\" \"compat\" \"eshell\")\n(consult-info-define 'completion\n                     \"vertico\" \"consult\" \"marginalia\" \"orderless\"\n                     \"embark\" \"corfu\" \"cape\" \"tempel\")\n(consult-info-define \"org\")\n(consult-info-define \"gnus\")\n(consult-info-define \"magit\")\n#+end_src\n\n** Miscellaneous\n:properties:\n:description: Various other useful commands\n:end:\n\n#+findex: consult-completion-in-region\n#+findex: consult-theme\n#+findex: consult-preview-at-point\n#+findex: consult-preview-at-point-mode\n- =consult-theme=: Select a theme and disable all currently enabled themes.\n  Supports live preview of the theme while scrolling through the candidates.\n- =consult-preview-at-point= and =consult-preview-at-point-mode=: Command and minor\n  mode which previews the candidate at point in the =*Completions*= buffer. This\n  mode is relevant if you use [[https://git.sr.ht/~protesilaos/mct][Mct]] or the default =*Completions*= UI.\n- =consult-completion-in-region=: In case you don't use [[https://github.com/minad/corfu][Corfu]] as your in-buffer\n  completion UI, this function can be set as =completion-in-region-function=. Then\n  your minibuffer completion UI (e.g., Vertico or Icomplete) will be used for\n  =completion-at-point=.\n  #+begin_src emacs-lisp\n  (setq completion-in-region-function #'consult-completion-in-region)\n  #+end_src\n  Instead of =consult-completion-in-region=, you may prefer to see the completions\n  directly in the buffer as a small popup. In that case, I recommend the [[https://github.com/minad/corfu][Corfu]]\n  package. There is a technical limitation of =consult-completion-in-region= in\n  combination with the Lsp modes. The Lsp server relies on the input at point,\n  in order to generate refined candidate strings. Since the completion is\n  transferred from the original buffer to the minibuffer, the server does not\n  receive the updated input. In contrast, in-buffer Lsp completion for example\n  via Corfu works properly since the completion takes place directly in the\n  original buffer.\n\n* Special features\n:properties:\n:description: Enhancements over built-in `completing-read'\n:end:\n\nConsult enhances =completing-read= with live previews of candidates, additional\nnarrowing capabilities to candidate groups and asynchronously generated\ncandidate lists. The internal =consult--read= function, which is used by most\nConsult commands, is a thin wrapper around =completing-read= and provides the\nspecial functionality. In order to support multiple candidate sources there\nexists the high-level function =consult--multi=. The architecture of Consult\nallows it to work with different completion systems in the backend, while still\noffering advanced features.\n\n** Live previews\n:properties:\n:description: Preview the currently selected candidate\n:custom_id: live-previews\n:end:\n#+cindex: preview\n\nSome Consult commands support live previews. For example when you scroll through\nthe items of =consult-line=, the buffer will scroll to the corresponding position.\nIt is possible to jump back and forth between the minibuffer and the buffer to\nperform recursive editing while the search is ongoing.\n\nConsult enables previews by default. You can disable them by adjusting the\n=consult-preview-key= variable. Furthermore it is possible to specify keybindings\nwhich trigger the preview manually as shown in the [[#use-package-example][example configuration]]. The\ndefault setting of =consult-preview-key= is =any= which means that Consult triggers\nthe preview /immediately/ on any key press when the selected candidate changes.\nYou can configure each command individually with its own =:preview-key=. The\nfollowing settings are possible:\n\n- Automatic and immediate ='any=\n- Automatic and delayed =(list :debounce 0.5 'any)=\n- Manual and immediate =\"M-.\"=\n- Manual and delayed =(list :debounce 0.5 \"M-.\")=\n- Disabled =nil=\n\nA safe recommendation is to leave automatic immediate previews enabled in\ngeneral and disable the automatic preview only for commands where the preview\nmay be expensive due to file loading. Internally, Consult uses the\nvalue of =this-command= to determine the =:preview-key=\ncustomized. This means that if you wrap a =consult-*= command within\nyour own function or command, you will also need to add the name of\n/your custom command/ to the =consult-customize= call in order for it\nto be considered.\n\n#+begin_src emacs-lisp\n(consult-customize\n consult-ripgrep consult-git-grep consult-grep consult-man\n consult-bookmark consult-recent-file consult-xref\n consult--source-bookmark consult--source-file-register\n consult--source-recent-file consult--source-project-recent-file\n ;; my/command-wrapping-consult    ;; disable auto previews inside my command\n :preview-key '(:debounce 0.4 any) ;; Option 1: Delay preview\n ;; :preview-key \"M-.\")            ;; Option 2: Manual preview\n#+end_src\n\nIn this case one may wonder what the difference is between using an Embark\naction on the current candidate in comparison to a manually triggered preview.\nThe main difference is that the files opened by manual preview are closed again\nafter the completion session. During preview some functionality is disabled to\nimprove the performance, see for example the customization variables\n=consult-preview-variables= and =consult-preview-allowed-hooks=. Only hooks listed\nin =consult-preview-allowed-hooks= are executed. This variable applies to\n=find-file-hook=, =change-major-mode-hook= and mode hooks, e.g., =prog-mode-hook=. In\norder to enable additional font locking during preview, add the corresponding\nhooks to the allow list. The following code demonstrates this for [[https://github.com/minad/org-modern][org-modern]] and\n[[https://github.com/tarsius/hl-todo][hl-todo]].\n\n#+begin_src emacs-lisp\n;; local modes added to prog-mode hooks\n(add-to-list 'consult-preview-allowed-hooks 'hl-todo-mode)\n(add-to-list 'consult-preview-allowed-hooks 'elide-head-mode)\n;; enabled global modes\n(add-to-list 'consult-preview-allowed-hooks 'global-org-modern-mode)\n(add-to-list 'consult-preview-allowed-hooks 'global-hl-todo-mode)\n#+end_src\n\nFiles larger than =consult-preview-partial-size= are previewed partially. Delaying\nthe preview is also useful for =consult-theme=, since the theme preview is slow.\nThe delay results in a smoother UI experience.\n\n#+begin_src emacs-lisp\n;; Preview on any key press, but delay 0.5s\n(consult-customize consult-theme :preview-key '(:debounce 0.5 any))\n;; Preview immediately on M-., on up/down after 0.5s, on any other key after 1s\n(consult-customize consult-theme\n                   :preview-key\n                   '(\"M-.\"\n                     :debounce 0.5 \"\u003cup\u003e\" \"\u003cdown\u003e\"\n                     :debounce 1 any))\n#+end_src\n\n** Narrowing and grouping\n:properties:\n:description: Restricting the completion to a candidate group\n:custom_id: narrowing-and-grouping\n:end:\n#+cindex: narrowing\n\nConsult has special support for candidate groups. If the completion UI supports\nthe grouping functionality, the UI separates the groups with thin lines and\nshows group titles. Grouping is useful if the list of candidates consists of\ncandidates of multiple types or candidates from [[#multiple-sources][multiple sources]], like the\n=consult-buffer= command, which shows both buffers and recently opened files. Note\nthat you can disable the group titles by setting the =:group= property of the\ncorresponding command to nil using the =consult-customize= macro.\n\nBy entering a narrowing prefix or by pressing a narrowing key it is possible to\nrestrict the completion candidates to a certain candidate group. When you use\nthe =consult-buffer= command, you can enter the prefix =b SPC= to restrict list of\ncandidates to buffers only. If you press =DEL= afterwards, the full candidate list\nwill be shown again. Furthermore a narrowing prefix key and a widening key can\nbe configured which can be pressed to achieve the same effect, see the\nconfiguration variables =consult-narrow-key= and =consult-widen-key=.\n\nAfter pressing =consult-narrow-key=, the possible narrowing keys can be shown by\npressing =C-h=. When pressing =C-h= after some prefix key, the =prefix-help-command=\nis invoked, which shows the keybinding help window by default. As a more compact\nalternative, there is the =consult-narrow-help= command which can be bound to a\nkey, for example =?= or =C-h= in the =consult-narrow-map=, as shown in the [[#use-package-example][example\nconfiguration]]. If [[https://github.com/justbur/emacs-which-key][which-key]] is installed, the narrowing keys are automatically\nshown in the which-key window after pressing the =consult-narrow-key=.\n\n** Asynchronous search\n:properties:\n:description: Filtering asynchronously generated candidate lists\n:end:\n#+cindex: asynchronous search\n\nConsult has support for asynchronous generation of candidate lists. This feature\nis used for search commands like =consult-grep=, where the list of matches is\ngenerated dynamically while the user is typing a regular expression. The grep\nprocess is executed in the background. When modifying the regular expression,\nthe background process is terminated and a new process is started with the\nmodified regular expression.\n\nThe matches, which have been found, can then be narrowed using the installed\nEmacs completion-style. This can be powerful if you are using for example the\n=orderless= completion style.\n\nThis two-level filtering is possible by splitting the input string. Part of the\ninput string is treated as input to grep and part of the input is used for\nfiltering. There are multiple splitting styles available, configured in\n~consult-async-split-styles-alist~: =nil=, =comma=, =semicolon= and =perl=. The default\nsplitting style is configured with the variable ~consult-async-split-style~.\n\nWith the =comma= and =semicolon= splitting styles, the first word before the comma\nor semicolon is passed to grep, the remaining string is used for filtering. The\n=nil= splitting style does not perform any splitting, the whole input is passed to\ngrep.\n\nThe =perl= splitting style splits the input string at a punctuation character,\nusing a similar syntax as Perl regular expressions.\n\nExamples:\n\n- =#defun=: Search for \"defun\" using grep.\n- =#consult embark=: Search for both \"consult\" and \"embark\" using grep in any order.\n- =#first.*second=: Search for \"first\" followed by \"second\" using grep.\n- =#\\(consult\\|embark\\)=: Search for \"consult\" or \"embark\" using grep. Note the\n  usage of Emacs-style regular expressions.\n- =#defun#consult=: Search for \"defun\" using grep, filter with the word\n  \"consult\".\n- =/defun/consult=: It is also possible to use other punctuation\n  characters.\n- =#to#=: Force searching for \"to\" using grep, since the grep pattern\n  must be longer than =consult-async-min-input= characters by default.\n- =#defun -- --invert-match#=: Pass argument =--invert-match= to grep.\n\nAsynchronous processes like =find= and =grep= create an error log buffer\n=_*consult-async*= (note the leading space), which is useful for\ntroubleshooting. The prompt has a small indicator showing the process status:\n\n- =:= the usual prompt colon, before input is provided.\n- =*= with warning face, the process is running.\n- =:= with success face, success, process exited with an error code of zero.\n- =!= with error face, failure, process exited with a nonzero error code.\n- =;= with error face, interrupted, for example if more input is provided.\n\n** Multiple sources\n:properties:\n:description: Combining candidates from different sources\n:custom_id: multiple-sources\n:end:\n#+cindex: multiple sources\n\nMultiple static and asynchronous candidate sources can be combined. This feature\nis used by the =consult-buffer= command to present buffer-like candidates in a\nsingle menu for quick access. By default =consult-buffer= includes buffers,\nbookmarks, recent files and project-specific buffers and files. The\n=consult-buffer-sources= variable configures the list of sources. Arbitrary custom\nsources can be added to this list.\n\nAs an example, the bookmark source is defined as follows:\n\n#+begin_src emacs-lisp\n(defvar consult--source-bookmark\n  `(:name     \"Bookmark\"\n    :narrow   ?m\n    :category bookmark\n    :face     consult-bookmark\n    :history  bookmark-history\n    :items    ,#'bookmark-all-names\n    :action   ,#'consult--bookmark-action))\n#+end_src\n\nEither the =:items= or the =:async= source field is required:\n- =:items= List of strings to select from or function returning list of strings.\n  The strings can carry metadata in text properties, which is then available to\n  the =:annotate=, =:action= and =:state= functions. The list can also consist of\n  pairs, with the string in the =car= used for display and the =cdr= the actual\n  candidate.\n- =:async= Alternative to =:items= for asynchronous sources. See the docstring for\n  details.\n\nOptional source fields:\n- =:name= Name of the source, used for narrowing, group titles and annotations.\n- =:narrow= Narrowing character, =(char . string)= pair or list of pairs.\n- =:category= Completion category.\n- =:preview-key= Preview key or keys which trigger preview.\n- =:enabled= Function which must return t if the source is enabled.\n- =:hidden= When t candidates of this source are hidden by default.\n- =:face= Face used for highlighting the candidates.\n- =:annotate= Annotation function called for each candidate, returns string.\n- =:history= Name of history variable to add selected candidate.\n- =:default= Must be t if the first item of the source is the default value.\n- =:action= Function called with the selected candidate.\n- =:new= Function called with new candidate name, only if =:require-match= is nil.\n- =:state= State constructor for the source, must return the state function.\n- Other source fields can be added specifically to the use case.\n\nThe =:state= and =:action= fields of the sources deserve a longer explanation. The\n=:action= function takes a single argument and is only called after selection with\nthe selected candidate, if the selection has not been aborted. This\nfunctionality is provided for convenience and easy definition of sources. The\n=:state= field is more general. The =:state= function is a constructor function\nwithout arguments, which can perform some setup necessary for the preview. It\nmust return a closure which takes an ACTION and a CANDIDATE argument. See the\ndocstring of =consult--with-preview= for more details about the ACTION argument.\n\nBy default, =consult-buffer= previews buffers, bookmarks and files. Loading recent\nfiles or bookmarks can result in expensive operations. However it is possible to\nconfigure a manual preview as follows.\n\n#+begin_src emacs-lisp\n(consult-customize\n consult--source-bookmark consult--source-file-register\n consult--source-recent-file consult--source-project-recent-file\n :preview-key \"M-.\")\n#+end_src\n\nSources can be added directly to the =consult-buffer-source= list for convenience.\nFor example, the following source lists all Org buffers and lets you create new\nones.\n\n#+begin_src emacs-lisp\n(defvar org-source\n  (list :name     \"Org Buffer\"\n        :category 'buffer\n        :narrow   ?o\n        :face     'consult-buffer\n        :history  'buffer-name-history\n        :state    #'consult--buffer-state\n        :new\n        (lambda (name)\n          (with-current-buffer (get-buffer-create name)\n            (insert \"#+title: \" name \"\\n\\n\")\n            (org-mode)\n            (consult--buffer-action (current-buffer))))\n        :items\n        (lambda ()\n          (consult--buffer-query :mode 'org-mode :as #'consult--buffer-pair))))\n\n(add-to-list 'consult-buffer-sources 'org-source 'append)\n#+end_src\n\nOne can create similar sources for other major modes. See the [[https://github.com/minad/consult/wiki][Consult wiki]] for\nmany additional source examples. See also the documentation of =consult-buffer=\nand of the internal =consult--multi= API. The function =consult--multi= can be used\nto create new multi-source commands.\n\n** Embark integration\n:properties:\n:description: Actions, Grep/Occur-buffer export\n:custom_id: embark-integration\n:end:\n#+cindex: embark\n\n*NOTE*: Install the =embark-consult= package from MELPA, which provides\nConsult-specific Embark actions and the Occur buffer export.\n\nEmbark is a versatile package which offers context dependent actions, comparable\nto a context menu. See the [[https://github.com/oantolin/embark][Embark manual]] for an extensive description of its\ncapabilities.\n\nActions are commands which can operate on the currently selected candidate (or\ntarget in Embark terminology). When completing files, for example the\n=delete-file= command is offered. With Embark you can execute arbitrary commands\non the currently selected candidate via =M-x=.\n\nFurthermore Embark provides the =embark-collect= command, which collects\ncandidates and presents them in an Embark collect buffer, where further actions\ncan be applied to them. A related feature is the =embark-export= command, which\nexports candidate lists to a buffer of a special type. For example in the case\nof file completion, a Dired buffer is opened.\n\nIn the context of Consult, particularly exciting is the possibility to export\nthe matching lines from =consult-line=, =consult-outline=, =consult-mark= and\n=consult-global-mark=. The matching lines are exported to an Occur buffer where\nthey can be edited via the =occur-edit-mode= (press key =e=). Similarly, Embark\nsupports exporting the matches found by =consult-grep=, =consult-ripgrep= and\n=consult-git-grep= to a Grep buffer, where the matches across files can be edited,\nif the [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] package is installed. These three workflows are symmetric.\n\n+ =consult-line= -\u003e =embark-export= to =occur-mode= buffer -\u003e =occur-edit-mode= for editing of matches in buffer.\n+ =consult-grep= -\u003e =embark-export= to =grep-mode= buffer -\u003e =wgrep= for editing of all matches.\n+ =consult-find= -\u003e =embark-export= to =dired-mode= buffer -\u003e =wdired-change-to-wdired-mode= for editing.\n\n* Configuration\n:properties:\n:description: Example configuration and customization variables\n:end:\n\nConsult can be installed from [[https://elpa.gnu.org/packages/consult.html][ELPA]] or [[https://melpa.org/#/consult][MELPA]] via the Emacs built-in package\nmanager. Alternatively it can be directly installed from the development\nrepository via other non-standard package managers.\n\nThere is the [[https://github.com/minad/consult/wiki][Consult wiki]], where additional configuration examples can be\ncontributed.\n\n*IMPORTANT:* It is recommended that you enable [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html][lexical binding]] in your\nconfiguration. Many Consult-related code snippets require lexical binding, since\nthey use lambdas and closures.\n\n** Use-package example\n:properties:\n:description: Configuration example based on use-package\n:custom_id: use-package-example\n:end:\n#+cindex: use-package\n\nThe Consult package only provides commands and does not add any keybindings or\nmodes. Therefore the package is non-intrusive but requires a little setup\neffort. While the configuration example is long, it consists essentially of key\nbindings only, such that the risk of interference with other Emacs functionality\nis minimized.\n\nIn order to use the Consult commands, it is recommended to add keybindings for\ncommands which are accessed often. Rarely used commands can be invoked via =M-x=.\nFeel free to only bind the commands you consider useful to your workflow. The\nconfiguration shown here relies on the =use-package= macro, which is a convenient\ntool to manage package configurations.\n\n*NOTE:* There is the [[https://github.com/minad/consult/wiki][Consult wiki]], where you can contribute additional\nconfiguration examples.\n\n#+begin_src emacs-lisp\n;; Example configuration for Consult\n(use-package consult\n  ;; Replace bindings. Lazily loaded by `use-package'.\n  :bind (;; C-c bindings in `mode-specific-map'\n         (\"C-c M-x\" . consult-mode-command)\n         (\"C-c h\" . consult-history)\n         (\"C-c k\" . consult-kmacro)\n         (\"C-c m\" . consult-man)\n         (\"C-c i\" . consult-info)\n         ([remap Info-search] . consult-info)\n         ;; C-x bindings in `ctl-x-map'\n         (\"C-x M-:\" . consult-complex-command)     ;; orig. repeat-complex-command\n         (\"C-x b\" . consult-buffer)                ;; orig. switch-to-buffer\n         (\"C-x 4 b\" . consult-buffer-other-window) ;; orig. switch-to-buffer-other-window\n         (\"C-x 5 b\" . consult-buffer-other-frame)  ;; orig. switch-to-buffer-other-frame\n         (\"C-x t b\" . consult-buffer-other-tab)    ;; orig. switch-to-buffer-other-tab\n         (\"C-x r b\" . consult-bookmark)            ;; orig. bookmark-jump\n         (\"C-x p b\" . consult-project-buffer)      ;; orig. project-switch-to-buffer\n         ;; Custom M-# bindings for fast register access\n         (\"M-#\" . consult-register-load)\n         (\"M-'\" . consult-register-store)          ;; orig. abbrev-prefix-mark (unrelated)\n         (\"C-M-#\" . consult-register)\n         ;; Other custom bindings\n         (\"M-y\" . consult-yank-pop)                ;; orig. yank-pop\n         ;; M-g bindings in `goto-map'\n         (\"M-g e\" . consult-compile-error)\n         (\"M-g f\" . consult-flymake)               ;; Alternative: consult-flycheck\n         (\"M-g g\" . consult-goto-line)             ;; orig. goto-line\n         (\"M-g M-g\" . consult-goto-line)           ;; orig. goto-line\n         (\"M-g o\" . consult-outline)               ;; Alternative: consult-org-heading\n         (\"M-g m\" . consult-mark)\n         (\"M-g k\" . consult-global-mark)\n         (\"M-g i\" . consult-imenu)\n         (\"M-g I\" . consult-imenu-multi)\n         ;; M-s bindings in `search-map'\n         (\"M-s d\" . consult-find)                  ;; Alternative: consult-fd\n         (\"M-s c\" . consult-locate)\n         (\"M-s g\" . consult-grep)\n         (\"M-s G\" . consult-git-grep)\n         (\"M-s r\" . consult-ripgrep)\n         (\"M-s l\" . consult-line)\n         (\"M-s L\" . consult-line-multi)\n         (\"M-s k\" . consult-keep-lines)\n         (\"M-s u\" . consult-focus-lines)\n         ;; Isearch integration\n         (\"M-s e\" . consult-isearch-history)\n         :map isearch-mode-map\n         (\"M-e\" . consult-isearch-history)         ;; orig. isearch-edit-string\n         (\"M-s e\" . consult-isearch-history)       ;; orig. isearch-edit-string\n         (\"M-s l\" . consult-line)                  ;; needed by consult-line to detect isearch\n         (\"M-s L\" . consult-line-multi)            ;; needed by consult-line to detect isearch\n         ;; Minibuffer history\n         :map minibuffer-local-map\n         (\"M-s\" . consult-history)                 ;; orig. next-matching-history-element\n         (\"M-r\" . consult-history))                ;; orig. previous-matching-history-element\n\n  ;; Enable automatic preview at point in the *Completions* buffer. This is\n  ;; relevant when you use the default completion UI.\n  :hook (completion-list-mode . consult-preview-at-point-mode)\n\n  ;; The :init configuration is always executed (Not lazy)\n  :init\n\n  ;; Tweak the register preview for `consult-register-load',\n  ;; `consult-register-store' and the built-in commands.  This improves the\n  ;; register formatting, adds thin separator lines, register sorting and hides\n  ;; the window mode line.\n  (advice-add #'register-preview :override #'consult-register-window)\n  (setq register-preview-delay 0.5)\n\n  ;; Use Consult to select xref locations with preview\n  (setq xref-show-xrefs-function #'consult-xref\n        xref-show-definitions-function #'consult-xref)\n\n  ;; Configure other variables and modes in the :config section,\n  ;; after lazily loading the package.\n  :config\n\n  ;; Optionally configure preview. The default value\n  ;; is 'any, such that any key triggers the preview.\n  ;; (setq consult-preview-key 'any)\n  ;; (setq consult-preview-key \"M-.\")\n  ;; (setq consult-preview-key '(\"S-\u003cdown\u003e\" \"S-\u003cup\u003e\"))\n  ;; For some commands and buffer sources it is useful to configure the\n  ;; :preview-key on a per-command basis using the `consult-customize' macro.\n  (consult-customize\n   consult-theme :preview-key '(:debounce 0.2 any)\n   consult-ripgrep consult-git-grep consult-grep consult-man\n   consult-bookmark consult-recent-file consult-xref\n   consult--source-bookmark consult--source-file-register\n   consult--source-recent-file consult--source-project-recent-file\n   ;; :preview-key \"M-.\"\n   :preview-key '(:debounce 0.4 any))\n\n  ;; Optionally configure the narrowing key.\n  ;; Both \u003c and C-+ work reasonably well.\n  (setq consult-narrow-key \"\u003c\") ;; \"C-+\"\n\n  ;; Optionally make narrowing help available in the minibuffer.\n  ;; You may want to use `embark-prefix-help-command' or which-key instead.\n  ;; (keymap-set consult-narrow-map (concat consult-narrow-key \" ?\") #'consult-narrow-help)\n)\n#+end_src\n\n** Custom variables\n:properties:\n:description: Short description of all customization settings\n:end:\n#+cindex: customization\n\n*TIP:* If you have [[https://github.com/minad/marginalia][Marginalia]] installed, type =M-x customize-variable RET\n^consult= to see all Consult-specific customizable variables with their current\nvalues and abbreviated description. Alternatively, type =C-h a ^consult= to get\nan overview of all Consult variables and functions with their descriptions.\n\n| Variable                         | Description                                         |\n|----------------------------------+-----------------------------------------------------|\n| consult-after-jump-hook          | Functions to call after jumping to a location       |\n| consult-async-input-debounce     | Input debounce for asynchronous commands            |\n| consult-async-input-throttle     | Input throttle for asynchronous commands            |\n| consult-async-min-input          | Minimum numbers of input characters                 |\n| consult-async-refresh-delay      | Refresh delay for asynchronous commands             |\n| consult-async-split-style        | Splitting style used for async commands             |\n| consult-async-split-styles-alist | Available splitting styles used for async commands  |\n| consult-async-indicator          | Async indicator characters                          |\n| consult-bookmark-narrow          | Narrowing configuration for =consult-bookmark=        |\n| consult-buffer-filter            | Filter for =consult-buffer=                           |\n| consult-buffer-sources           | List of virtual buffer sources                      |\n| consult-fd-args                  | Command line arguments for fd                       |\n| consult-find-args                | Command line arguments for find                     |\n| consult-fontify-max-size         | Buffers larger than this limit are not fontified    |\n| consult-fontify-preserve         | Preserve fontification for line-based commands.     |\n| consult-git-grep-args            | Command line arguments for git-grep                 |\n| consult-goto-line-numbers        | Show line numbers for =consult-goto-line=             |\n| consult-grep-max-columns         | Maximal number of columns of the matching lines     |\n| consult-grep-args                | Command line arguments for grep                     |\n| consult-imenu-config             | Mode-specific configuration for =consult-imenu=       |\n| consult-line-numbers-widen       | Show absolute line numbers when narrowing is active |\n| consult-line-start-from-top      | Start the =consult-line= search from the top          |\n| consult-locate-args              | Command line arguments for locate                   |\n| consult-man-args                 | Command line arguments for man                      |\n| consult-mode-command-filter      | Filter for =consult-mode-command=                     |\n| consult-mode-histories           | Mode-specific history variables                     |\n| consult-narrow-key               | Narrowing prefix key during completion              |\n| consult-point-placement          | Placement of the point when jumping to matches      |\n| consult-preview-key              | Keys which triggers preview                         |\n| consult-preview-allowed-hooks    | List of hooks to allow during preview               |\n| consult-preview-excluded-buffers | Predicate to exclude buffers from preview           |\n| consult-preview-excluded-files   | Regexps matched against file names during preview   |\n| consult-preview-max-count        | Maximum number of files to keep open during preview |\n| consult-preview-partial-size     | Files larger than this size are previewed partially |\n| consult-preview-partial-chunk    | Size of the file chunk which is previewed partially |\n| consult-preview-variables        | Alist of variables to bind during preview           |\n| consult-project-buffer-sources   | List of virtual project buffer sources              |\n| consult-project-function         | Function which returns current project root         |\n| consult-register-prefix          | Prefix string for register keys during completion   |\n| consult-ripgrep-args             | Command line arguments for ripgrep                  |\n| consult-themes                   | List of themes to be presented for selection        |\n| consult-widen-key                | Widening key during completion                      |\n\n** Project support\n:properties:\n:description: Project discovery support for search commands\n:custom_id: project-support\n:end:\n\nMultiple Consult search commands like =consult-grep= try to discover the current\nproject and search in the project top level directory by default, if a project\nis found. Otherwise they fall back to the =default-directory=. By default, Consult\nuses the Emacs built-in project discovery support (=project-current= and\n=project-root=). It is possible to configure alternative methods via the\ncustomization variable =consult-project-function=.\n\n#+begin_src emacs-lisp\n;; Optionally configure a different project root function.\n;; 1. project.el (the default)\n(setq consult-project-function #'consult--default-project--function)\n;; 2. vc.el (vc-root-dir)\n(setq consult-project-function (lambda (_) (vc-root-dir)))\n;; 3. locate-dominating-file\n(setq consult-project-function (lambda (_) (locate-dominating-file \".\" \".git\")))\n;; 4. projectile.el (projectile-project-root)\n(autoload 'projectile-project-root \"projectile\")\n(setq consult-project-function (lambda (_) (projectile-project-root)))\n;; 5. Disable project support\n(setq consult-project-function nil)\n#+end_src\n\n** Fine-tuning of individual commands\n:properties:\n:alt_title: Fine-tuning\n:description: Fine-grained configuration for special requirements\n:end:\n\n*NOTE:* Consult supports fine-grained customization of individual commands. This\nconfiguration feature exists for experienced users with special requirements.\nThere is the [[https://github.com/minad/consult/wiki][Consult wiki]], where we collect further configuration examples.\n\nCommands and buffer sources allow flexible, individual customization by using\nthe =consult-customize= macro. You can override any option passed to the internal\n=consult--read= API. Note that since =consult--read= is part of the internal API,\noptions could be removed, replaced or renamed in future versions of the package.\n\nUseful options are:\n- =:prompt= set the prompt string\n- =:preview-key= set the preview key, default is =consult-preview-key=\n- =:initial= set the initial input\n- =:initial-narrow= set the initial narrow key\n- =:default= set the default value\n- =:history= set the history variable symbol\n- =:add-history= add items to the future history, for example symbol at point\n- =:sort= enable or disable sorting\n- =:group= set to nil to disable candidate grouping and titles.\n- =:inherit-input-method= set to non-nil to inherit the input method.\n\n#+begin_src emacs-lisp\n(consult-customize\n ;; Disable preview for `consult-theme' completely.\n consult-theme :preview-key nil\n ;; Set preview for `consult-buffer' to key `M-.'\n consult-buffer :preview-key \"M-.\"\n ;; For `consult-line' change the prompt and specify multiple preview\n ;; keybindings. Note that you should bind \u003cS-up\u003e and \u003cS-down\u003e in the\n ;; `minibuffer-local-completion-map' or `vertico-map' to the commands which\n ;; select the previous or next candidate.\n consult-line :prompt \"Search: \"\n :preview-key '(\"S-\u003cdown\u003e\" \"S-\u003cup\u003e\"))\n#+end_src\n\nThe configuration values are evaluated at runtime, just before the completion\nsession is started. Therefore you can use for example =thing-at-point= to adjust\nthe initial input or the future history.\n\n#+begin_src emacs-lisp\n(consult-customize\n consult-line\n :add-history (seq-some #'thing-at-point '(region symbol)))\n\n(defalias 'consult-line-thing-at-point 'consult-line)\n\n(consult-customize\n consult-line-thing-at-point\n :initial (thing-at-point 'symbol))\n#+end_src\n\nGenerally it is possible to modify commands for your individual needs by the\nfollowing techniques:\n\n1. Use =consult-customize= in order to change the command or source settings.\n2. Create your own wrapper function which passes modified arguments to the Consult functions.\n3. Create your own buffer [[#multiple-sources][multi sources]] for =consult-buffer=.\n4. Create advices to modify some internal behavior.\n5. Write or propose a patch.\n\n* Recommended packages\n:properties:\n:description: Related packages recommended for installation\n:end:\n\nI use and recommend this combination of packages:\n\n- consult: This package\n- [[https://github.com/minad/vertico][vertico]]: Fast and minimal vertical completion system\n- [[https://github.com/minad/marginalia][marginalia]]: Annotations for the completion candidates\n- [[https://github.com/oantolin/embark][embark and embark-consult]]: Action commands, which can act on the completion candidates\n- [[https://github.com/oantolin/orderless][orderless]]: Completion style which offers flexible candidate filtering\n- [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]]: Editing of grep buffers. Use with =consult-grep= via =embark-export=.\n\nThere exist multiple fine completion UIs beside Vertico, which are supported by\nConsult. Give them a try and find out which interaction model fits best for you.\n\n- The builtin completion UI, which pops up the =*Completions*= buffer.\n- The builtin =icomplete-vertical-mode=.\n- [[https://git.sr.ht/~protesilaos/mct][mct by Protesilaos Stavrou]]: Minibuffer and Completions in Tandem, which builds\n  on the default completion UI.\n\nNote that all packages are independent and can be exchanged with alternative\ncomponents, since there exist no hard dependencies. Furthermore it is possible\nto get started with only default completion and Consult and add more components\nlater to the mix. For example you can omit Marginalia if you don't need\nannotations. I highly recommend the Embark package, but in order to familiarize\nyourself with the other components, you can first start without it - or you could\nuse with Embark right away and add the other components later on.\n\nWe document a [[https://github.com/minad/consult/wiki/Auxiliary-packages][list of auxiliary packages]] in the Consult wiki. These packages\nintegrate Consult with special programs or with other packages in the wider\nEmacs ecosystem.\n\n* Bug reports\n:properties:\n:description: How to create reproducible bug reports\n:end:\n\nIf you find a bug or suspect that there is a problem with Consult, please carry\nout the following steps:\n\n1. *Search through the issue tracker* if your issue has been reported before (and\n   has been resolved eventually) in the meantime.\n2. *Remove all packages involved in the suspected bug from your installation.*\n3. *Reinstall the newest version of all relevant packages*. Updating alone is not\n   sufficient, since package.el sometimes causes miscompilation. The list of\n   packages includes Consult, Compat, Vertico or other completion UIs,\n   Marginalia, Embark and Orderless.\n4. Either use the default completion UI or ensure that exactly one of\n   =vertico-mode=, =mct-mode=, or =icomplete-mode= is enabled. The unsupported modes\n   =selectrum-mode=, =ivy-mode=, =helm-mode=, =ido-mode= and =ido-ubiquitous-mode= must be\n   disabled.\n5. Ensure that the =completion-styles= variable is properly configured. Try to set\n   =completion-styles= to a list including =substring= or =orderless=.\n6. Try to reproduce the issue with the newest stable Emacs version. Start a bare\n   bone Emacs instance with =emacs -Q= on the command line. Execute the following\n   minimal code snippets in the scratch buffer. This way we can exclude side\n   effects due to configuration settings. If other packages are relevant to\n   reproduce the issue, include them in the minimal configuration snippet.\n\nMinimal setup with Vertico for =emacs -Q=:\n#+begin_src emacs-lisp\n(package-initialize)\n(require 'consult)\n(require 'vertico)\n(vertico-mode)\n(setq completion-styles '(substring basic))\n#+end_src\n\nMinimal setup with the default completion system for =emacs -Q=:\n#+begin_src emacs-lisp\n(package-initialize)\n(require 'consult)\n(setq completion-styles '(substring basic))\n#+end_src\n\nPlease provide the necessary important information with your bug report:\n\n- The minimal configuration snippet used to reproduce the issue.\n- Your completion UI (Default completion, Vertico, Mct or Icomplete).\n- A stack trace in case the bug triggers an exception.\n- Your Emacs version, since bugs may be fixed or introduced in newer versions.\n- Your operating system, since Emacs behavior varies subtly between Linux, Mac\n  and Windows.\n- The package manager, e.g., straight.el or package.el, used to install the\n  Emacs packages, in order to exclude update issues. Did you install Consult as\n  part of the Doom Emacs distribution?\n- Do you use Evil? Consult does not provide Evil integration out of the box, but\n  there is some support in [[https://github.com/emacs-evil/evil-collection][evil-collection]].\n\nWhen evaluating Consult-related code snippets you should enable [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html][lexical binding]].\nConsult often relies on lambdas and lexical closures.\n\n* Hacking\n** Creating asynchronous completion commands\n\nIf you have a completion source that's both dynamic and expensive to generate,\n=completing-read= may not be the best choice. Instead, =consult--read= serves as a\nthin wrapper around =completing-read= that provides this functionality. For\nexample, consider the following slow script that splits its input on space:\n\n#+begin_src sh\n#!/usr/bin/env bash\n# simulate work\nsleep .1\n# generate completion candidates\nprintf \"%s\\n\" \"$*\" | tr \" \" \"\\n\" | sort\n#+end_src\n\nLet's assume this script is callable as =testibus hello world=. To have Consult\nuse it for completion, use =consult--process-collection=:\n\n#+begin_src emacs-lisp\n(consult--read\n (consult--process-collection\n  (lambda (input) (list \"testibus\" (string-trim input))))\n :prompt \"run testibus: \")\n#+end_src\n\nIf the completion candidates are generated by Lisp instead, use\n=consult--dynamic-collection=:\n\n#+begin_src emacs-lisp\n(consult--read\n (consult--dynamic-collection\n  (lambda (input)\n    (sleep-for 0.1) ;; Simulate work\n    (split-string input nil t)))\n :prompt \"run testibus: \")\n#+end_src\n\n=consult--dynamic-collection= can take a function with a callback such that the\ncompletion UI can update for long running computations.\n\n#+begin_src emacs-lisp\n(consult--read\n (consult--dynamic-collection\n  (lambda (input callback)\n    (dotimes (i 3)\n      (sleep-for 0.1) ;; Simulate work\n      (funcall callback (mapcar (lambda (s) (format \"%s%s\" s i))\n                                (split-string input nil t))))))\n :prompt \"run testibus: \")\n#+end_src\n\nThe asynchronous completion collections =consult--dynamic-collection= and\n=consult--process-collection= can be used for =consult--multi= sources. Specify them\nas =:async= field of the source plist.\n\n** Live preview\n\nImplementing live preview requires the definition of a state or preview function\nas defined by =consult--with-preview=. The preview function receives the candidate\nand some action to perform (e.g., ='preview=). In its simplest form supporting\nlive preview, it looks something like this:\n\n#+begin_src emacs-lisp\n(defun testibus--preview (action cand)\n  (pcase action\n    ('preview\n     (with-current-buffer-window \" *testibus*\" 'action nil\n       (erase-buffer)\n       (insert (format \"input: %s\\n\" cand))))))\n#+end_src\n\nSee the docstring of =consult--with-preview= for the lifecycle of the action\nargument. Once defined, we can use this preview function in =consult--read=:\n\n#+begin_src emacs-lisp\n(consult--read\n (consult--dynamic-collection\n  (lambda (input callback)\n    (dotimes (i 3)\n      (sleep-for 0.1) ;; Simulate work\n      (funcall callback (mapcar (lambda (s) (format \"%s%s\" s i))\n                                (split-string input nil t))))))\n :prompt \"run testibus: \"\n :state #'testibus--preview)\n#+end_src\n\n* Contributions\n:properties:\n:description: Feature requests and pull requests\n:end:\n\nConsult is a community effort, please participate in the discussions.\nContributions are welcome, but you may want to discuss potential contributions\nfirst. Since this package is part of [[https://elpa.gnu.org/packages/consult.html][GNU ELPA]] contributions require a copyright\nassignment to the FSF.\n\nIf you have a proposal, take a look at the [[https://github.com/minad/consult/issues][Consult issue tracker]] and the [[https://github.com/minad/consult/issues/6][Consult\nwishlist]]. There have been many prior feature discussions. Please search through\nthe issue tracker, maybe your issue or feature request has already been\ndiscussed. You can contribute to the [[https://github.com/minad/consult/wiki][Consult wiki]], in case you want to share\nsmall configuration or command snippets.\n\n* Acknowledgments\n:properties:\n:description: Contributors and Sources of Inspiration\n:end:\n\nThis package took inspiration from [[https://github.com/abo-abo/swiper#counsel][Counsel]] by Oleh Krehel. Some of the Consult\ncommands originated in the Counsel package or the wiki of the Selectrum package.\nThis package exists only thanks to the help of these great contributors and\nthanks to the feedback of many users. Thank you!\n\nCode contributions: [[https://github.com/aagon][Aymeric Agon-Rambosson]], [[https://github.com/amosbird][Amos Bird]], [[https://github.com/ashton314][Ashton Wiersdorf]], [[https://github.com/aspiers/][Adam\nSpiers]], [[https://github.com/astoff][Augusto Stoffel]], [[https://github.com/clemera/][Clemens Radermacher]], [[https://github.com/fuzy112][Zhengyi]], [[https://github.com/geolessel][Geoffrey Lessel]], [[https://github.com/iostapyshyn][Illia\nOstapyshyn]], [[https://github.com/jakanakaevangeli][jakanakaevangeli]], [[https://github.com/jdtsmith][JD Smith]], [[https://github.com/jyp][Jean-Philippe Bernardy]], [[https://github.com/mattiasdrp][mattiasdrp]],\n[[https://github.com/mohamed-abdelnour][Mohamed Abdelnour]], [[https://github.com/mohkale][Mohsin Kaleem]], [[https://github.com/noctuid][Fox Kiester]], [[https://github.com/oantolin/][Omar Antolín Camarena]], [[https://github.com/okamsn/][Earl\nHyatt]], [[https://github.com/omar-polo][Omar Polo]], [[https://github.com/piotrkwiecinski][Piotr Kwiecinski]], [[https://github.com/rswgnu][Robert Weiner]], [[https://github.com/s-kostyaev/][Sergey Kostyaev]], [[https://github.com/scvalex][Alexandru\nScvorțov]], [[https://github.com/tecosaur][Tecosaur]], [[https://github.com/thisirs][Sylvain Rousseau]], [[https://github.com/tomfitzhenry/][Tom Fitzhenry]], [[https://hg.serna.eu][Iñigo Serna]] and [[https://github.com/akreisher][Alex\nKreisher]].\n\nAdvice and useful discussions: [[https://github.com/Qkessler][Enrique Kessler Martínez]], [[https://github.com/alphapapa/][Adam Porter]], [[https://github.com/bdarcus][Bruce\nd'Arcus]], [[https://github.com/clemera/][Clemens Radermacher]], [[https://github.com/dgutov/][Dmitry Gutov]], [[https://github.com/hmelman/][Howard Melman]], [[https://github.com/iyefrat][Itai Y. Efrat]], [[https://github.com/jdtsmith][JD\nSmith]], [[https://github.com/manuel-uberti/][Manuel Uberti]], [[https://github.com/monnier/][Stefan Monnier]], [[https://github.com/oantolin/][Omar Antolín Camarena]], [[https://github.com/purcell/][Steve Purcell]],\n[[https://github.com/raxod502][Radon Rosborough]], [[https://github.com/tomfitzhenry/][Tom Fitzhenry]] and [[https://protesilaos.com][Protesilaos Stavrou]].\n\n#+html: \u003c!--\n\n* Indices\n:properties:\n:description: Indices of concepts and functions\n:end:\n\n** Function index\n:properties:\n:description: List of all Consult commands\n:index:    fn\n:end:\n\n** Concept index\n:properties:\n:description: List of all Consult-specific concepts\n:index:    cp\n:end:\n\n#+html: --\u003e\n","funding_links":["https://github.com/sponsors/minad","https://liberapay.com/minad","https://www.paypal.me/danielmendler"],"categories":["Emacs Lisp"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminad%2Fconsult","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminad%2Fconsult","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminad%2Fconsult/lists"}