-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathconsult.info
1544 lines (1322 loc) · 72.8 KB
/
consult.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is doc2UPoKa.info, produced by makeinfo version 6.8 from
consult.texi.
INFO-DIR-SECTION Emacs misc features
START-INFO-DIR-ENTRY
* Consult: (consult). Useful commands built on completing-read.
END-INFO-DIR-ENTRY
File: doc2UPoKa.info, Node: Top, Next: Available commands, Up: (dir)
consult.el - Consulting completing-read
***************************************
Consult provides search and navigation commands based on the Emacs
completion function completing-read
(https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html).
Completion allows you to quickly select an item from a list of
candidates. Consult offers asynchronous and interactive ‘consult-grep’
and ‘consult-ripgrep’ commands, and the line-based search command
‘consult-line’. Furthermore Consult provides an advanced buffer
switching command ‘consult-buffer’ to switch between buffers, recently
opened files, bookmarks and buffer-like candidates from other sources.
Some of the Consult commands are enhanced versions of built-in Emacs
commands. For example the command ‘consult-imenu’ presents a flat list
of the Imenu with *note live preview: Live previews, *note grouping and
narrowing: Narrowing and grouping. Please take a look at the *note full
list of commands: Available commands.
Consult is fully compatible with completion systems centered around
the standard Emacs ‘completing-read’ API, notably the default completion
system, Vertico (https://github.com/minad/vertico), Mct
(https://github.com/protesilaos/mct), and Icomplete
(https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html).
This package keeps the completion system specifics to a minimum. The
ability of the Consult commands to work well with arbitrary completion
systems is one of the main advantages of the package. Consult fits well
into existing setups and it helps you to create a full completion
environment out of small and independent components.
You can combine the complementary packages Marginalia
(https://github.com/minad/marginalia/), Embark
(https://github.com/oantolin/embark/) and Orderless
(https://github.com/oantolin/orderless) with Consult. Marginalia
enriches the completion display with annotations, e.g., documentation
strings or file information. The versatile Embark package provides
local actions, comparable to a context menu. These actions operate on
the selected candidate in the minibuffer or at point in normal buffers.
For example, when selecting from a list of files, Embark offers an
action to delete the file. Additionally Embark offers a facility to
collect completion candidates in a collect buffer. The section *note
Embark integration:: documents in detail how Consult and Embark work
together.
* Menu:
* Available commands:: Navigation, search, editing commands and more
* Special features:: Enhancements over built-in ‘completing-read’
* Configuration:: Example configuration and customization variables
* Recommended packages:: Related packages recommended for installation
* Bug reports:: How to create reproducible bug reports
* Hacking::
* Contributions:: Feature requests and pull requests
* Acknowledgments:: Contributors and Sources of Inspiration
* Indices:: Indices of concepts and functions
— The Detailed Node Listing —
Available commands
* Virtual Buffers:: Buffers, bookmarks and recent files
* Editing:: Commands useful for editing
* Register:: Searching through registers and fast access
* Navigation:: Mark rings, outlines and imenu
* Search:: Line search, grep and file search
* Grep and Find:: Searching through the filesystem
* Compilation:: Jumping to references and compilation errors
* Histories:: Navigating histories
* Modes:: Toggling minor modes and executing commands
* Org Mode:: Org-specific commands
* Help:: Searching through help
* Miscellaneous:: Various other useful commands
Special features
* Live previews:: Preview the currently selected candidate
* Narrowing and grouping:: Restricting the completion to a candidate group
* Asynchronous search:: Filtering asynchronously generated candidate lists
* Multiple sources:: Combining candidates from different sources
* Embark integration:: Actions, Grep/Occur-buffer export
Configuration
* Use-package example:: Configuration example based on use-package
* Custom variables:: Short description of all customization settings
* Project support:: Project discovery support for search commands
* Fine-tuning:: Fine-grained configuration for special requirements
Hacking
* Creating asynchronous completion commands::
* Live preview::
Indices
* Function index:: List of all Consult commands
* Concept index:: List of all Consult-specific concepts
File: doc2UPoKa.info, Node: Available commands, Next: Special features, Prev: Top, Up: Top
1 Available commands
********************
Most Consult commands follow the meaningful naming scheme
‘consult-<thing>’. Many commands implement a little known but
convenient Emacs feature called "future history", which guesses what
input the user wants. At a command prompt type ‘M-n’ and typically
Consult will insert the symbol or thing at point into the input.
*TIP:* If you have Marginalia (https://github.com/minad/marginalia)
annotators activated, type ‘M-x ^consult’ to see all Consult commands
with their abbreviated description. Alternatively, type ‘C-h a
^consult’ to get an overview of all Consult variables and functions with
their descriptions.
* Menu:
* Virtual Buffers:: Buffers, bookmarks and recent files
* Editing:: Commands useful for editing
* Register:: Searching through registers and fast access
* Navigation:: Mark rings, outlines and imenu
* Search:: Line search, grep and file search
* Grep and Find:: Searching through the filesystem
* Compilation:: Jumping to references and compilation errors
* Histories:: Navigating histories
* Modes:: Toggling minor modes and executing commands
* Org Mode:: Org-specific commands
* Help:: Searching through help
* Miscellaneous:: Various other useful commands
File: doc2UPoKa.info, Node: Virtual Buffers, Next: Editing, Up: Available commands
1.1 Virtual Buffers
===================
• ‘consult-buffer’: Enhanced version of ‘switch-to-buffer’ with
support for virtual buffers. Supports live preview of buffers and
narrowing to the virtual buffer types. You can type ‘f SPC’ in
order to narrow to recent files. Press ‘SPC’ to show ephemeral
buffers. Supported narrowing keys:
• b Buffers
• SPC Hidden buffers
• * Modified buffers
• f Files (Requires ‘recentf-mode’)
• r File registers
• m Bookmarks
• p Project
• B Project buffers
• F Project files
• R Project roots
• Custom *note other sources: Multiple sources. configured in
‘consult-buffer-sources’.
• ‘consult-buffer-other-window’, ‘consult-buffer-other-frame’,
‘consult-buffer-other-tab’: Variants of ‘consult-buffer’.
• ‘consult-project-buffer’: Variant of ‘consult-buffer’ restricted to
buffers and recent files of the current project. You can add
custom sources to ‘consult-project-buffer-sources’. The command
may prompt you for a project if you invoke it from outside a
project.
• ‘consult-bookmark’: Select or create bookmark. To select bookmarks
you might use the ‘consult-buffer’ as an alternative, which can
include a bookmark virtual buffer source. Note that
‘consult-bookmark’ supports preview of bookmarks and narrowing.
• ‘consult-recent-file’: Select from recent files with preview. You
might prefer the powerful ‘consult-buffer’ instead, which can
include recent files as a virtual buffer source. The
‘recentf-mode’ enables tracking of recent files.
File: doc2UPoKa.info, Node: Editing, Next: Register, Prev: Virtual Buffers, Up: Available commands
1.2 Editing
===========
• ‘consult-yank-from-kill-ring’: Enhanced version of ‘yank’ to select
an item from the ‘kill-ring’. The selected text previewed as
overlay in the buffer.
• ‘consult-yank-pop’: Enhanced version of ‘yank-pop’ with
DWIM-behavior, which either replaces the last ‘yank’ by cycling
through the ‘kill-ring’, or if there has not been a last ‘yank’
consults the ‘kill-ring’. The selected text previewed as overlay
in the buffer.
• ‘consult-yank-replace’: Like ‘consult-yank-pop’, but always
replaces the last ‘yank’ with an item from the ‘kill-ring’.
• ‘consult-kmacro’: Select macro from the macro ring and execute it.
File: doc2UPoKa.info, Node: Register, Next: Navigation, Prev: Editing, Up: Available commands
1.3 Register
============
• ‘consult-register’: Select from list of registers. The command
supports narrowing to register types and preview of marker
positions. This command is useful to search the register contents.
For quick access use the commands ‘consult-register-load’,
‘consult-register-store’ or the built-in Emacs register commands.
• ‘consult-register-format’: Set ‘register-preview-function’ to this
function for an enhanced register formatting. Used automatically
by ‘consult-register-window’.
• ‘consult-register-window’: Replace ‘register-preview’ with this
function for a better register window. See the *note example
configuration: Use-package example.
• ‘consult-register-load’: Utility command to quickly load a
register. The command either jumps to the register value or
inserts it.
• ‘consult-register-store’: Improved UI to store registers depending
on the current context with an action menu. With an active region,
store/append/prepend the contents, optionally deleting the region
when a prefix argument is given. With a numeric prefix argument,
store/add the number. Otherwise store point, frameset, window or
kmacro. Usage examples:
• ‘M-' x’: If no region is active, store point in register ‘x’.
If a region is active, store the region in register ‘x’.
• ‘M-' M-w x’: Store window configuration in register ‘x’.
• ‘C-u 100 M-' x’: Store number in register ‘x’.
File: doc2UPoKa.info, Node: Navigation, Next: Search, Prev: Register, Up: Available commands
1.4 Navigation
==============
• ‘consult-goto-line’: Jump to line number enhanced with live
preview. This is a drop-in replacement for ‘goto-line’. Enter a
line number to jump to the first column of the given line.
Alternatively enter ‘line:column’ in order to jump to a specific
column.
• ‘consult-mark’: Jump to a marker in the ‘mark-ring’. Supports live
preview and recursive editing.
• ‘consult-global-mark’: Jump to a marker in the ‘global-mark-ring’.
Supports live preview and recursive editing.
• ‘consult-outline’: Jump to a heading of the outline. Supports
narrowing to a heading level, live preview and recursive editing.
• ‘consult-imenu’: Jump to imenu item in the current buffer.
Supports live preview, recursive editing and narrowing.
• ‘consult-imenu-multi’: Jump to imenu item in project buffers, with
the same major mode as the current buffer. Supports live preview,
recursive editing and narrowing. This feature has been inspired by
imenu-anywhere (https://github.com/vspinu/imenu-anywhere).
File: doc2UPoKa.info, Node: Search, Next: Grep and Find, Prev: Navigation, Up: Available commands
1.5 Search
==========
• ‘consult-line’: Enter search string and select from matching lines.
Supports live preview and recursive editing. The symbol at point
and the recent Isearch string are added to the "future history" and
can be accessed by pressing ‘M-n’. When ‘consult-line’ is bound to
the ‘isearch-mode-map’ and is invoked during a running Isearch, it
will use the current Isearch string.
• ‘consult-line-multi’: Search dynamically across multiple buffers.
By default search across project buffers. If invoked with a prefix
argument search across all buffers. The candidates are computed on
demand based on the input. The command behaves like
‘consult-grep’, but operates on buffers instead of files.
• ‘consult-keep-lines’: Replacement for ‘keep/flush-lines’ which uses
the current completion style for filtering the buffer. The
function updates the buffer while typing. In particular
‘consult-keep-lines’ can narrow down an exported Embark collect
buffer further, relying on the same completion filtering as
‘completing-read’. If the input begins with the negation operator,
i.e., ‘! SPC’, the filter matches the complement. If a region is
active, the region restricts the filtering.
• ‘consult-focus-lines’: Temporarily hide lines by filtering them
using the current completion style. Call with ‘C-u’ prefix
argument in order to show the hidden lines again. If the input
begins with the negation operator, i.e., ‘! SPC’, the filter
matches the complement. In contrast to ‘consult-keep-lines’ this
function does not edit the buffer. If a region is active, the
region restricts the filtering.
File: doc2UPoKa.info, Node: Grep and Find, Next: Compilation, Prev: Search, Up: Available commands
1.6 Grep and Find
=================
• ‘consult-grep’, ‘consult-ripgrep’, ‘consult-git-grep’: Search for
regular expression in files. Consult invokes Grep asynchronously,
while you enter the search term. After at least
‘consult-async-min-input’ characters, the search gets started.
Consult splits the input string into two parts, if the first
character is a punctuation character, like ‘#’. For example
‘#regexps#filter-string’, is split at the second ‘#’. The string
‘regexps’ is passed to Grep. Note that Consult transforms Emacs
regular expressions to expressions understand by the search
program. Always use Emacs regular expressions at the prompt. If
you enter multiple regular expressions separated by space only
lines matching all regular expressions are shown. In order to
match space literally, escape the space with a backslash. The
‘filter-string’ is passed to the _fast_ Emacs filtering to further
narrow down the list of matches. This is particularly useful if
you are using an advanced completion style like orderless.
‘consult-grep’ supports preview. ‘consult-grep’ searches the
current *note project directory: Project support. if a project is
found. Otherwise the ‘default-directory’ is searched. If
‘consult-grep’ is invoked with prefix argument ‘C-u M-s g’, you can
specify one or more comma-separated files and directories manually.
If invoked with two prefix arguments ‘C-u C-u M-s g’, you can first
select a project if you are not yet inside a project.
• ‘consult-find’, ‘consult-fd’, ‘consult-locate’: Find file by
matching the path against a regexp. Like for ‘consult-grep’,
either the project root or the current directory is the root
directory for the search. The input string is treated similarly to
‘consult-grep’, where the first part is passed to find, and the
second part is used for Emacs filtering. Prefix arguments to
‘consult-find’ work just like those for the consult grep commands.
File: doc2UPoKa.info, Node: Compilation, Next: Histories, Prev: Grep and Find, Up: Available commands
1.7 Compilation
===============
• ‘consult-compile-error’: Jump to a compilation error. Supports
live preview narrowing and recursive editing.
• ‘consult-flymake’: Jump to Flymake diagnostic. Supports live
preview and recursive editing. The command supports narrowing.
Press ‘e SPC’, ‘w SPC’, ‘n SPC’ to only show errors, warnings and
notes respectively.
• ‘consult-xref’: Integration with xref. This function can be set as
‘xref-show-xrefs-function’ and ‘xref-show-definitions-function’.
File: doc2UPoKa.info, Node: Histories, Next: Modes, Prev: Compilation, Up: Available commands
1.8 Histories
=============
• ‘consult-complex-command’: Select a command from the
‘command-history’. This command is a ‘completing-read’ version of
‘repeat-complex-command’ and is also a replacement for the
‘command-history’ command from chistory.el.
• ‘consult-history’: Insert a string from the current buffer history,
for example the Eshell or Comint history. You can also invoke this
command from the minibuffer. In that case ‘consult-history’ uses
the history stored in the ‘minibuffer-history-variable’. If you
prefer ‘completion-at-point’, take a look at ‘cape-history’ from
the Cape (https://github.com/minad/cape) package.
• ‘consult-isearch-history’: During an Isearch session, this command
picks a search string from history and continues the search with
the newly selected string. Outside of Isearch, the command allows
you to pick a string from the history and starts a new Isearch.
‘consult-isearch-history’ acts as a drop-in replacement for
‘isearch-edit-string’.
File: doc2UPoKa.info, Node: Modes, Next: Org Mode, Prev: Histories, Up: Available commands
1.9 Modes
=========
• ‘consult-minor-mode-menu’: Enable/disable minor mode. Supports
narrowing to on/off/local/global modes by pressing ‘i/o/l/g SPC’
respectively.
• ‘consult-mode-command’: Run a command from the currently active
minor or major modes. Supports narrowing to
local-minor/global-minor/major mode via the keys ‘l/g/m’.
File: doc2UPoKa.info, Node: Org Mode, Next: Help, Prev: Modes, Up: Available commands
1.10 Org Mode
=============
• ‘consult-org-heading’: Variant of ‘consult-imenu’ or
‘consult-outline’ for Org buffers. The headline and its ancestors
headlines are separated by slashes. Supports narrowing by heading
level, priority and TODO keyword, as well as live preview and
recursive editing.
• ‘consult-org-agenda’: Jump to an Org agenda heading. Supports
narrowing by heading level, priority and TODO keyword, as well as
live preview and recursive editing.
File: doc2UPoKa.info, Node: Help, Next: Miscellaneous, Prev: Org Mode, Up: Available commands
1.11 Help
=========
• ‘consult-man’: Find Unix man page, via Unix ‘apropos’ or ‘man -k’.
‘consult-man’ opens the selected man page using the Emacs ‘man’
command. Supports live preview of the theme while scrolling
through the candidates.
• ‘consult-info’: Full text search through info pages. If the
command is invoked from within an ‘*info*’ buffer, it will search
through the current manual. You may want to create your own
commands which search through a predefined set of info pages, for
example:
(defun consult-info-emacs ()
"Search through Emacs info pages."
(interactive)
(consult-info "emacs" "efaq" "elisp" "cl" "compat"))
(defun consult-info-org ()
"Search through the Org info page."
(interactive)
(consult-info "org"))
(defun consult-info-completion ()
"Search through completion info pages."
(interactive)
(consult-info "vertico" "consult" "marginalia" "orderless" "embark"
"corfu" "cape" "tempel"))
File: doc2UPoKa.info, Node: Miscellaneous, Prev: Help, Up: Available commands
1.12 Miscellaneous
==================
• ‘consult-theme’: Select a theme and disable all currently enabled
themes. Supports live preview of the theme while scrolling through
the candidates.
• ‘consult-preview-at-point’ and ‘consult-preview-at-point-mode’:
Command and minor mode which previews the candidate at point in the
‘*Completions*’ buffer. This mode is relevant if you use Mct
(https://git.sr.ht/~protesilaos/mct) or the default ‘*Completions*’
UI.
• ‘consult-completion-in-region’: In case you don’t use Corfu
(https://github.com/minad/corfu) as your in-buffer completion UI,
this function can be set as ‘completion-in-region-function’. Then
your minibuffer completion UI (e.g., Vertico or Icomplete) will be
used for ‘completion-at-point’.
;; Use `consult-completion-in-region' if Vertico is enabled.
;; Otherwise use the default `completion--in-region' function.
(setq completion-in-region-function
(lambda (&rest args)
(apply (if vertico-mode
#'consult-completion-in-region
#'completion--in-region)
args)))
Instead of ‘consult-completion-in-region’, you may prefer to see
the completions directly in the buffer as a small popup. In that
case, I recommend the Corfu (https://github.com/minad/corfu)
package. There is a technical limitation of
‘consult-completion-in-region’ in combination with the Lsp modes.
The Lsp server relies on the input at point, in order to generate
refined candidate strings. Since the completion is transferred
from the original buffer to the minibuffer, the server does not
receive the updated input. In contrast, in-buffer Lsp completion
for example via Corfu works properly since the completion takes
place directly in the original buffer.
File: doc2UPoKa.info, Node: Special features, Next: Configuration, Prev: Available commands, Up: Top
2 Special features
******************
Consult enhances ‘completing-read’ with live previews of candidates,
additional narrowing capabilities to candidate groups and asynchronously
generated candidate lists. The internal ‘consult--read’ function, which
is used by most Consult commands, is a thin wrapper around
‘completing-read’ and provides the special functionality. In order to
support multiple candidate sources there exists the high-level function
‘consult--multi’. The architecture of Consult allows it to work with
different completion systems in the backend, while still offering
advanced features.
* Menu:
* Live previews:: Preview the currently selected candidate
* Narrowing and grouping:: Restricting the completion to a candidate group
* Asynchronous search:: Filtering asynchronously generated candidate lists
* Multiple sources:: Combining candidates from different sources
* Embark integration:: Actions, Grep/Occur-buffer export
File: doc2UPoKa.info, Node: Live previews, Next: Narrowing and grouping, Up: Special features
2.1 Live previews
=================
Some Consult commands support live previews. For example when you
scroll through the items of ‘consult-line’, the buffer will scroll to
the corresponding position. It is possible to jump back and forth
between the minibuffer and the buffer to perform recursive editing while
the search is ongoing.
Consult enables previews by default. You can disable them by
adjusting the ‘consult-preview-key’ variable. Furthermore it is
possible to specify keybindings which trigger the preview manually as
shown in the *note example configuration: Use-package example. The
default setting of ‘consult-preview-key’ is ‘any’ which means that
Consult triggers the preview _immediately_ on any key press when the
selected candidate changes. You can configure each command individually
with its own ‘:preview-key’. The following settings are possible:
• Automatic and immediate ‘'any’
• Automatic and delayed ‘(list :debounce 0.5 'any)’
• Manual and immediate ‘"M-."’
• Manual and delayed ‘(list :debounce 0.5 "M-.")’
• Disabled ‘nil’
A safe recommendation is to leave automatic immediate previews
enabled in general and disable the automatic preview only for commands
where the preview may be expensive due to file loading. Internally,
Consult uses the value of ‘this-command’ to determine the ‘:preview-key’
customized. This means that if you wrap a ‘consult-*’ command within
your own function or command, you will also need to add the name of
_your custom command_ to the ‘consult-customize’ call in order for it to
be considered.
(consult-customize
consult-ripgrep consult-git-grep consult-grep consult-man
consult-bookmark consult-recent-file consult-xref
consult--source-bookmark consult--source-file-register
consult--source-recent-file consult--source-project-recent-file
;; my/command-wrapping-consult ;; disable auto previews inside my command
:preview-key '(:debounce 0.4 any) ;; Option 1: Delay preview
;; :preview-key "M-.") ;; Option 2: Manual preview
In this case one may wonder what the difference is between using an
Embark action on the current candidate in comparison to a manually
triggered preview. The main difference is that the files opened by
manual preview are closed again after the completion session. During
preview some functionality is disabled to improve the performance, see
for example the customization variables ‘consult-preview-variables’ and
‘consult-preview-allowed-hooks’. Only hooks listed in
‘consult-preview-allowed-hooks’ are executed. This variable applies to
‘find-file-hook’, ‘change-major-mode-hook’ and mode hooks, e.g.,
‘prog-mode-hook’. In order to enable additional font locking during
preview, add the corresponding hooks to the allow list. The following
code demonstrates this for org-modern
(https://github.com/minad/org-modern) and hl-todo
(https://github.com/tarsius/hl-todo).
;; local modes added to prog-mode hooks
(add-to-list 'consult-preview-allowed-hooks 'hl-todo-mode)
(add-to-list 'consult-preview-allowed-hooks 'elide-head-mode)
;; enabled global modes
(add-to-list 'consult-preview-allowed-hooks 'global-org-modern-mode)
(add-to-list 'consult-preview-allowed-hooks 'global-hl-todo-mode)
Files larger than ‘consult-preview-partial-size’ are previewed
partially. Delaying the preview is also useful for ‘consult-theme’,
since the theme preview is slow. The delay results in a smoother UI
experience.
;; Preview on any key press, but delay 0.5s
(consult-customize consult-theme :preview-key '(:debounce 0.5 any))
;; Preview immediately on M-., on up/down after 0.5s, on any other key after 1s
(consult-customize consult-theme
:preview-key
'("M-."
:debounce 0.5 "<up>" "<down>"
:debounce 1 any))
File: doc2UPoKa.info, Node: Narrowing and grouping, Next: Asynchronous search, Prev: Live previews, Up: Special features
2.2 Narrowing and grouping
==========================
Consult has special support for candidate groups. If the completion UI
supports the grouping functionality, the UI separates the groups with
thin lines and shows group titles. Grouping is useful if the list of
candidates consists of candidates of multiple types or candidates from
*note multiple sources: Multiple sources, like the ‘consult-buffer’
command, which shows both buffers and recently opened files. Note that
you can disable the group titles by setting the ‘:group’ property of the
corresponding command to nil using the ‘consult-customize’ macro.
By entering a narrowing prefix or by pressing a narrowing key it is
possible to restrict the completion candidates to a certain candidate
group. When you use the ‘consult-buffer’ command, you can enter the
prefix ‘b SPC’ to restrict list of candidates to buffers only. If you
press ‘DEL’ afterwards, the full candidate list will be shown again.
Furthermore a narrowing prefix key and a widening key can be configured
which can be pressed to achieve the same effect, see the configuration
variables ‘consult-narrow-key’ and ‘consult-widen-key’.
After pressing ‘consult-narrow-key’, the possible narrowing keys can
be shown by pressing ‘C-h’. When pressing ‘C-h’ after some prefix key,
the ‘prefix-help-command’ is invoked, which shows the keybinding help
window by default. As a more compact alternative, there is the
‘consult-narrow-help’ command which can be bound to a key, for example
‘?’ or ‘C-h’ in the ‘consult-narrow-map’, as shown in the *note example
configuration: Use-package example. If which-key
(https://github.com/justbur/emacs-which-key) is installed, the narrowing
keys are automatically shown in the which-key window after pressing the
‘consult-narrow-key’.
File: doc2UPoKa.info, Node: Asynchronous search, Next: Multiple sources, Prev: Narrowing and grouping, Up: Special features
2.3 Asynchronous search
=======================
Consult has support for asynchronous generation of candidate lists.
This feature is used for search commands like ‘consult-grep’, where the
list of matches is generated dynamically while the user is typing a
regular expression. The grep process is executed in the background.
When modifying the regular expression, the background process is
terminated and a new process is started with the modified regular
expression.
The matches, which have been found, can then be narrowed using the
installed Emacs completion-style. This can be powerful if you are using
for example the ‘orderless’ completion style.
This two-level filtering is possible by splitting the input string.
Part of the input string is treated as input to grep and part of the
input is used for filtering. There are multiple splitting styles
available, configured in ‘consult-async-split-styles-alist’: ‘nil’,
‘comma’, ‘semicolon’ and ‘perl’. The default splitting style is
configured with the variable ‘consult-async-split-style’.
With the ‘comma’ and ‘semicolon’ splitting styles, the first word
before the comma or semicolon is passed to grep, the remaining string is
used for filtering. The ‘nil’ splitting style does not perform any
splitting, the whole input is passed to grep.
The ‘perl’ splitting style splits the input string at a punctuation
character, using a similar syntax as Perl regular expressions.
Examples:
• ‘#defun’: Search for "defun" using grep.
• ‘#consult embark’: Search for both "consult" and "embark" using
grep in any order.
• ‘#first.*second’: Search for "first" followed by "second" using
grep.
• ‘#\(consult\|embark\)’: Search for "consult" or "embark" using
grep. Note the usage of Emacs-style regular expressions.
• ‘#defun#consult’: Search for "defun" using grep, filter with the
word "consult".
• ‘/defun/consult’: It is also possible to use other punctuation
characters.
• ‘#to#’: Force searching for "to" using grep, since the grep pattern
must be longer than ‘consult-async-min-input’ characters by
default.
• ‘#defun -- --invert-match#’: Pass argument ‘--invert-match’ to
grep.
Asynchronous processes like ‘find’ and ‘grep’ create an error log
buffer ‘_*consult-async*’ (note the leading space), which is useful for
troubleshooting. The prompt has a small indicator showing the process
status:
• ‘:’ the usual prompt colon, before input is provided.
• ‘*’ with warning face, the process is running.
• ‘:’ with success face, success, process exited with an error code
of zero.
• ‘!’ with error face, failure, process exited with a nonzero error
code.
• ‘;’ with error face, interrupted, for example if more input is
provided.
File: doc2UPoKa.info, Node: Multiple sources, Next: Embark integration, Prev: Asynchronous search, Up: Special features
2.4 Multiple sources
====================
Multiple static and asynchronous candidate sources can be combined.
This feature is used by the ‘consult-buffer’ command to present
buffer-like candidates in a single menu for quick access. By default
‘consult-buffer’ includes buffers, bookmarks, recent files and
project-specific buffers and files. The ‘consult-buffer-sources’
variable configures the list of sources. Arbitrary custom sources can
be added to this list.
As an example, the bookmark source is defined as follows:
(defvar consult--source-bookmark
`(:name "Bookmark"
:narrow ?m
:category bookmark
:face consult-bookmark
:history bookmark-history
:items ,#'bookmark-all-names
:action ,#'consult--bookmark-action))
Either the ‘:items’ or the ‘:async’ source field is required:
• ‘:items’ List of strings to select from or function returning list
of strings. The strings can carry metadata in text properties,
which is then available to the ‘:annotate’, ‘:action’ and ‘:state’
functions. The list can also consist of pairs, with the string in
the ‘car’ used for display and the ‘cdr’ the actual candidate.
• ‘:async’ Alternative to ‘:items’ for asynchronous sources. See the
docstring for details.
Optional source fields:
• ‘:name’ Name of the source, used for narrowing, group titles and
annotations.
• ‘:narrow’ Narrowing character, ‘(char . string)’ pair or list of
pairs.
• ‘:category’ Completion category.
• ‘:preview-key’ Preview key or keys which trigger preview.
• ‘:enabled’ Function which must return t if the source is enabled.
• ‘:hidden’ When t candidates of this source are hidden by default.
• ‘:face’ Face used for highlighting the candidates.
• ‘:annotate’ Annotation function called for each candidate, returns
string.
• ‘:history’ Name of history variable to add selected candidate.
• ‘:default’ Must be t if the first item of the source is the default
value.
• ‘:action’ Function called with the selected candidate.
• ‘:new’ Function called with new candidate name, only if
‘:require-match’ is nil.
• ‘:state’ State constructor for the source, must return the state
function.
• Other source fields can be added specifically to the use case.
The ‘:state’ and ‘:action’ fields of the sources deserve a longer
explanation. The ‘:action’ function takes a single argument and is only
called after selection with the selected candidate, if the selection has
not been aborted. This functionality is provided for convenience and
easy definition of sources. The ‘:state’ field is more general. The
‘:state’ function is a constructor function without arguments, which can
perform some setup necessary for the preview. It must return a closure
which takes an ACTION and a CANDIDATE argument. See the docstring of
‘consult--with-preview’ for more details about the ACTION argument.
By default, ‘consult-buffer’ previews buffers, bookmarks and files.
Loading recent files or bookmarks can result in expensive operations.
However it is possible to configure a manual preview as follows.
(consult-customize
consult--source-bookmark consult--source-file-register
consult--source-recent-file consult--source-project-recent-file
:preview-key "M-.")
Sources can be added directly to the ‘consult-buffer-source’ list for
convenience. For example, the following source lists all Org buffers
and lets you create new ones.
(defvar org-source
(list :name "Org Buffer"
:category 'buffer
:narrow ?o
:face 'consult-buffer
:history 'buffer-name-history
:state #'consult--buffer-state
:new
(lambda (name)
(with-current-buffer (get-buffer-create name)
(insert "#+title: " name "\n\n")
(org-mode)
(consult--buffer-action (current-buffer))))
:items
(lambda ()
(consult--buffer-query :mode 'org-mode :as #'consult--buffer-pair))))
(add-to-list 'consult-buffer-sources 'org-source 'append)
One can create similar sources for other major modes. See the
Consult wiki (https://github.com/minad/consult/wiki) for many additional
source examples. See also the documentation of ‘consult-buffer’ and of
the internal ‘consult--multi’ API. The function ‘consult--multi’ can be
used to create new multi-source commands.
File: doc2UPoKa.info, Node: Embark integration, Prev: Multiple sources, Up: Special features
2.5 Embark integration
======================
*NOTE*: Install the ‘embark-consult’ package from MELPA, which provides
Consult-specific Embark actions and the Occur buffer export.
Embark is a versatile package which offers context dependent actions,
comparable to a context menu. See the Embark manual
(https://github.com/oantolin/embark) for an extensive description of its
capabilities.
Actions are commands which can operate on the currently selected
candidate (or target in Embark terminology). When completing files, for
example the ‘delete-file’ command is offered. With Embark you can
execute arbitrary commands on the currently selected candidate via
‘M-x’.
Furthermore Embark provides the ‘embark-collect’ command, which
collects candidates and presents them in an Embark collect buffer, where
further actions can be applied to them. A related feature is the
‘embark-export’ command, which exports candidate lists to a buffer of a
special type. For example in the case of file completion, a Dired
buffer is opened.
In the context of Consult, particularly exciting is the possibility
to export the matching lines from ‘consult-line’, ‘consult-outline’,
‘consult-mark’ and ‘consult-global-mark’. The matching lines are
exported to an Occur buffer where they can be edited via the
‘occur-edit-mode’ (press key ‘e’). Similarly, Embark supports exporting
the matches found by ‘consult-grep’, ‘consult-ripgrep’ and
‘consult-git-grep’ to a Grep buffer, where the matches across files can
be edited, if the wgrep (https://github.com/mhayashi1120/Emacs-wgrep)
package is installed. These three workflows are symmetric.
• ‘consult-line’ -> ‘embark-export’ to ‘occur-mode’ buffer ->
‘occur-edit-mode’ for editing of matches in buffer.
• ‘consult-grep’ -> ‘embark-export’ to ‘grep-mode’ buffer -> ‘wgrep’
for editing of all matches.
• ‘consult-find’ -> ‘embark-export’ to ‘dired-mode’ buffer ->
‘wdired-change-to-wdired-mode’ for editing.
File: doc2UPoKa.info, Node: Configuration, Next: Recommended packages, Prev: Special features, Up: Top
3 Configuration
***************
Consult can be installed from ELPA
(https://elpa.gnu.org/packages/consult.html) or MELPA
(https://melpa.org/#/consult) via the Emacs built-in package manager.
Alternatively it can be directly installed from the development
repository via other non-standard package managers.
There is the Consult wiki (https://github.com/minad/consult/wiki),
where additional configuration examples can be contributed.
*IMPORTANT:* It is recommended that you enable lexical binding
(https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html)
in your configuration. Many Consult-related code snippets require
lexical binding, since they use lambdas and closures.
* Menu:
* Use-package example:: Configuration example based on use-package
* Custom variables:: Short description of all customization settings
* Project support:: Project discovery support for search commands
* Fine-tuning:: Fine-grained configuration for special requirements
File: doc2UPoKa.info, Node: Use-package example, Next: Custom variables, Up: Configuration
3.1 Use-package example
=======================
The Consult package only provides commands and does not add any
keybindings or modes. Therefore the package is non-intrusive but
requires a little setup effort. While the configuration example is
long, it consists essentially of key bindings only, such that the risk
of interference with other Emacs functionality is minimized.
In order to use the Consult commands, it is recommended to add
keybindings for commands which are accessed often. Rarely used commands
can be invoked via ‘M-x’. Feel free to only bind the commands you
consider useful to your workflow. The configuration shown here relies
on the ‘use-package’ macro, which is a convenient tool to manage package
configurations.
*NOTE:* There is the Consult wiki
(https://github.com/minad/consult/wiki), where you can contribute
additional configuration examples.
;; Example configuration for Consult
(use-package consult
;; Replace bindings. Lazily loaded by `use-package'.
:bind (;; C-c bindings in `mode-specific-map'
("C-c M-x" . consult-mode-command)
("C-c h" . consult-history)
("C-c k" . consult-kmacro)
("C-c m" . consult-man)
("C-c i" . consult-info)
([remap Info-search] . consult-info)
;; C-x bindings in `ctl-x-map'
("C-x M-:" . consult-complex-command) ;; orig. repeat-complex-command
("C-x b" . consult-buffer) ;; orig. switch-to-buffer
("C-x 4 b" . consult-buffer-other-window) ;; orig. switch-to-buffer-other-window
("C-x 5 b" . consult-buffer-other-frame) ;; orig. switch-to-buffer-other-frame
("C-x t b" . consult-buffer-other-tab) ;; orig. switch-to-buffer-other-tab
("C-x r b" . consult-bookmark) ;; orig. bookmark-jump
("C-x p b" . consult-project-buffer) ;; orig. project-switch-to-buffer
;; Custom M-# bindings for fast register access
("M-#" . consult-register-load)
("M-'" . consult-register-store) ;; orig. abbrev-prefix-mark (unrelated)
("C-M-#" . consult-register)
;; Other custom bindings
("M-y" . consult-yank-pop) ;; orig. yank-pop
;; M-g bindings in `goto-map'
("M-g e" . consult-compile-error)
("M-g f" . consult-flymake) ;; Alternative: consult-flycheck
("M-g g" . consult-goto-line) ;; orig. goto-line
("M-g M-g" . consult-goto-line) ;; orig. goto-line
("M-g o" . consult-outline) ;; Alternative: consult-org-heading
("M-g m" . consult-mark)
("M-g k" . consult-global-mark)
("M-g i" . consult-imenu)
("M-g I" . consult-imenu-multi)
;; M-s bindings in `search-map'
("M-s d" . consult-find) ;; Alternative: consult-fd
("M-s c" . consult-locate)
("M-s g" . consult-grep)
("M-s G" . consult-git-grep)
("M-s r" . consult-ripgrep)
("M-s l" . consult-line)
("M-s L" . consult-line-multi)
("M-s k" . consult-keep-lines)
("M-s u" . consult-focus-lines)
;; Isearch integration
("M-s e" . consult-isearch-history)
:map isearch-mode-map
("M-e" . consult-isearch-history) ;; orig. isearch-edit-string
("M-s e" . consult-isearch-history) ;; orig. isearch-edit-string
("M-s l" . consult-line) ;; needed by consult-line to detect isearch
("M-s L" . consult-line-multi) ;; needed by consult-line to detect isearch
;; Minibuffer history
:map minibuffer-local-map
("M-s" . consult-history) ;; orig. next-matching-history-element
("M-r" . consult-history)) ;; orig. previous-matching-history-element
;; Enable automatic preview at point in the *Completions* buffer. This is
;; relevant when you use the default completion UI.
:hook (completion-list-mode . consult-preview-at-point-mode)
;; The :init configuration is always executed (Not lazy)
:init
;; Tweak the register preview for `consult-register-load',
;; `consult-register-store' and the built-in commands. This improves the
;; register formatting, adds thin separator lines, register sorting and hides
;; the window mode line.
(advice-add #'register-preview :override #'consult-register-window)
(setq register-preview-delay 0.5)
;; Use Consult to select xref locations with preview
(setq xref-show-xrefs-function #'consult-xref
xref-show-definitions-function #'consult-xref)
;; Configure other variables and modes in the :config section,
;; after lazily loading the package.
:config
;; Optionally configure preview. The default value
;; is 'any, such that any key triggers the preview.
;; (setq consult-preview-key 'any)
;; (setq consult-preview-key "M-.")
;; (setq consult-preview-key '("S-<down>" "S-<up>"))
;; For some commands and buffer sources it is useful to configure the
;; :preview-key on a per-command basis using the `consult-customize' macro.
(consult-customize
consult-theme :preview-key '(:debounce 0.2 any)
consult-ripgrep consult-git-grep consult-grep consult-man
consult-bookmark consult-recent-file consult-xref
consult--source-bookmark consult--source-file-register
consult--source-recent-file consult--source-project-recent-file
;; :preview-key "M-."
:preview-key '(:debounce 0.4 any))
;; Optionally configure the narrowing key.
;; Both < and C-+ work reasonably well.
(setq consult-narrow-key "<") ;; "C-+"
;; Optionally make narrowing help available in the minibuffer.
;; You may want to use `embark-prefix-help-command' or which-key instead.
;; (keymap-set consult-narrow-map (concat consult-narrow-key " ?") #'consult-narrow-help)
)
File: doc2UPoKa.info, Node: Custom variables, Next: Project support, Prev: Use-package example, Up: Configuration
3.2 Custom variables
====================
*TIP:* If you have Marginalia (https://github.com/minad/marginalia)
installed, type ‘M-x customize-variable RET ^consult’ to see all
Consult-specific customizable variables with their current values and
abbreviated description. Alternatively, type ‘C-h a ^consult’ to get an
overview of all Consult variables and functions with their descriptions.
Variable Description
-----------------------------------------------------------------------------------------
consult-after-jump-hook Functions to call after jumping to a location
consult-async-input-debounce Input debounce for asynchronous commands
consult-async-input-throttle Input throttle for asynchronous commands
consult-async-min-input Minimum numbers of input characters
consult-async-refresh-delay Refresh delay for asynchronous commands
consult-async-split-style Splitting style used for async commands
consult-async-split-styles-alist Available splitting styles used for async commands
consult-async-indicator Async indicator characters
consult-bookmark-narrow Narrowing configuration for ‘consult-bookmark’
consult-buffer-filter Filter for ‘consult-buffer’
consult-buffer-sources List of virtual buffer sources
consult-fd-args Command line arguments for fd
consult-find-args Command line arguments for find
consult-fontify-max-size Buffers larger than this limit are not fontified
consult-fontify-preserve Preserve fontification for line-based commands.
consult-git-grep-args Command line arguments for git-grep
consult-goto-line-numbers Show line numbers for ‘consult-goto-line’
consult-grep-max-columns Maximal number of columns of the matching lines