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