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