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