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