README-elpa (65323B)
1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2 CONSULT.EL - CONSULTING COMPLETING-READ 3 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4 5 6 Consult provides search and navigation commands based on the Emacs 7 completion function [completing-read]. Completion allows you to quickly 8 select an item from a list of candidates. Consult offers asynchronous 9 and interactive `consult-grep' and `consult-ripgrep' commands, and the 10 line-based search command `consult-line'. Furthermore Consult provides 11 an advanced buffer switching command `consult-buffer' to switch between 12 buffers, recently opened files, bookmarks and buffer-like candidates 13 from other sources. Some of the Consult commands are enhanced versions 14 of built-in Emacs commands. For example the command `consult-imenu' 15 presents a flat list of the Imenu with [live preview], [grouping and 16 narrowing]. Please take a look at the [full list of commands]. 17 18 Consult is fully compatible with completion systems centered around the 19 standard Emacs `completing-read' API, notably the default completion 20 system, [Vertico], [Mct], and [Icomplete]. 21 22 This package keeps the completion system specifics to a minimum. The 23 ability of the Consult commands to work well with arbitrary completion 24 systems is one of the main advantages of the package. Consult fits well 25 into existing setups and it helps you to create a full completion 26 environment out of small and independent components. 27 28 You can combine the complementary packages [Marginalia], [Embark] and 29 [Orderless] with Consult. Marginalia enriches the completion display 30 with annotations, e.g., documentation strings or file information. The 31 versatile Embark package provides local actions, comparable to a context 32 menu. These actions operate on the selected candidate in the minibuffer 33 or at point in normal buffers. For example, when selecting from a list 34 of files, Embark offers an action to delete the file. Additionally 35 Embark offers a facility to collect completion candidates in a collect 36 buffer. The section [Embark integration] documents in greater detail how 37 Consult and Embark work together. 38 39 Table of Contents 40 ───────────────── 41 42 1. Available commands 43 .. 1. Virtual Buffers 44 .. 2. Editing 45 .. 3. Register 46 .. 4. Navigation 47 .. 5. Search 48 .. 6. Grep and Find 49 .. 7. Compilation 50 .. 8. Histories 51 .. 9. Modes 52 .. 10. Org Mode 53 .. 11. Miscellaneous 54 2. Special features 55 .. 1. Live previews 56 .. 2. Narrowing and grouping 57 .. 3. Asynchronous search 58 .. 4. Multiple sources 59 .. 5. Embark integration 60 3. Configuration 61 .. 1. Use-package example 62 .. 2. Custom variables 63 .. 3. Fine-tuning 64 4. Recommended packages 65 5. Auxiliary packages 66 6. Bug reports 67 7. Contributions 68 8. Acknowledgments 69 9. Indices 70 .. 1. Function index 71 .. 2. Concept index 72 73 74 [completing-read] 75 <https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html> 76 77 [live preview] See section 2.1 78 79 [grouping and narrowing] See section 2.2 80 81 [full list of commands] See section 1 82 83 [Vertico] <https://github.com/minad/vertico> 84 85 [Mct] <https://github.com/protesilaos/mct> 86 87 [Icomplete] 88 <https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html> 89 90 [Marginalia] <https://github.com/minad/marginalia/> 91 92 [Embark] <https://github.com/oantolin/embark/> 93 94 [Orderless] <https://github.com/oantolin/orderless> 95 96 [Embark integration] See section 2.5 97 98 99 1 Available commands 100 ════════════════════ 101 102 Most Consult commands follow the meaningful naming scheme 103 `consult-<thing>'. Many commands implement a little known but 104 convenient Emacs feature called "future history", which guesses what 105 input the user wants. At a command prompt type `M-n' and typically 106 Consult will insert the symbol or thing at point into the input. 107 108 *TIP:* If you have [Marginalia] annotators activated, type `M-x 109 ^consult' to see all Consult commands with their abbreviated 110 description. Alternatively, type `C-h a ^consult' to get an overview 111 of all Consult variables and functions with their descriptions. 112 113 114 [Marginalia] <https://github.com/minad/marginalia> 115 116 1.1 Virtual Buffers 117 ─────────────────── 118 119 • `consult-buffer' (`-other-window', `-other-frame'): Enhanced version 120 of `switch-to-buffer' with support for virtual buffers. Supports 121 live preview of buffers and narrowing to the virtual buffer 122 types. You can type `f SPC' in order to narrow to recent 123 files. Press `SPC' to show ephemeral buffers. Supported narrowing 124 keys: 125 • b Buffers 126 • SPC Hidden buffers 127 • * Modified buffers 128 • f Files (Requires `recentf-mode') 129 • r File registers 130 • m Bookmarks 131 • p Project 132 • Custom [other sources] configured in `consult-buffer-sources'. 133 • `consult-project-buffer': Variant of `consult-buffer' restricted to 134 buffers and recent files of the current project. You can add custom 135 sources to `consult-project-buffer-sources'. The command may prompt 136 you for a project if you invoke it from outside a project. 137 • `consult-bookmark': Select or create bookmark. To select bookmarks 138 you might use the `consult-buffer' as an alternative, which can 139 include a bookmark virtual buffer source. Note that 140 `consult-bookmark' supports preview of bookmarks and narrowing. 141 • `consult-recent-file': Select from recent files with preview. You 142 might prefer the powerful `consult-buffer' instead, which can 143 include recent files as a virtual buffer source. The `recentf-mode' 144 enables tracking of recent files. 145 146 147 [other sources] See section 2.4 148 149 150 1.2 Editing 151 ─────────── 152 153 • `consult-yank-from-kill-ring': Enhanced version of `yank' to select 154 an item from the `kill-ring'. The selected text previewed as overlay 155 in the buffer. 156 • `consult-yank-pop': Enhanced version of `yank-pop' with 157 DWIM-behavior, which either replaces the last `yank' by cycling 158 through the `kill-ring', or if there has not been a last `yank' 159 consults the `kill-ring'. The selected text previewed as overlay in 160 the buffer. 161 • `consult-yank-replace': Like `consult-yank-pop', but always replaces 162 the last `yank' with an item from the `kill-ring'. 163 • `consult-kmacro': Select macro from the macro ring and execute it. 164 165 166 1.3 Register 167 ──────────── 168 169 • `consult-register': Select from list of registers. The command 170 supports narrowing to register types and preview of marker 171 positions. This command is useful to search the register 172 contents. For quick access use the commands `consult-register-load', 173 `consult-register-store' or the built-in Emacs register commands. 174 • `consult-register-format': Set `register-preview-function' to this 175 function for an enhanced register formatting. See the [example 176 configuration]. 177 • `consult-register-window': Replace `register-preview' with this 178 function for a better register window. See the [example 179 configuration]. 180 • `consult-register-load': Utility command to quickly load a register. 181 The command either jumps to the register value or inserts it. 182 • `consult-register-store': Improved UI to store registers depending 183 on the current context with an action menu. With an active region, 184 store/append/prepend the contents, optionally deleting the region 185 when a prefix argument is given. With a numeric prefix argument, 186 store/add the number. Otherwise store point, frameset, window or 187 kmacro. Usage examples: 188 ‣ `M-' x': If no region is active, store point in register `x'. If 189 a region is active, store the region in register `x'. 190 ‣ `M-' M-w x': Store window configuration in register `x'. 191 ‣ `C-u 100 M-' x': Store number in register `x'. 192 193 194 [example configuration] See section 3.1 195 196 197 1.4 Navigation 198 ────────────── 199 200 • `consult-goto-line': Jump to line number enhanced with live preview. 201 This is a drop-in replacement for `goto-line'. 202 • `consult-mark': Jump to a marker in the `mark-ring'. Supports live 203 preview and recursive editing. 204 • `consult-global-mark': Jump to a marker in the `global-mark-ring'. 205 Supports live preview and recursive editing. 206 • `consult-outline': Jump to a heading of the outline. Supports 207 narrowing to a heading level, live preview and recursive editing. 208 • `consult-imenu': Jump to imenu item in the current buffer. Supports 209 live preview, recursive editing and narrowing. 210 • `consult-imenu-multi': Jump to imenu item in project buffers, with 211 the same major mode as the current buffer. Supports live preview, 212 recursive editing and narrowing. This feature has been inspired by 213 [imenu-anywhere]. 214 215 216 [imenu-anywhere] <https://github.com/vspinu/imenu-anywhere> 217 218 219 1.5 Search 220 ────────── 221 222 • `consult-line': Enter search string and select from matching lines. 223 Supports live preview and recursive editing. The symbol at point and 224 the recent Isearch string are added to the "future history" and can 225 be accessed by pressing `M-n'. When `consult-line' is bound to the 226 `isearch-mode-map' and is invoked during a running Isearch, it will 227 use the current Isearch string. 228 • `consult-line-multi': Search dynamically across multiple buffers. By 229 default search across project buffers. If invoked with a prefix 230 argument search across all buffers. The candidates are computed on 231 demand based on the input. The command behaves like `consult-grep', 232 but operates on buffers instead of files. 233 • `consult-keep-lines': Replacement for `keep/flush-lines' which uses 234 the current completion style for filtering the buffer. The function 235 updates the buffer while typing. In particular `consult-keep-lines' 236 can narrow down an exported Embark collect buffer further, relying 237 on the same completion filtering as `completing-read'. If the input 238 begins with the negation operator, i.e., `! SPC', the filter matches 239 the complement. If a region is active, the region restricts the 240 filtering. 241 • `consult-focus-lines': Temporarily hide lines by filtering them 242 using the current completion style. Call with `C-u' prefix argument 243 in order to show the hidden lines again. If the input begins with 244 the negation operator, i.e., `! SPC', the filter matches the 245 complement. In contrast to `consult-keep-lines' this function does 246 not edit the buffer. If a region is active, the region restricts the 247 filtering. 248 249 250 1.6 Grep and Find 251 ───────────────── 252 253 • `consult-grep', `consult-ripgrep', `consult-git-grep': Search for 254 regular expression in files. Consult invokes Grep asynchronously, 255 while you enter the search term. After at least 256 `consult-async-min-input' characters, the search gets 257 started. Consult splits the input string into two parts, if the 258 first character is a punctuation character, like `#'. For example 259 `#regexps#filter-string', is split at the second `#'. The string 260 `regexps' is passed to Grep. Note that Consult transforms Emacs 261 regular expressions to expressions understand by the search 262 program. Always use Emacs regular expressions at the prompt. If you 263 enter multiple regular expressions separated by space only lines 264 matching all regular expressions are shown. In order to match space 265 literally, escape the space with a backslash. The `filter-string' is 266 passed to the /fast/ Emacs filtering to further narrow down the list 267 of matches. This is particularly useful if you are using an advanced 268 completion style like orderless. `consult-grep' supports preview. If 269 the `consult-project-function' returns non-nil, `consult-grep' 270 searches the current project directory. Otherwise the 271 `default-directory' is searched. If `consult-grep' is invoked with 272 prefix argument `C-u M-s g', you can specify the directory manually. 273 • `consult-find', `consult-locate': Find file by matching the path 274 against a regexp. Like for `consult-grep', either the project root 275 or the current directory is the root directory for the search. The 276 input string is treated similarly to `consult-grep', where the first 277 part is passed to find, and the second part is used for Emacs 278 filtering. 279 280 281 1.7 Compilation 282 ─────────────── 283 284 • `consult-compile-error': Jump to a compilation error. Supports live 285 preview narrowing and recursive editing. 286 • `consult-flymake': Jump to flymake diagnostic. Supports live preview 287 and recursive editing. The command supports narrowing. Press `e 288 SPC', `w SPC', `n SPC' to only show errors, warnings and notes 289 respectively. 290 • `consult-xref': Integration with xref. This function can be set as 291 `xref-show-xrefs-function' and `xref-show-definitions-function'. 292 293 294 1.8 Histories 295 ───────────── 296 297 • `consult-complex-command': Select a command from the 298 `command-history'. This command is a `completing-read' version of 299 `repeat-complex-command' and is also a replacement for the 300 `command-history' command from chistory.el. 301 • `consult-history': Insert a string from the current buffer history, 302 for example the Eshell or Comint history. You can also invoke this 303 command from the minibuffer. In that case `consult-history' uses the 304 history stored in the `minibuffer-history-variable'. If you prefer 305 `completion-at-point', take a look at `cape-history' from the [Cape] 306 package. 307 • `consult-isearch-history': During an Isearch session, this command 308 picks a search string from history and continues the search with the 309 newly selected string. Outside of Isearch, the command allows you to 310 pick a string from the history and starts a new 311 Isearch. `consult-isearch-history' acts as a drop-in replacement for 312 `isearch-edit-string'. 313 314 315 [Cape] <https://github.com/minad/cape> 316 317 318 1.9 Modes 319 ───────── 320 321 • `consult-minor-mode-menu': Enable/disable minor mode. Supports 322 narrowing to on/off/local/global modes by pressing `i/o/l/g SPC' 323 respectively. 324 • `consult-mode-command': Run a command from the currently active 325 minor or major modes. Supports narrowing to 326 local-minor/global-minor/major mode via the keys `l/g/m'. 327 328 329 1.10 Org Mode 330 ───────────── 331 332 • `consult-org-heading': Similar to `consult-outline', for Org 333 buffers. Supports narrowing by heading level, priority and TODO 334 state, as well as live preview and recursive editing. 335 • `consult-org-agenda': Jump to an agenda heading. Supports narrowing 336 by heading level, priority and TODO state, as well as live preview 337 and recursive editing. 338 339 340 1.11 Miscellaneous 341 ────────────────── 342 343 • `consult-man': Find Unix man page, via Unix `apropos' or `man 344 -k'. `consult-man' opens the selected man page using the Emacs `man' 345 command. 346 • `consult-theme': Select a theme and disable all currently enabled 347 themes. Supports live preview of the theme while scrolling through 348 the candidates. 349 • `consult-preview-at-point' and `consult-preview-at-point-mode': 350 Command and minor mode which previews the candidate at point in the 351 `*Completions*' buffer. This mode is relevant if you use [Mct] or 352 the default `*Completions*' UI. 353 • `consult-completion-in-region': In case you don't use [Corfu] as 354 your in-buffer completion UI, this function can be set as 355 `completion-in-region-function'. Then your minibuffer completion UI 356 (e.g., Vertico or Icomplete) will be used for 357 `completion-at-point'. If you use Mct, you can give 358 `mct-region-mode' a try. 359 ┌──── 360 │ ;; Use `consult-completion-in-region' if Vertico is enabled. 361 │ ;; Otherwise use the default `completion--in-region' function. 362 │ (setq completion-in-region-function 363 │ (lambda (&rest args) 364 │ (apply (if vertico-mode 365 │ #'consult-completion-in-region 366 │ #'completion--in-region) 367 │ args))) 368 └──── 369 Instead of `consult-completion-in-region', you may prefer to see the 370 completions directly in the buffer as a small popup. In that case, I 371 recommend either the [Corfu] or the [Company] package. There is a 372 technical limitation of `consult-completion-in-region' in 373 combination with Lsp-mode or Eglot. The Lsp server relies on the 374 input at point, in order to generate refined candidate 375 strings. Since the completion is transferred from the original 376 buffer to the minibuffer, the server does not receive the updated 377 input. LSP completion works with Corfu or Company though, which 378 perform the completion directly in the original buffer. 379 380 381 [Mct] <https://git.sr.ht/~protesilaos/mct> 382 383 [Corfu] <https://github.com/minad/corfu> 384 385 [Company] <https://github.com/company-mode/company-mode> 386 387 388 2 Special features 389 ══════════════════ 390 391 Consult enhances `completing-read' with live previews of candidates, 392 additional narrowing capabilities to candidate groups and 393 asynchronously generated candidate lists. The internal `consult--read' 394 function, which is used by most Consult commands, is a thin wrapper 395 around `completing-read' and provides the special functionality. In 396 order to support multiple candidate sources there exists the 397 high-level function `consult--multi'. The architecture of Consult 398 allows it to work with different completion systems in the backend, 399 while still offering advanced features. 400 401 402 2.1 Live previews 403 ───────────────── 404 405 Some Consult commands support live previews. For example when you 406 scroll through the items of `consult-line', the buffer will scroll to 407 the corresponding position. It is possible to jump back and forth 408 between the minibuffer and the buffer to perform recursive editing 409 while the search is ongoing. 410 411 Consult enables previews by default. You can disable them by adjusting 412 the `consult-preview-key' variable. Furthermore it is possible to 413 specify keybindings which trigger the preview manually as shown in the 414 [example configuration]. The default setting of `consult-preview-key' 415 is `any' which means that Consult triggers the preview /immediately/ 416 on any key press when the selected candidate changes. You can 417 configure each command individually with its own `:preview-key'. The 418 following settings are possible: 419 420 • Automatic and immediate `'any' 421 • Automatic and delayed `(list :debounce 0.5 'any)' 422 • Manual and immediate `(kbd "M-.")' 423 • Manual and delayed `(list :debounce 0.5 (kbd "M-."))' 424 • Disabled `nil' 425 426 A safe recommendation is to leave automatic immediate previews enabled 427 in general and disable the automatic preview only for commands where 428 the preview may be expensive due to file loading. Internally, Consult 429 uses the value of `this-command' to determine the `:preview-key' 430 customized. This means that if you wrap a `consult-*' command within 431 your own function or command, you will also need to add the name of 432 /your custom command/ to the `consult-customize' call in order for it 433 to be considered. 434 435 ┌──── 436 │ (consult-customize 437 │ consult-ripgrep consult-git-grep consult-grep 438 │ consult-bookmark consult-recent-file consult-xref 439 │ consult--source-bookmark consult--source-file-register 440 │ consult--source-recent-file consult--source-project-recent-file 441 │ ;; my/command-wrapping-consult ;; disable auto previews inside my command 442 │ :preview-key '(:debounce 0.4 any) ;; Option 1: Delay preview 443 │ ;; :preview-key (kbd "M-.")) ;; Option 2: Manual preview 444 └──── 445 446 In this case one may wonder what the difference is between using an 447 Embark action on the current candidate in comparison to a manually 448 triggered preview. The main difference is that the files opened by 449 manual preview are closed again after the completion 450 session. Furthermore during preview some functionality is disabled to 451 improve the performance, see for example the customization variables 452 `consult-preview-allowed-hooks' and `consult-preview-variables'. Files 453 larger than `consult-preview-raw-size' are previewed literally without 454 syntax highlighting and without changing the major mode. Delaying the 455 preview is also useful for `consult-theme', since the theme preview is 456 slow. The delay results in a smoother UI experience. 457 458 ┌──── 459 │ ;; Preview on any key press, but delay 0.5s 460 │ (consult-customize consult-theme :preview-key '(:debounce 0.5 any)) 461 │ ;; Preview immediately on M-., on up/down after 0.5s, on any other key after 1s 462 │ (consult-customize consult-theme 463 │ :preview-key 464 │ (list (kbd "M-.") 465 │ :debounce 0.5 (kbd "<up>") (kbd "<down>") 466 │ :debounce 1 'any)) 467 └──── 468 469 470 [example configuration] See section 3.1 471 472 473 2.2 Narrowing and grouping 474 ────────────────────────── 475 476 Consult has special support for candidate groups. If the completion UI 477 supports the grouping functionality, the UI separates the groups with 478 thin lines and shows group titles. Grouping is useful if the list of 479 candidates consists of candidates of multiple types or candidates from 480 [multiple sources], like the `consult-buffer' command, which shows 481 both buffers and recently opened files. Note that you can disable the 482 group titles by setting the `:group' property of the corresponding 483 command to nil using the `consult-customize' macro. 484 485 By entering a narrowing prefix or by pressing a narrowing key it is 486 possible to restrict the completion candidates to a certain candidate 487 group. When you use the `consult-buffer' command, you can enter the 488 prefix `b SPC' to restrict list of candidates to buffers only. If you 489 press `DEL' afterwards, the full candidate list will be shown 490 again. Furthermore a narrowing prefix key and a widening key can be 491 configured which can be pressed to achieve the same effect, see the 492 configuration variables `consult-narrow-key' and `consult-widen-key'. 493 494 After pressing `consult-narrow-key', the possible narrowing keys can 495 be shown by pressing `C-h'. When pressing `C-h' after some prefix key, 496 the `prefix-help-command' is invoked, which shows the keybinding help 497 window by default. As a more compact alternative, there is the 498 `consult-narrow-help' command which can be bound to a key, for example 499 `?' or `C-h' in the `consult-narrow-map', as shown in the [example 500 configuration]. If [which-key] is installed, the narrowing keys are 501 automatically shown in the which-key window after pressing the 502 `consult-narrow-key'. 503 504 505 [multiple sources] See section 2.4 506 507 [example configuration] See section 3.1 508 509 [which-key] <https://github.com/justbur/emacs-which-key> 510 511 512 2.3 Asynchronous search 513 ─────────────────────── 514 515 Consult has support for asynchronous generation of candidate 516 lists. This feature is used for search commands like `consult-grep', 517 where the list of matches is generated dynamically while the user is 518 typing a regular expression. The grep process is executed in the 519 background. When modifying the regular expression, the background 520 process is terminated and a new process is started with the modified 521 regular expression. 522 523 The matches, which have been found, can then be narrowed using the 524 installed Emacs completion-style. This can be powerful if you are 525 using for example the `orderless' completion style. 526 527 This two-level filtering is possible by splitting the input 528 string. Part of the input string is treated as input to grep and part 529 of the input is used for filtering. There are multiple splitting 530 styles available, configured in `consult-async-split-styles-alist': 531 `nil', `comma', `semicolon' and `perl'. The default splitting style is 532 configured with the variable `consult-async-split-style'. 533 534 With the `comma' and `semicolon' splitting styles, the first word 535 before the comma or semicolon is passed to grep, the remaining string 536 is used for filtering. The `nil' splitting style does not perform any 537 splitting, the whole input is passed to grep. 538 539 The `perl' splitting style splits the input string at a punctuation 540 character, using a similar syntax as Perl regular expressions. 541 542 Examples: 543 544 • `#defun': Search for "defun" using grep. 545 • `#consult embark': Search for both "consult" and "embark" using grep 546 in any order. 547 • `#first.*second': Search for "first" followed by "second" using 548 grep. 549 • `#\(consult\|embark\)': Search for "consult" or "embark" using 550 grep. Note the usage of Emacs-style regular expressions. 551 • `#defun#consult': Search for "defun" using grep, filter with the 552 word "consult". 553 • `/defun/consult': It is also possible to use other punctuation 554 characters. 555 • `#to#': Force searching for "to" using grep, since the grep pattern 556 must be longer than `consult-async-min-input' characters by default. 557 • `#defun -- --invert-match#': Pass argument `--invert-match' to grep. 558 559 Asynchronous processes like `find' and `grep' create an error log 560 buffer `_*consult-async*' (note the leading space), which is useful 561 for troubleshooting. The prompt has a small indicator showing the 562 process status: 563 564 • `:' the usual prompt colon, before input is provided. 565 • `*' with warning face, the process is running. 566 • `:' with success face, success, process exited with an error code of 567 zero. 568 • `!' with error face, failure, process exited with a nonzero error 569 code. 570 • `;' with error face, interrupted, for example if more input is 571 provided. 572 573 574 2.4 Multiple sources 575 ──────────────────── 576 577 Multiple synchronous candidate sources can be combined. This feature 578 is used by the `consult-buffer' command to present buffer-like 579 candidates in a single menu for quick access. By default 580 `consult-buffer' includes buffers, bookmarks, recent files and 581 project-specific buffers and files. It is possible to configure the 582 list of sources via the `consult-buffer-sources' variable. Arbitrary 583 custom sources can be defined. 584 585 As an example, the bookmark source is defined as follows: 586 587 ┌──── 588 │ (defvar consult--source-bookmark 589 │ `(:name "Bookmark" 590 │ :narrow ?m 591 │ :category bookmark 592 │ :face consult-bookmark 593 │ :history bookmark-history 594 │ :items ,#'bookmark-all-names 595 │ :action ,#'consult--bookmark-action)) 596 └──── 597 598 Required source fields: 599 • `:category' Completion category. 600 • `:items' List of strings to select from or function returning list 601 of strings. A list of cons cells is not supported. 602 603 Optional source fields: 604 • `:name' Name of the source, used for narrowing, group titles and 605 annotations. 606 • `:narrow' Narrowing character or `(character . string)' pair. 607 • `:preview-key' Preview key or keys which trigger preview. 608 • `:enabled' Function which must return t if the source is enabled. 609 • `:hidden' When t candidates of this source are hidden by default. 610 • `:face' Face used for highlighting the candidates. 611 • `:annotate' Annotation function called for each candidate, returns 612 string. 613 • `:history' Name of history variable to add selected candidate. 614 • `:default' Must be t if the first item of the source is the default 615 value. 616 • `:action' Function called with the selected candidate. 617 • `:new' Function called with new candidate name, only if 618 `:require-match' is nil. 619 • `:state' State constructor for the source, must return the state 620 function. 621 • Other source fields can be added specifically to the use case. 622 623 The `:state' and `:action' fields of the sources deserve a longer 624 explanation. The `:action' function takes a single argument and is 625 only called after selection with the selected candidate, if the 626 selection has not been aborted. This functionality is provided for 627 convenience and easy definition of sources. The `:state' field is more 628 general. The `:state' function is a constructor function without 629 arguments, which can perform some setup necessary for the preview. It 630 must return a closure which takes an ACTION and a CANDIDATE 631 argument. See the docstring of `consult--with-preview' for more 632 details about the ACTION argument. 633 634 By default, `consult-buffer' previews buffers, bookmarks and 635 files. Loading recent files or bookmarks can result in expensive 636 operations. However it is possible to configure a manual preview as 637 follows. 638 639 ┌──── 640 │ (consult-customize 641 │ consult--source-bookmark consult--source-file-register 642 │ consult--source-recent-file consult--source-project-recent-file 643 │ :preview-key (kbd "M-.")) 644 └──── 645 646 Sources can be added directly to the `consult-buffer-source' list for 647 convenience. For example views/perspectives can be added to the list 648 of virtual buffers from a library like [bookmark-view]. 649 650 ┌──── 651 │ ;; Configure new bookmark-view source 652 │ (add-to-list 'consult-buffer-sources 653 │ (list :name "View" 654 │ :narrow ?v 655 │ :category 'bookmark 656 │ :face 'font-lock-keyword-face 657 │ :history 'bookmark-view-history 658 │ :action #'consult--bookmark-action 659 │ :items #'bookmark-view-names) 660 │ 'append) 661 │ 662 │ ;; Modify bookmark source, such that views are hidden 663 │ (setq consult--source-bookmark 664 │ (plist-put 665 │ consult--source-bookmark :items 666 │ (lambda () 667 │ (bookmark-maybe-load-default-file) 668 │ (mapcar #'car 669 │ (seq-remove (lambda (x) 670 │ (eq #'bookmark-view-handler 671 │ (alist-get 'handler (cdr x)))) 672 │ bookmark-alist))))) 673 └──── 674 675 Another useful source lists all Org buffers and lets you create new 676 ones. One can create similar sources for other major modes, e.g., for 677 Eshell. 678 679 ┌──── 680 │ (defvar org-source 681 │ (list :name "Org Buffer" 682 │ :category 'buffer 683 │ :narrow ?o 684 │ :face 'consult-buffer 685 │ :history 'buffer-name-history 686 │ :state #'consult--buffer-state 687 │ :new 688 │ (lambda (name) 689 │ (with-current-buffer (get-buffer-create name) 690 │ (insert "#+title: " name "\n\n") 691 │ (org-mode) 692 │ (consult--buffer-action (current-buffer)))) 693 │ :items 694 │ (lambda () 695 │ (mapcar #'buffer-name 696 │ (seq-filter 697 │ (lambda (x) 698 │ (eq (buffer-local-value 'major-mode x) 'org-mode)) 699 │ (buffer-list)))))) 700 │ 701 │ (add-to-list 'consult-buffer-sources 'org-source 'append) 702 └──── 703 704 For more details, see the documentation of `consult-buffer' and of the 705 internal `consult--multi' API. The `consult--multi' function can be 706 used to create new multi-source commands, but is part of the internal 707 API as of now, since some details may still change. 708 709 710 [bookmark-view] <https://github.com/minad/bookmark-view/> 711 712 713 2.5 Embark integration 714 ────────────────────── 715 716 *NOTE*: Install the `embark-consult' package from MELPA, which 717 provides Consult-specific Embark actions and the Occur buffer export. 718 719 Embark is a versatile package which offers context dependent actions, 720 comparable to a context menu. See the [Embark manual] for an extensive 721 description of its capabilities. 722 723 Actions are commands which can operate on the currently selected 724 candidate (or target in Embark terminology). When completing files, 725 for example the `delete-file' command is offered. With Embark you can 726 execute arbitrary commands on the currently selected candidate via 727 `M-x'. 728 729 Furthermore Embark provides the `embark-collect' command, which 730 collects candidates and presents them in an Embark collect buffer, 731 where further actions can be applied to them. A related feature is the 732 `embark-export' command, which exports candidate lists to a buffer of 733 a special type. For example in the case of file completion, a Dired 734 buffer is opened. 735 736 In the context of Consult, particularly exciting is the possibility to 737 export the matching lines from `consult-line', `consult-outline', 738 `consult-mark' and `consult-global-mark'. The matching lines are 739 exported to an Occur buffer where they can be edited via the 740 `occur-edit-mode' (press key `e'). Similarly, Embark supports 741 exporting the matches found by `consult-grep', `consult-ripgrep' and 742 `consult-git-grep' to a Grep buffer, where the matches across files 743 can be edited, if the [wgrep] package is installed. These three 744 workflows are symmetric. 745 746 ⁃ `consult-line' -> `embark-export' to `occur-mode' buffer -> 747 `occur-edit-mode' for editing of matches in buffer. 748 ⁃ `consult-grep' -> `embark-export' to `grep-mode' buffer -> `wgrep' 749 for editing of all matches. 750 ⁃ `consult-find' -> `embark-export' to `dired-mode' buffer -> 751 `wdired-change-to-wdired-mode' for editing. 752 753 754 [Embark manual] <https://github.com/oantolin/embark> 755 756 [wgrep] <https://github.com/mhayashi1120/Emacs-wgrep> 757 758 759 3 Configuration 760 ═══════════════ 761 762 Consult can be installed from [ELPA] or [MELPA] via the Emacs built-in 763 package manager. Alternatively it can be directly installed from the 764 development repository via other non-standard package managers. 765 766 There is the [Consult wiki], where additional configuration examples 767 can be contributed. 768 769 *IMPORTANT:* It is strongly recommended that you enable [lexical 770 binding] in your configuration. Consult relies on lambdas and lexical 771 closures. For this reason many Consult-related snippets require 772 lexical binding. 773 774 775 [ELPA] <https://elpa.gnu.org/packages/consult.html> 776 777 [MELPA] <https://melpa.org/#/consult> 778 779 [Consult wiki] <https://github.com/minad/consult/wiki> 780 781 [lexical binding] 782 <https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html> 783 784 3.1 Use-package example 785 ─────────────────────── 786 787 The Consult package only provides commands and does not add any 788 keybindings or modes. Therefore the package is non-intrusive but 789 requires a little setup effort. In order to use the Consult commands, 790 it is advised to add keybindings for commands which are accessed 791 often. Rarely used commands can be invoked via `M-x'. Feel free to 792 only bind the commands you consider useful to your workflow. The 793 configuration shown here relies on the `use-package' macro, which is a 794 convenient tool to manage package configurations. 795 796 *NOTE:* There is the [Consult wiki], where you can contribute 797 additional configuration examples. 798 799 ┌──── 800 │ ;; Example configuration for Consult 801 │ (use-package consult 802 │ ;; Replace bindings. Lazily loaded due by `use-package'. 803 │ :bind (;; C-c bindings (mode-specific-map) 804 │ ("C-c h" . consult-history) 805 │ ("C-c m" . consult-mode-command) 806 │ ("C-c k" . consult-kmacro) 807 │ ;; C-x bindings (ctl-x-map) 808 │ ("C-x M-:" . consult-complex-command) ;; orig. repeat-complex-command 809 │ ("C-x b" . consult-buffer) ;; orig. switch-to-buffer 810 │ ("C-x 4 b" . consult-buffer-other-window) ;; orig. switch-to-buffer-other-window 811 │ ("C-x 5 b" . consult-buffer-other-frame) ;; orig. switch-to-buffer-other-frame 812 │ ("C-x r b" . consult-bookmark) ;; orig. bookmark-jump 813 │ ("C-x p b" . consult-project-buffer) ;; orig. project-switch-to-buffer 814 │ ;; Custom M-# bindings for fast register access 815 │ ("M-#" . consult-register-load) 816 │ ("M-'" . consult-register-store) ;; orig. abbrev-prefix-mark (unrelated) 817 │ ("C-M-#" . consult-register) 818 │ ;; Other custom bindings 819 │ ("M-y" . consult-yank-pop) ;; orig. yank-pop 820 │ ;; M-g bindings (goto-map) 821 │ ("M-g e" . consult-compile-error) 822 │ ("M-g f" . consult-flymake) ;; Alternative: consult-flycheck 823 │ ("M-g g" . consult-goto-line) ;; orig. goto-line 824 │ ("M-g M-g" . consult-goto-line) ;; orig. goto-line 825 │ ("M-g o" . consult-outline) ;; Alternative: consult-org-heading 826 │ ("M-g m" . consult-mark) 827 │ ("M-g k" . consult-global-mark) 828 │ ("M-g i" . consult-imenu) 829 │ ("M-g I" . consult-imenu-multi) 830 │ ;; M-s bindings (search-map) 831 │ ("M-s d" . consult-find) 832 │ ("M-s D" . consult-locate) 833 │ ("M-s g" . consult-grep) 834 │ ("M-s G" . consult-git-grep) 835 │ ("M-s r" . consult-ripgrep) 836 │ ("M-s l" . consult-line) 837 │ ("M-s L" . consult-line-multi) 838 │ ("M-s k" . consult-keep-lines) 839 │ ("M-s u" . consult-focus-lines) 840 │ ;; Isearch integration 841 │ ("M-s e" . consult-isearch-history) 842 │ :map isearch-mode-map 843 │ ("M-e" . consult-isearch-history) ;; orig. isearch-edit-string 844 │ ("M-s e" . consult-isearch-history) ;; orig. isearch-edit-string 845 │ ("M-s l" . consult-line) ;; needed by consult-line to detect isearch 846 │ ("M-s L" . consult-line-multi) ;; needed by consult-line to detect isearch 847 │ ;; Minibuffer history 848 │ :map minibuffer-local-map 849 │ ("M-s" . consult-history) ;; orig. next-matching-history-element 850 │ ("M-r" . consult-history)) ;; orig. previous-matching-history-element 851 │ 852 │ ;; Enable automatic preview at point in the *Completions* buffer. This is 853 │ ;; relevant when you use the default completion UI. 854 │ :hook (completion-list-mode . consult-preview-at-point-mode) 855 │ 856 │ ;; The :init configuration is always executed (Not lazy) 857 │ :init 858 │ 859 │ ;; Optionally configure the register formatting. This improves the register 860 │ ;; preview for `consult-register', `consult-register-load', 861 │ ;; `consult-register-store' and the Emacs built-ins. 862 │ (setq register-preview-delay 0.5 863 │ register-preview-function #'consult-register-format) 864 │ 865 │ ;; Optionally tweak the register preview window. 866 │ ;; This adds thin lines, sorting and hides the mode line of the window. 867 │ (advice-add #'register-preview :override #'consult-register-window) 868 │ 869 │ ;; Use Consult to select xref locations with preview 870 │ (setq xref-show-xrefs-function #'consult-xref 871 │ xref-show-definitions-function #'consult-xref) 872 │ 873 │ ;; Configure other variables and modes in the :config section, 874 │ ;; after lazily loading the package. 875 │ :config 876 │ 877 │ ;; Optionally configure preview. The default value 878 │ ;; is 'any, such that any key triggers the preview. 879 │ ;; (setq consult-preview-key 'any) 880 │ ;; (setq consult-preview-key (kbd "M-.")) 881 │ ;; (setq consult-preview-key (list (kbd "<S-down>") (kbd "<S-up>"))) 882 │ ;; For some commands and buffer sources it is useful to configure the 883 │ ;; :preview-key on a per-command basis using the `consult-customize' macro. 884 │ (consult-customize 885 │ consult-theme :preview-key '(:debounce 0.2 any) 886 │ consult-ripgrep consult-git-grep consult-grep 887 │ consult-bookmark consult-recent-file consult-xref 888 │ consult--source-bookmark consult--source-file-register 889 │ consult--source-recent-file consult--source-project-recent-file 890 │ ;; :preview-key (kbd "M-.") 891 │ :preview-key '(:debounce 0.4 any)) 892 │ 893 │ ;; Optionally configure the narrowing key. 894 │ ;; Both < and C-+ work reasonably well. 895 │ (setq consult-narrow-key "<") ;; (kbd "C-+") 896 │ 897 │ ;; Optionally make narrowing help available in the minibuffer. 898 │ ;; You may want to use `embark-prefix-help-command' or which-key instead. 899 │ ;; (define-key consult-narrow-map (vconcat consult-narrow-key "?") #'consult-narrow-help) 900 │ 901 │ ;; By default `consult-project-function' uses `project-root' from project.el. 902 │ ;; Optionally configure a different project root function. 903 │ ;; There are multiple reasonable alternatives to chose from. 904 │ ;;;; 1. project.el (the default) 905 │ ;; (setq consult-project-function #'consult--default-project--function) 906 │ ;;;; 2. projectile.el (projectile-project-root) 907 │ ;; (autoload 'projectile-project-root "projectile") 908 │ ;; (setq consult-project-function (lambda (_) (projectile-project-root))) 909 │ ;;;; 3. vc.el (vc-root-dir) 910 │ ;; (setq consult-project-function (lambda (_) (vc-root-dir))) 911 │ ;;;; 4. locate-dominating-file 912 │ ;; (setq consult-project-function (lambda (_) (locate-dominating-file "." ".git"))) 913 │ ) 914 └──── 915 916 917 [Consult wiki] <https://github.com/minad/consult/wiki> 918 919 920 3.2 Custom variables 921 ──────────────────── 922 923 *TIP:* If you have [Marginalia] installed, type `M-x 924 customize-variable RET ^consult' to see all Consult-specific 925 customizable variables with their current values and abbreviated 926 description. Alternatively, type `C-h a ^consult' to get an overview 927 of all Consult variables and functions with their descriptions. 928 929 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 930 Variable Description 931 ───────────────────────────────────────────────────────────────────────────────────────── 932 consult-after-jump-hook Functions to call after jumping to a location 933 consult-async-input-debounce Input debounce for asynchronous commands 934 consult-async-input-throttle Input throttle for asynchronous commands 935 consult-async-min-input Minimum numbers of letters needed for async process 936 consult-async-refresh-delay Refresh delay for asynchronous commands 937 consult-async-split-style Splitting style used for async commands 938 consult-async-split-styles-alist Available splitting styles used for async commands 939 consult-bookmark-narrow Narrowing configuration for `consult-bookmark' 940 consult-buffer-filter Filter for `consult-buffer' 941 consult-buffer-sources List of virtual buffer sources 942 consult-find-args Command line arguments for find 943 consult-fontify-max-size Buffers larger than this limit are not fontified 944 consult-fontify-preserve Preserve fontification for line-based commands. 945 consult-git-grep-args Command line arguments for git-grep 946 consult-goto-line-numbers Show line numbers for `consult-goto-line' 947 consult-grep-max-columns Maximal number of columns of the matching lines 948 consult-grep-args Command line arguments for grep 949 consult-imenu-config Mode-specific configuration for `consult-imenu' 950 consult-line-numbers-widen Show absolute line numbers when narrowing is active. 951 consult-line-start-from-top Start the `consult-line' search from the top 952 consult-locate-args Command line arguments for locate 953 consult-man-args Command line arguments for man 954 consult-mode-command-filter Filter for `consult-mode-command' 955 consult-mode-histories Mode-specific history variables 956 consult-narrow-key Narrowing prefix key during completion 957 consult-point-placement Placement of the point when jumping to matches 958 consult-preview-key Keys which triggers preview 959 consult-preview-allowed-hooks List of `find-file' hooks to enable during preview 960 consult-preview-excluded-files Regexps matched against file names during preview 961 consult-preview-max-count Maximum number of files to keep open during preview 962 consult-preview-max-size Files larger than this size are not previewed 963 consult-preview-raw-size Files larger than this size are previewed in raw form 964 consult-preview-variables Alist of variables to bind during preview 965 consult-project-buffer-sources List of virtual project buffer sources 966 consult-project-function Function which returns current project root 967 consult-register-prefix Prefix string for register keys during completion 968 consult-ripgrep-args Command line arguments for ripgrep 969 consult-themes List of themes to be presented for selection 970 consult-widen-key Widening key during completion 971 consult-yank-rotate Rotate kill ring 972 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 973 974 975 [Marginalia] <https://github.com/minad/marginalia> 976 977 978 3.3 Fine-tuning of individual commands 979 ────────────────────────────────────── 980 981 *NOTE:* Consult supports fine-grained customization of individual 982 commands. This configuration feature exists for experienced users with 983 special requirements. There is the [Consult wiki], where we collect 984 further configuration examples. 985 986 Commands and buffer sources allow flexible, individual customization 987 by using the `consult-customize' macro. You can override any option 988 passed to the internal `consult--read' API. The [Consult wiki] already 989 contains a numerous useful configuration examples. Note that since 990 `consult--read' is part of the internal API, options could be removed, 991 replaced or renamed in future versions of the package. 992 993 Useful options are: 994 • `:prompt' set the prompt string 995 • `:preview-key' set the preview key, default is `consult-preview-key' 996 • `:initial' set the initial input 997 • `:default' set the default value 998 • `:history' set the history variable symbol 999 • `:add-history' add items to the future history, for example symbol 1000 at point 1001 • `:sort' enable or disable sorting 1002 • `:group' set to nil to disable candidate grouping and titles. 1003 • `:inherit-input-method' set to non-nil to inherit the input method. 1004 1005 ┌──── 1006 │ (consult-customize 1007 │ ;; Disable preview for `consult-theme' completely. 1008 │ consult-theme :preview-key nil 1009 │ ;; Set preview for `consult-buffer' to key `M-.' 1010 │ consult-buffer :preview-key (kbd "M-.") 1011 │ ;; For `consult-line' change the prompt and specify multiple preview 1012 │ ;; keybindings. Note that you should bind <S-up> and <S-down> in the 1013 │ ;; `minibuffer-local-completion-map' or `vertico-map' to the commands which 1014 │ ;; select the previous or next candidate. 1015 │ consult-line :prompt "Search: " 1016 │ :preview-key (list (kbd "<S-down>") (kbd "<S-up>"))) 1017 └──── 1018 1019 The configuration values are evaluated at runtime, just before the 1020 completion session is started. Therefore you can use for example 1021 `thing-at-point' to adjust the initial input or the future history. 1022 1023 ┌──── 1024 │ (consult-customize 1025 │ consult-line 1026 │ :add-history (seq-some #'thing-at-point '(region symbol))) 1027 │ 1028 │ (defalias 'consult-line-thing-at-point 'consult-line) 1029 │ 1030 │ (consult-customize 1031 │ consult-line-thing-at-point 1032 │ :initial (thing-at-point 'symbol)) 1033 └──── 1034 1035 Generally it is possible to modify commands for your individual needs 1036 by the following techniques: 1037 1038 1. Use `consult-customize' in order to change the command or source 1039 settings. 1040 2. Create your own wrapper function which passes modified arguments to 1041 the Consult functions. 1042 3. Create your own buffer [multi sources] for `consult-buffer'. 1043 4. Create advices to modify some internal behavior. 1044 5. Write or propose a patch. 1045 1046 1047 [Consult wiki] <https://github.com/minad/consult/wiki> 1048 1049 [multi sources] See section 2.4 1050 1051 1052 4 Recommended packages 1053 ══════════════════════ 1054 1055 I use and recommend this combination of packages: 1056 1057 • consult: This package 1058 • [vertico]: Fast and minimal vertical completion system 1059 • [marginalia]: Annotations for the completion candidates 1060 • [embark and embark-consult]: Action commands, which can act on the 1061 completion candidates 1062 • [orderless]: Completion style which offers flexible candidate 1063 filtering 1064 1065 There exist many other fine completion UIs beside Vertico, which are 1066 supported by Consult. Give them a try and find out which interaction 1067 model fits best for you. 1068 1069 • The builtin completion UI, which pops up the `*Completions*' buffer. 1070 • The builtin `icomplete-vertical-mode' in Emacs 28. 1071 • [mct by Protesilaos Stavrou]: Minibuffer and Completions in Tandem, 1072 which builds on the default completion UI (development currently 1073 [discontinued]). 1074 1075 Note that all packages are independent and can be exchanged with 1076 alternative components, since there exist no hard 1077 dependencies. Furthermore it is possible to get started with only 1078 default completion and Consult and add more components later to the 1079 mix. For example you can omit Marginalia if you don't need 1080 annotations. I highly recommend the Embark package, but in order to 1081 familiarize yourself with the other components, you can first start 1082 without it - or you could use with Embark right away and add the other 1083 components later on. 1084 1085 1086 [vertico] <https://github.com/minad/vertico> 1087 1088 [marginalia] <https://github.com/minad/marginalia> 1089 1090 [embark and embark-consult] <https://github.com/oantolin/embark> 1091 1092 [orderless] <https://github.com/oantolin/orderless> 1093 1094 [mct by Protesilaos Stavrou] <https://git.sr.ht/~protesilaos/mct> 1095 1096 [discontinued] 1097 <https://protesilaos.com/codelog/2022-04-14-emacs-discontinue-mct/> 1098 1099 1100 5 Auxiliary packages 1101 ════════════════════ 1102 1103 You can integrate Consult with special programs or with other packages 1104 in the wider Emacs ecosystem. You may want to install some of theses 1105 packages depending on your preferences and requirements. 1106 1107 • [consult-ag]: Support for the [Silver Searcher] in the style of 1108 `consult-grep'. 1109 • [consult-company]: Completion at point using the [Company] backends. 1110 • [consult-codesearch]: Integration with [Code Search]. 1111 • [consult-dir]: Directory jumper using Consult multi sources. 1112 • [consult-dash]: Consult interface to [Dash documentation] 1113 • [consult-eglot]: Integration with Eglot (LSP client). 1114 • [consult-flycheck]: Additional Flycheck integration. 1115 • [consult-flyspell]: Additional Flyspell integration. 1116 • [consult-git-log-grep]: Consult interface to git log. 1117 • [consult-hatena-bookmark]: Access Hatena bookmarks. 1118 • [consult-ls-git]: List files from git via Consult. 1119 • [consult-lsp]: Integration with Lsp-mode (LSP client). 1120 • [consult-notmuch]: Access the [Notmuch] email system using Consult. 1121 • [consult-notes]: Searching notes with Consult. 1122 • [consult-org-roam]: Integration with [Org-roam]. 1123 • [consult-project-extra]: Additional project.el extras and buffer 1124 sources. 1125 • [consult-projectile]: Additional [Projectile] integration and buffer 1126 sources. 1127 • [consult-recoll]: Access the [Recoll] desktop full-text search using 1128 Consult. 1129 • [consult-spotify]: Access the Spotify API and control your local 1130 music player. 1131 • [consult-yasnippet]: Integration with Yasnippet. 1132 • [affe]: Asynchronous Fuzzy Finder for Emacs based on Consult. 1133 1134 Not directly related to Consult, but maybe still of interest are the 1135 following packages. These packages should work well with Consult, 1136 follow a similar spirit or offer functionality based on 1137 `completing-read'. 1138 1139 • [corfu]: Completion systems for `completion-at-point' using small 1140 popups (Alternative to [Company]). 1141 • [cape]: Completion At Point Extensions, which can be used with 1142 `consult-completion-in-region' and [Corfu]. 1143 • [bookmark-view]: Store window configuration as bookmarks, possible 1144 integration with `consult-buffer'. 1145 • [citar]: Versatile package for citation insertion and bibliography 1146 management. 1147 • [devdocs]: Emacs viewer for [DevDocs] with a convenient completion 1148 interface. 1149 • [flyspell-correct]: Apply spelling corrections by selecting via 1150 `completing-read'. 1151 • [wgrep]: Editing of grep buffers, use together with `consult-grep' 1152 via `embark-export'. 1153 • [all-the-icons-completion]: Icons for the completion UI. 1154 1155 1156 [consult-ag] <https://github.com/yadex205/consult-ag> 1157 1158 [Silver Searcher] <https://github.com/ggreer/the_silver_searcher> 1159 1160 [consult-company] <https://github.com/mohkale/consult-company> 1161 1162 [Company] <https://github.com/company-mode/company-mode> 1163 1164 [consult-codesearch] <https://github.com/youngker/consult-codesearch.el> 1165 1166 [Code Search] <https://github.com/google/codesearch> 1167 1168 [consult-dir] <https://github.com/karthink/consult-dir> 1169 1170 [consult-dash] <https://codeberg.org/ravi/consult-dash> 1171 1172 [Dash documentation] <https://github.com/dash-docs-el/dash-docs> 1173 1174 [consult-eglot] <https://github.com/mohkale/consult-eglot> 1175 1176 [consult-flycheck] <https://github.com/minad/consult-flycheck> 1177 1178 [consult-flyspell] <https://gitlab.com/OlMon/consult-flyspell> 1179 1180 [consult-git-log-grep] 1181 <https://github.com/ghosty141/consult-git-log-grep> 1182 1183 [consult-hatena-bookmark] 1184 <https://github.com/Nyoho/consult-hatena-bookmark> 1185 1186 [consult-ls-git] <https://github.com/rcj/consult-ls-git> 1187 1188 [consult-lsp] <https://github.com/gagbo/consult-lsp> 1189 1190 [consult-notmuch] <https://codeberg.org/jao/consult-notmuch> 1191 1192 [Notmuch] <https://notmuchmail.org/> 1193 1194 [consult-notes] <https://github.com/mclear-tools/consult-notes> 1195 1196 [consult-org-roam] <https://github.com/jgru/consult-org-roam> 1197 1198 [Org-roam] <https://github.com/org-roam/org-roam> 1199 1200 [consult-project-extra] 1201 <https://github.com/Qkessler/consult-project-extra/> 1202 1203 [consult-projectile] <https://gitlab.com/OlMon/consult-projectile/> 1204 1205 [Projectile] <https://github.com/bbatsov/projectile> 1206 1207 [consult-recoll] <https://codeberg.org/jao/consult-recoll> 1208 1209 [Recoll] <https://www.lesbonscomptes.com/recoll/> 1210 1211 [consult-spotify] <https://codeberg.org/jao/espotify> 1212 1213 [consult-yasnippet] <https://github.com/mohkale/consult-yasnippet> 1214 1215 [affe] <https://github.com/minad/affe> 1216 1217 [corfu] <https://github.com/minad/corfu> 1218 1219 [cape] <https://github.com/minad/cape> 1220 1221 [Corfu] <https://github.com/minad/corfu> 1222 1223 [bookmark-view] <https://github.com/minad/bookmark-view> 1224 1225 [citar] <https://github.com/bdarcus/citar> 1226 1227 [devdocs] <https://github.com/astoff/devdocs.el> 1228 1229 [DevDocs] <https://devdocs.io/> 1230 1231 [flyspell-correct] <https://github.com/d12frosted/flyspell-correct> 1232 1233 [wgrep] <https://github.com/mhayashi1120/Emacs-wgrep> 1234 1235 [all-the-icons-completion] 1236 <https://github.com/iyefrat/all-the-icons-completion> 1237 1238 1239 6 Bug reports 1240 ═════════════ 1241 1242 If you find a bug or suspect that there is a problem with Consult, 1243 please carry out the following steps: 1244 1245 1. *Update all the relevant packages to the newest version*. This 1246 includes Consult, Vertico or other completion UIs, Marginalia, 1247 Embark and Orderless. 1248 2. Either use the default completion UI or ensure that exactly one of 1249 `vertico-mode', `mct-mode', or `icomplete-mode' is enabled. The 1250 unsupported modes `ivy-mode', `helm-mode' and `ido-ubiquitous-mode' 1251 must be disabled. 1252 3. Ensure that the `completion-styles' variable is properly 1253 configured. Try to set `completion-styles' to a list including 1254 `substring' or `orderless'. 1255 4. Try to reproduce the issue by starting a bare bone Emacs instance 1256 with `emacs -Q' on the command line. Execute the following minimal 1257 code snippets in the scratch buffer. This way we can exclude side 1258 effects due to configuration settings. If other packages are 1259 relevant to reproduce the issue, include them in the minimal 1260 configuration snippet. 1261 1262 Minimal setup with Vertico for `emacs -Q': 1263 ┌──── 1264 │ (package-initialize) 1265 │ (require 'consult) 1266 │ (require 'vertico) 1267 │ (vertico-mode) 1268 │ (setq completion-styles '(substring basic)) 1269 └──── 1270 1271 Minimal setup with the default completion system for `emacs -Q': 1272 ┌──── 1273 │ (package-initialize) 1274 │ (require 'consult) 1275 │ (setq completion-styles '(substring basic)) 1276 └──── 1277 1278 Please provide the necessary important information with your bug 1279 report: 1280 1281 • The minimal configuration snippet used to reproduce the issue. 1282 • Your completion UI (Default completion, Vertico, Mct or Icomplete). 1283 • A stack trace in case the bug triggers an exception. 1284 • Your Emacs version, since bugs may be fixed or introduced in newer 1285 versions. 1286 • Your operating system, since Emacs behavior varies between Linux, 1287 Mac and Windows. 1288 • The package manager, e.g., straight.el or package.el, used to 1289 install the Emacs packages, in order to exclude update issues. Did 1290 you install Consult as part of the Doom or Spacemacs Emacs 1291 distributions? 1292 • Do you use Evil or other packages which apply deep changes? Consult 1293 does not provide Evil integration out of the box, but there is some 1294 support in [evil-collection]. 1295 1296 When evaluating Consult-related code snippets you should enable 1297 [lexical binding]. Consult often relies on lambdas and lexical 1298 closures. 1299 1300 1301 [evil-collection] <https://github.com/emacs-evil/evil-collection> 1302 1303 [lexical binding] 1304 <https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html> 1305 1306 1307 7 Contributions 1308 ═══════════════ 1309 1310 Consult is a community effort, please participate in the discussions. 1311 Contributions are welcome, but you may want to discuss potential 1312 contributions first. Since this package is part of [GNU ELPA] 1313 contributions require a copyright assignment to the FSF. 1314 1315 If you have a proposal, take a look at the [Consult issue tracker] and 1316 the [Consult wishlist]. There have been many prior feature 1317 discussions. Please search through the issue tracker, maybe your issue 1318 or feature request has already been discussed. You can contribute to 1319 the [Consult wiki], in case you want to share small configuration or 1320 command snippets. 1321 1322 1323 [GNU ELPA] <https://elpa.gnu.org/packages/consult.html> 1324 1325 [Consult issue tracker] <https://github.com/consult/issues> 1326 1327 [Consult wishlist] <https://github.com/minad/consult/issues/6> 1328 1329 [Consult wiki] <https://github.com/minad/consult/wiki> 1330 1331 1332 8 Acknowledgments 1333 ═════════════════ 1334 1335 This package took inspiration from [Counsel] by Oleh Krehel. Some of 1336 the Consult commands originated in the Counsel package or the wiki of 1337 the Selectrum package. This package exists only thanks to the help of 1338 these great contributors and thanks to the feedback of many 1339 users. Thank you! 1340 1341 Code contributions: 1342 • [Omar Antolín Camarena] 1343 • [Sergey Kostyaev] 1344 • [Earl Hyatt] 1345 • [Clemens Radermacher] 1346 • [Tom Fitzhenry] 1347 • [jakanakaevangeli] 1348 • [Iñigo Serna] 1349 • [Adam Spiers] 1350 • [Omar Polo] 1351 • [Augusto Stoffel] 1352 • [Fox Kiester] 1353 • [Tecosaur] 1354 • [Mohamed Abdelnour] 1355 • [Sylvain Rousseau] 1356 • [J.D. Smith] 1357 • [Mohsin Kaleem] 1358 • [Jean-Philippe Bernardy] 1359 • [Aymeric Agon-Rambosson] 1360 • [Geoffrey Lessel] 1361 • [Piotr Kwiecinski] 1362 1363 Advice and useful discussions: 1364 • [Clemens Radermacher] 1365 • [Omar Antolín Camarena] 1366 • [Protesilaos Stavrou] 1367 • [Steve Purcell] 1368 • [Adam Porter] 1369 • [Manuel Uberti] 1370 • [Tom Fitzhenry] 1371 • [Howard Melman] 1372 • [Stefan Monnier] 1373 • [Dmitry Gutov] 1374 • [Itai Y. Efrat] 1375 • [Bruce d'Arcus] 1376 • [J.D. Smith] 1377 • [Enrique Kessler Martínez] 1378 • [Radon Rosborough] 1379 1380 Authors of supplementary `consult-*' packages: 1381 1382 • [Jose A Ortega Ruiz] ([consult-notmuch], [consult-recoll], 1383 [consult-spotify]) 1384 • [Gerry Agbobada] ([consult-lsp]) 1385 • [Karthik Chikmagalur] ([consult-dir]) 1386 • [Mohsin Kaleem] ([consult-company], [consult-eglot], 1387 [consult-yasnippet]) 1388 • [Marco Pawłowski] ([consult-flyspell], [consult-projectile]) 1389 • [Enrique Kessler Martínez] ([consult-project-extra]) 1390 • [Jan Gru] ([consult-org-roam]) 1391 • [Kanon Kakuno] ([consult-ag]) 1392 • [Robin Joy] ([consult-ls-git]) 1393 • [Ravi R Kiran] [(consult-dash]) 1394 • [Colin McLear] ([consult-notes]) 1395 • [Yukinori Kitadai] ([consult-hatena-bookmark]) 1396 • [ghosty141] ([consult-git-log-grep]) 1397 • [YoungJoo Lee] ([consult-codesearch]) 1398 1399 1400 [Counsel] <https://github.com/abo-abo/swiper#counsel> 1401 1402 [Omar Antolín Camarena] <https://github.com/oantolin/> 1403 1404 [Sergey Kostyaev] <https://github.com/s-kostyaev/> 1405 1406 [Earl Hyatt] <https://github.com/okamsn/> 1407 1408 [Clemens Radermacher] <https://github.com/clemera/> 1409 1410 [Tom Fitzhenry] <https://github.com/tomfitzhenry/> 1411 1412 [jakanakaevangeli] <https://github.com/jakanakaevangeli> 1413 1414 [Iñigo Serna] <https://hg.serna.eu> 1415 1416 [Adam Spiers] <https://github.com/aspiers/> 1417 1418 [Omar Polo] <https://github.com/omar-polo> 1419 1420 [Augusto Stoffel] <https://github.com/astoff> 1421 1422 [Fox Kiester] <https://github.com/noctuid> 1423 1424 [Tecosaur] <https://github.com/tecosaur> 1425 1426 [Mohamed Abdelnour] <https://github.com/mohamed-abdelnour> 1427 1428 [Sylvain Rousseau] <https://github.com/thisirs> 1429 1430 [J.D. Smith] <https://github.com/jdtsmith> 1431 1432 [Mohsin Kaleem] <https://github.com/mohkale> 1433 1434 [Jean-Philippe Bernardy] <https://github.com/jyp> 1435 1436 [Aymeric Agon-Rambosson] <https://github.com/aagon> 1437 1438 [Geoffrey Lessel] <https://github.com/geolessel> 1439 1440 [Piotr Kwiecinski] <https://github.com/piotrkwiecinski> 1441 1442 [Protesilaos Stavrou] <https://protesilaos.com> 1443 1444 [Steve Purcell] <https://github.com/purcell/> 1445 1446 [Adam Porter] <https://github.com/alphapapa/> 1447 1448 [Manuel Uberti] <https://github.com/manuel-uberti/> 1449 1450 [Howard Melman] <https://github.com/hmelman/> 1451 1452 [Stefan Monnier] <https://github.com/monnier/> 1453 1454 [Dmitry Gutov] <https://github.com/dgutov/> 1455 1456 [Itai Y. Efrat] <https://github.com/iyefrat> 1457 1458 [Bruce d'Arcus] <https://github.com/bdarcus> 1459 1460 [Enrique Kessler Martínez] <https://github.com/Qkessler> 1461 1462 [Radon Rosborough] <https://github.com/raxod502> 1463 1464 [Jose A Ortega Ruiz] <https://codeberg.org/jao/> 1465 1466 [consult-notmuch] <https://codeberg.org/jao/consult-notmuch> 1467 1468 [consult-recoll] <https://codeberg.org/jao/consult-recoll> 1469 1470 [consult-spotify] <https://codeberg.org/jao/espotify> 1471 1472 [Gerry Agbobada] <https://github.com/gagbo/> 1473 1474 [consult-lsp] <https://github.com/gagbo/consult-lsp> 1475 1476 [Karthik Chikmagalur] <https://github.com/karthink> 1477 1478 [consult-dir] <https://github.com/karthink/consult-dir> 1479 1480 [consult-company] <https://github.com/mohkale/consult-company> 1481 1482 [consult-eglot] <https://github.com/mohkale/consult-eglot> 1483 1484 [consult-yasnippet] <https://github.com/mohkale/consult-yasnippet> 1485 1486 [Marco Pawłowski] <https://gitlab.com/OlMon> 1487 1488 [consult-flyspell] <https://gitlab.com/OlMon/consult-flyspell> 1489 1490 [consult-projectile] <https://gitlab.com/OlMon/consult-projectile> 1491 1492 [consult-project-extra] 1493 <https://github.com/Qkessler/consult-project-extra> 1494 1495 [Jan Gru] <https://github.com/jgru> 1496 1497 [consult-org-roam] <https://github.com/jgru/consult-org-roam> 1498 1499 [Kanon Kakuno] <https://github.com/yadex205> 1500 1501 [consult-ag] <https://github.com/yadex205/consult-ag> 1502 1503 [Robin Joy] <https://github.com/rcj> 1504 1505 [consult-ls-git] <https://github.com/rcj/consult-ls-git> 1506 1507 [Ravi R Kiran] <https://codeberg.org/ravi> 1508 1509 [(consult-dash] <https://codeberg.org/ravi/consult-dash> 1510 1511 [Colin McLear] <https://github.com/mclearc> 1512 1513 [consult-notes] <https://github.com/mclear-tools/consult-notes> 1514 1515 [Yukinori Kitadai] <https://github.com/Nyoho> 1516 1517 [consult-hatena-bookmark] 1518 <https://github.com/Nyoho/consult-hatena-bookmark> 1519 1520 [ghosty141] <https://github.com/ghosty141> 1521 1522 [consult-git-log-grep] 1523 <https://github.com/ghosty141/consult-git-log-grep> 1524 1525 [YoungJoo Lee] <https://github.com/youngker> 1526 1527 [consult-codesearch] <https://github.com/youngker/consult-codesearch.el> 1528 1529 1530 9 Indices 1531 ═════════ 1532 1533 9.1 Function index 1534 ────────────────── 1535 1536 1537 9.2 Concept index 1538 ─────────────────