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