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