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