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