forked from minad/consult
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathconsult.texi
1287 lines (1125 loc) · 51.5 KB
/
consult.texi
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
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename consult.info
@settitle consult.el - Consulting completing-read
@documentencoding UTF-8
@documentlanguage en
@c %**end of header
@dircategory Emacs
@direntry
* Consult: (consult). Useful commands built on completing-read.
@end direntry
@finalout
@titlepage
@title consult.el - Consulting completing-read
@author Daniel Mendler
@end titlepage
@contents
@ifnottex
@node Top
@top consult.el - Consulting completing-read
@end ifnottex
@menu
* Introduction:: Why Consult?
* 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
* Contributions:: Feature requests and pull requests
* Acknowledgements:: Contributors and Sources of Inspiration
* Indices:: Indices of concepts and functions
@detailmenu
--- 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 errors:: Jumping to compilation errors
* Histories:: Navigating histories
* Modes:: Toggling minor modes and executing commands
* 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
* Fine-tuning:: Fine-grained configuration for special requirements
Indices
* Function index:: List of all Consult commands
* Concept index:: List of all Consult-specific concepts
@end detailmenu
@end menu
@node Introduction
@chapter Introduction
@cindex introduction
Consult provides various handy commands based on the Emacs completion function
@uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html, completing-read}, which allows to quickly select an item from a list of
candidates with completion. Consult offers in particular a more advanced buffer
switching command @samp{consult-buffer} to switch to buffers and recently opened
files. Various search commands are provided, like an asynchronous
@samp{consult-grep}, and @samp{consult-line}, which resembles @uref{https://github.com/abo-abo/swiper#swiper, Swiper} or @uref{https://github.com/emacsorphanage/helm-swoop, Helm-Swoop}. Some
of the offered commands are greatly enhanced versions of existing Emacs
commands. For example the command @samp{consult-imenu} presents a flat list of the
Imenu with @ref{Live previews, , live preview} and @ref{Narrowing and grouping, , narrowing support}. Please take a look at the @ref{Available commands, , full
list of commands}.
All Consult commands are compatible with completion systems based on the
standard Emacs @samp{completing-read} API, notably the default completion system,
@uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html, Icomplete}, @uref{https://github.com/raxod502/selectrum, Selectrum} and @uref{https://github.com/oantolin/embark/, Embark}, with which Consult works out of the box. If
Icomplete is used, it is recommended to install @uref{https://github.com/oantolin/icomplete-vertical, Icomplete-vertical} to enjoy the
enhanced visuals. The completion system specifics in this package are kept to a
minimum. The ability of the Consult commands to work well with arbitrary
completion systems is one of 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. Note that, if you use @uref{https://github.com/abo-abo/swiper#ivy, Ivy} or @uref{https://github.com/emacs-helm/helm, Helm}, you
probably don't need Consult, since both packages come with their own set of
commands.
There are the @uref{https://github.com/minad/marginalia/, Marginalia} and @uref{https://github.com/oantolin/embark/, Embark} packages, which can be combined with
Consult. Marginalia enriches the completion display with annotations, for
example documentation strings or file information. The versatile Embark packages
provides local actions, comparable to a context menu, which can be executed
while selecting a candidate in the minibuffer or in other contexts. For example,
when selecting from a list of files, it offers an action to delete the file.
Additionally Embark can also be used as a completion system by itself through
its live-updating completion buffer. The @ref{Embark integration} is described later
in greater detail.
@node Available commands
@chapter Available commands
@cindex commands
Most provided commands follow the meaningful naming scheme @samp{consult-<thing>}.
@strong{TIP:} If you have @uref{https://github.com/minad/marginalia, Marginalia} installed and heavy annotators enabled, type @samp{M-x
^consult} to see all Consult commands with their abbreviated description.
Alternatively, type @samp{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 errors:: Jumping to compilation errors
* Histories:: Navigating histories
* Modes:: Toggling minor modes and executing commands
* Miscellaneous:: Various other useful commands
@end menu
@node Virtual Buffers
@section Virtual Buffers
@cindex virtual buffers
@findex consult-buffer
@findex consult-buffer-other-window
@findex consult-buffer-other-frame
@findex consult-recent-file
@findex consult-bookmark
@itemize
@item
@samp{consult-buffer} (@samp{-other-window}, @samp{-other-frame}): Enhanced version
of @samp{switch-to-buffer} with support for virtual buffers. Supports live preview
of buffers and narrowing to the virtual buffer types. You can type @samp{f SPC} in
order to narrow to recent files. Ephemeral buffers can be shown by pressing
@samp{SPC} - it works the same way as @samp{switch-buffer}. Supported narrowing keys:
@itemize
@item
b Buffers
@item
f Files
@item
m Bookmarks
@item
p Project (only available if @samp{consult-project-root-function} is
configured as shown in the @ref{Use-package example, , example configuration}).
@item
Arbitrary @ref{Multiple sources, , other sources} can be configured via @samp{consult-buffer-sources}.
@end itemize
By default only buffers are preview in order to ensure that @samp{consult-buffer}
is fast, but it is possible to @ref{Multiple sources, , configure} file and bookmark preview.
@item
@samp{consult-bookmark}: Select or create bookmark. You might use the
powerful @samp{consult-buffer} as an alternative, which can include a bookmark
virtual buffer source. But note that @samp{consult-bookmark} supports preview of
bookmarks and narrowing.
@item
@samp{consult-recent-file}: Select from recent files with preview.
You might prefer the powerful @samp{consult-buffer} instead, which can include
recent files as a virtual buffer source.
@end itemize
@node Editing
@section Editing
@cindex editing
@findex consult-yank
@findex consult-kmacro
@itemize
@item
@samp{consult-yank}, @samp{consult-yank-pop}: Enhanced version of @samp{yank} and
@samp{yank-pop} which allows selecting from the kill-ring. Live preview is
supported when selecting from the kill-ring.
@item
@samp{consult-kmacro}: Select macro from the macro ring and execute it.
@end itemize
@node Register
@section Register
@cindex register
@findex consult-register
@findex consult-register-load
@findex consult-register-store
@findex consult-register-format
@findex consult-register-window
@itemize
@item
@samp{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 it is
recommended to use @samp{consult-register-load} or @samp{consult-register-store} or the
built-in Emacs register commands.
@item
@samp{consult-register-format}: Supplementary register formatting function which can be
used as @samp{register-preview-function} for an enhanced register formatting. See
the @ref{Use-package example, , example configuration}.
@item
@samp{consult-register-window}: Supplementary function which can be used
as replacement for @samp{register-preview} for a better register window. See the
@ref{Use-package example, , example configuration}.
@item
@samp{consult-register-load}: Utility command to quickly load a register.
The command either jumps to the register value or inserts it.
@item
@samp{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:
@itemize
@item
@samp{M-' x}: If no region is active, store point in register @samp{x}.
If a region is active, store the region in register @samp{x}.
@item
@samp{M-' M-w x}: Store window configuration in register @samp{x}.
@item
@samp{C-u 100 M-' x}: Store number in register @samp{x}.
@end itemize
@end itemize
@node Navigation
@section Navigation
@cindex navigation
@findex consult-goto-line
@findex consult-mark
@findex consult-global-mark
@findex consult-outline
@findex consult-imenu
@findex consult-project-imenu
@itemize
@item
@samp{consult-goto-line}: Jump to line number enhanced with live preview.
This is a drop-in replacement for @samp{goto-line}.
@item
@samp{consult-mark}: Jump to a marker in the @samp{mark-ring}. Supports live
preview and recursive editing.
@item
@samp{consult-global-mark}: Jump to a marker in the @samp{global-mark-ring}.
Supports live preview and recursive editing.
@item
@samp{consult-outline}: Jump to a heading of the outline. Supports live
preview and recursive editing.
@item
@samp{consult-imenu}: Jump to imenu item in the current buffer. Supports
live preview, recursive editing and narrowing.
@item
@samp{consult-project-imenu}: 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
@uref{https://github.com/vspinu/imenu-anywhere, imenu-anywhere}.
@end itemize
@node Search
@section Search
@cindex search
@findex consult-line
@findex consult-multi-occur
@findex consult-keep-lines
@findex consult-focus-lines
@findex consult-isearch
@itemize
@item
@samp{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 @samp{M-n}. When @samp{consult-line} is bound to the @samp{isearch-mode-map} and
is invoked during a running Isearch, it will use the current Isearch string.
@item
@samp{consult-isearch}: 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 to pick a string from the
history and starts a new Isearch. This command can be used as a drop-in
replacement for @samp{isearch-edit-string}.
@item
@samp{consult-multi-occur}: Replacement for @samp{multi-occur} which uses
@samp{completing-read-multiple}.
@item
@samp{consult-keep-lines}: Replacement for @samp{keep/flush-lines}
which uses the current completion style for filtering the buffer. The
function updates the buffer while typing. In particular, this function can be
used to further narrow an exported Embark collect buffer with the same
completion filtering as during @samp{completing-read}. If the input begins with
the negation operator, i.e., @code{! SPC}, the filter matches the complement. If a
region is active, the filtering is restricted to that region.
@item
@samp{consult-focus-lines}: Temporarily hide lines by filtering them using the current
completion style. Call with @samp{C-u} prefix argument in order to show the hidden
lines again. If the input begins with the negation operator, i.e., @code{! SPC},
the filter matches the complement. In contrast to @samp{consult-keep-lines} this
function does not edit the buffer. If a region is active, the focusing is
restricted to that region.
@end itemize
@node Grep and Find
@section Grep and Find
@cindex grep
@cindex find
@cindex locate
@findex consult-grep
@findex consult-ripgrep
@findex consult-git-grep
@findex consult-find
@findex consult-locate
@itemize
@item
@samp{consult-grep}, @samp{consult-ripgrep}, @samp{consult-git-grep}: Search for
regular expression in files. Grep is invoked asynchronously, while you enter
the search term. You are required to enter at least @samp{consult-async-min-input}
characters in order for the search to get started. The input string is split
into two parts, if the first character is a punctuation character, like @samp{#}.
For example @samp{#grep-regexp#filter-string}, is split at the second @samp{#}. The
string @samp{grep-regexp} is passed to Grep, the @samp{filter-string} is passed to the
@emph{fast} Emacs filtering to further narrow down the list of matches. This is
particularily useful if you are using an advanced completion style like
orderless. @samp{consult-grep} supports preview. If the
@samp{consult-project-root-function} is @ref{Use-package example, , configured} and returns non-nil,
@samp{consult-grep} searches the current project directory. Otherwise the
@samp{default-directory} is searched. If @samp{consult-grep} is invoked with prefix
argument @samp{C-u M-s g}, you can specify the directory manually.
@item
@samp{consult-find}, @samp{consult-locate}: Find file by
matching the path against a regexp. Like @samp{consult-grep} either the project
root or the current directory is used as root directory for the search. The
input string is treated similarly to @samp{consult-grep}, where the first part is
passed to find, and the second part is used for Emacs filtering. Note that
the standard @samp{find} command uses wildcards in contrast to the popular @samp{fd},
which uses regular expressions. In case you want to use @samp{fd}, you can either
change the @samp{consult-find-command} configuration variable or define a small
command as described in the @uref{https://github.com/minad/consult/wiki, Consult wiki}.
@end itemize
@node Compilation errors
@section Compilation errors
@cindex compilation errors
@findex consult-compile-error
@findex consult-flycheck
@findex consult-flymake
@itemize
@item
@samp{consult-compile-error}: Jump to a compilation error. Supports live preview
narrowing and and recursive editing.
@item
@samp{consult-flycheck}: Jump to flycheck error. Supports live preview and
recursive editing. The command supports narrowing. Press @samp{e SPC},
@samp{w SPC}, @samp{i SPC} to only show errors, warnings and infos respectively.
This command requires to install the additional @samp{consult-flycheck.el}
package since the main @samp{consult.el} package only depends on Emacs core
components.
@item
@samp{consult-flymake}: Jump to Flymake diagnostic, like @samp{consult-flycheck}.
@end itemize
@node Histories
@section Histories
@cindex history
@findex consult-complex-command
@findex consult-history
@itemize
@item
@samp{consult-complex-command}: Select a command from the
@samp{command-history}. This command is a @samp{completing-read} version of
@samp{repeat-complex-command} and can also be considered a replacement for
the @samp{command-history} command from chistory.el.
@item
@samp{consult-history}: Insert a string from the current buffer history.
This command can be invoked from the minibuffer. In that case the
history stored in the @samp{minibuffer-history-variable} is used.
@end itemize
@node Modes
@section Modes
@cindex minor mode
@cindex major mode
@findex consult-minor-mode-menu
@findex consult-mode-command
@itemize
@item
@samp{consult-minor-mode-menu}: Enable/disable minor mode. Supports
narrowing to on/off/local/global modes by pressing @samp{i/o/l/g SPC}
respectively.
@item
@samp{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 @samp{l/g/m}.
@end itemize
@node Miscellaneous
@section Miscellaneous
@findex consult-apropos
@findex consult-file-externally
@findex consult-completion-in-region
@findex consult-theme
@findex consult-man
@findex consult-xref
@itemize
@item
@samp{consult-apropos}: Replacement for @samp{apropos} with completion.
@item
@samp{consult-man}: Find Unix man page, via Unix @samp{apropos} or @samp{man -k}.
The selected man page is opened using the Emacs @samp{man} command.
@item
@samp{consult-file-externally}: Select a file and open it externally,
e.g. using @samp{xdg-open} on Linux.
@item
@samp{consult-completion-in-region}: Function which can be used as
@samp{completion-in-region-function}. This way, the minibuffer completion
UI will be used for @samp{completion-at-point}. This function is
particularily useful in combination with Icomplete-vertical, since
Icomplete does not provide its own @samp{completion-in-region-function}. In
contrast, Selectrum already comes with its own function.
@item
@samp{consult-theme}: Select a theme and disable all currently enabled
themes. Supports live preview of the theme while scrolling through the
candidates.
@item
@samp{consult-xref}: Integration with xref. This function can be set as
as @samp{xref-show-xrefs-function} and @samp{xref-show-definitions-function}.
@end itemize
@node Special features
@chapter Special features
Consult enhances @samp{completing-read} with live previews of candidates, additional
narrowing capabilities to candidate groups and asynchronously generated
candidate lists. This functionality is provided by the internal @samp{consult--read}
function, which is used by most Consult commands. The @samp{consult--read} function
is a thin wrapper around @samp{completing-read}. In order to support multiple
candidate sources there exists the high-level function @samp{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
@end menu
@node Live previews
@section Live previews
@cindex preview
Some Consult commands support live previews. For example when you scroll
through the items of @samp{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.
Previews are enabled by default but can be disabled via the
@samp{consult-preview-key} variable. Furthermore it is possible to specify
keybindings which trigger the preview manually as shown in the @ref{Use-package example, , example
configuration}. The default setting of @samp{consult-preview-key} is @samp{any} which
means that the preview will be triggered on any keypress when the selected
candidate changes. Each command can be configured individually with its own
@samp{:preview-key}, such that preview can be manual for some commands, for some
commands automatic and for some commands completely disabled.
@node Narrowing and grouping
@section Narrowing and grouping
@cindex narrowing
Consult has special support for candidate groups which are separated by
separator lines with titles if supported by the completion system. As of now,
Selectrum and Icomplete-vertical provide support. This functionality is useful
if the list of candidates consists of candidates of multiple types or
candidates from @ref{Multiple sources, , multiple sources}, like the @samp{consult-buffer} command, which
shows both buffers and recently opened files. Note that the group titles can be
disabled by setting the @samp{:title} property of the corresponding command in the
@samp{consult-config} configuration alist to nil.
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 @samp{consult-buffer} command, you can enter the prefix @samp{b SPC} and the list of
candidates will be restricted to buffers only. If you press @samp{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 @samp{consult-narrow-key} and
@samp{consult-widen-key}.
If @uref{https://github.com/justbur/emacs-which-key, which-key} is installed, the narrowing keys are shown in the which-key window
after pressing the prefix key @samp{consult-narrow-key}. Furthermore there is the
@samp{consult-narrow-help} command which can be bound to a key in the
@samp{consult-narrow-map} if this is desired, as shown in the @ref{Use-package example, , example configuration}.
@node Asynchronous search
@section Asynchronous search
@cindex asynchronous search
Consult has support for asynchronous generation of candidate lists. This
feature is used for search commands like @samp{consult-grep}, where the list of
matches is generated dynamically while the user is typing a grep regular
expression. The grep process is executed in the background. When modifying the
grep 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
@samp{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. The input string is split at a punctuation character, using a
similar syntax as Perl regular expressions.
Examples:
@itemize
@item
@samp{#defun}: Search for "defun" using grep.
@item
@samp{#defun#consult}: Search for "defun" using grep, filter with the word
"consult".
@item
@samp{/defun/consult}: It is also possible to use other punctuation
characters.
@item
@samp{#to#}: Force searching for "to" using grep, since the grep pattern
must be longer than @samp{consult-async-min-input} characters by default.
@item
@samp{#defun -- --invert-match#}: Pass argument @samp{--invert-match} to grep.
@end itemize
For asynchronous processes like @samp{find} and @samp{grep}, the prompt has a small
indicator showing the process status:
@itemize
@item
@samp{:} the usual prompt colon, before input is provided.
@item
@samp{*} with warning face, the process is running.
@item
@samp{:} with success face, success, process exited with an error code of zero.
@item
@samp{!} with error face, failure, process exited with a nonzero error code.
@item
@samp{;} with error face, interrupted, for example if more input is provided.
@end itemize
There is an ephemeral error log buffer @samp{_*consult-async-log*} (note the leading space),
you can access the buffer using @samp{consult-buffer} and @samp{switch-to-buffer} by first pressing @samp{SPC}
and then selecting the buffer.
@node Multiple sources
@section Multiple sources
@cindex multiple sources
Consult allows combining multiple synchronous candidate sources. This feature
is used by the @samp{consult-buffer} command to present buffer-like candidates in a
single menu for quick access. By default @samp{consult-buffer} includes buffers,
bookmarks, recent files and project-specific buffers and files. It is possible
to configure the list of sources via the @samp{consult-buffer-sources} variable.
Arbitrary custom sources can be defined.
As an example, the bookmark source is defined as follows:
@lisp
(defvar consult--source-bookmark
`(:name "Bookmark"
:narrow ?m
:category bookmark
:face consult-bookmark
:history bookmark-history
:items ,#'bookmark-all-names
:action ,#'consult--bookmark-action))
@end lisp
Required source fields:
@itemize
@item
@samp{:category} Completion category.
@item
@samp{:items} List of strings to select from or function returning list of strings.
@end itemize
Optional source fields:
@itemize
@item
@samp{:name} Name of the source, used for narrowing, group titles and annotations.
@item
@samp{:narrow} Narrowing character or @samp{(character . string)} pair.
@item
@samp{:enabled} Function which must return t if the source is enabled.
@item
@samp{:hidden} When t candidates of this source are hidden by default.
@item
@samp{:face} Face used for highlighting the candidates.
@item
@samp{:annotate} Annotation function called for each candidate, returns string.
@item
@samp{:history} Name of history variable to add selected candidate.
@item
@samp{:default} Must be t if the first item of the source is the default value.
@item
@samp{:action} Action function called with the selected candidate.
@item
@samp{:state} State constructor for the source, must return the state function.
@item
Other source fields can be added specifically to the use case.
@end itemize
The @samp{:state} and @samp{:action} fields of the sources deserve a longer explanation.
The @samp{: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 @samp{:state} field is more complicated and general. The @samp{:state} function is a
constructor function without arguments, which can perform some setup
necessary for the preview. It must return a closure with two arguments: The
first argument is the candidate string, the second argument is the restore
flag. The state function is called during preview, if a preview key has been
pressed, with the selected candidate or nil and the restore argument being
nil. Furthermore the state function is always called after selection with the
selected candidate or nil. The state function is called with nil for the
candidate if for example the selection process has been aborted or if the
original preview state should be restored during preview. The restore flag is
t for the final call. The final call happens even if preview is disabled. For
this reason you can also use the final call to the state function in a similar
way as @samp{:action}. You probably only want to specify both @samp{:state} and
@samp{:action} if @samp{:state} is purely responsible for preview and @samp{:action} is then
responsible for the real action after selection.
In order to avoid slowness, @samp{consult-buffer} only preview buffers by default.
Loading recent files, bookmarks or views can result in expensive operations.
However it is possible to configure the bookmark and file sources to also
perform preview.
@lisp
(nconc consult--source-bookmark (list :state #'consult--bookmark-preview))
(nconc consult--source-file (list :state #'consult--file-preview))
(nconc consult--source-project-file (list :state #'consult--file-preview))
@end lisp
Sources can be added directly to the @samp{consult-buffer-source} list for
convenience. For example views can be added to the list of virtual buffers
from a library like @uref{https://github.com/minad/bookmark-view/}.
@lisp
;; Configure new bookmark-view source
(add-to-list 'consult-buffer-sources
(list :name "View"
:narrow ?v
:category 'bookmark
:face 'font-lock-keyword-face
:history 'bookmark-view-history
:action #'consult--bookmark-jump
:items #'bookmark-view-names)
'append)
;; Modify bookmark source, such that views are hidden
(setq consult--source-bookmark
(plist-put
consult--source-bookmark :items
(lambda ()
(bookmark-maybe-load-default-file)
(mapcar #'car
(seq-remove (lambda (x)
(eq #'bookmark-view-handler
(alist-get 'handler (cdr x))))
bookmark-alist)))))
@end lisp
Other useful sources allow the creation of terminal and eshell
buffers if they do not exist yet.
@lisp
(defun mode-buffer-exists-p (mode)
(seq-some (lambda (buf)
(provided-mode-derived-p
(buffer-local-value 'major-mode buf)
mode))
(buffer-list)))
(defvar eshell-source
`(:category 'consult-new
:face 'font-lock-constant-face
:action ,(lambda (_) (eshell))
:items
,(lambda ()
(unless (mode-buffer-exists-p 'eshell-mode)
'("*eshell* (new)")))))
(defvar term-source
`(:category 'consult-new
:face 'font-lock-constant-face
:action
,(lambda (_)
(ansi-term (or (getenv "SHELL") "/bin/sh")))
:items
,(lambda ()
(unless (mode-buffer-exists-p 'term-mode)
'("*ansi-term* (new)")))))
(add-to-list 'consult-buffer-sources 'eshell-source 'append)
(add-to-list 'consult-buffer-sources 'term-source 'append)
@end lisp
For more details, see the documentation of @samp{consult-buffer} and of the
internal @samp{consult--multi} API@. The @samp{consult--multi} function can be used to
create new multi-source commands, but is part of the internal API as of now,
since some details may still change.
@node Embark integration
@section Embark integration
@cindex embark
@strong{NOTE}: Install the @samp{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 @uref{https://github.com/oantolin/embark, Embark manual} 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
@samp{delete-file} command is offered. Embark also allows to to execute arbitrary
commands on the currently selected candidate via @samp{M-x}.
Furthermore Embark provides the @samp{embark-collect-snapshot} 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
@samp{embark-export} command, which allows to export 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, particularily exciting is the possibility to export
the matching lines from @samp{consult-line}, @samp{consult-outline}, @samp{consult-mark} and
@samp{consult-global-mark}. The matching lines are exported to an Occur buffer where
they can be edited via the @samp{occur-edit-mode} (press key @samp{e}). Similarily,
Embark supports exporting the matches found by @samp{consult-grep},
@samp{consult-ripgrep} and @samp{consult-git-grep} to a Grep buffer, where the matches
across files can be edited, if the @uref{https://github.com/mhayashi1120/Emacs-wgrep, wgrep} package is installed.
@node Configuration
@chapter Configuration
Consult can be installed from @uref{https://melpa.org/, MELPA} via the Emacs built-in package manager.
Alternatively it can be directly installed from the development repository via
other non-standard package managers.
Note that there are two packages as of now: @samp{consult} and @samp{consult-flycheck}.
@samp{consult-flycheck} is a separate package such that the core @samp{consult} package
only depends on Emacs core components. The @samp{consult} package will work out of
the box with the default completion, Icomplete and Selectrum.
There is the @uref{https://github.com/minad/consult/wiki, Consult wiki}, where additional configuration examples can be
contributed.
@strong{IMPORTANT:} It is strongly recommended that you enable @uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html, lexical binding} in your
configuration. Consult uses a functional programming style, relying on lambdas
and lexical closures. For this reason many Consult-related snippets require
lexical binding.
@menu
* Use-package example:: Configuration example based on use-package
* Custom variables:: Short description of all customization settings
* Fine-tuning:: Fine-grained configuration for special requirements
@end menu
@node Use-package example
@section Use-package example
@cindex use-package
It is recommended to manage package configurations with the @samp{use-package} macro.
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. In order to use the Consult commands, it is advised to add keybindings
for commands which are accessed often. Rarely used commands can be invoked via
@samp{M-x}. Feel free to only bind the commands you consider useful to your workflow.
@strong{NOTE:} There is the @uref{https://github.com/minad/consult/wiki, Consult wiki}, where additional configuration examples can be
contributed.
@lisp
;; Example configuration for Consult
(use-package consult
;; Replace bindings. Lazily loaded due by `use-package'.
:bind (;; C-c bindings (mode-specific-map)
("C-c h" . consult-history)
("C-c m" . consult-mode-command)
("C-c b" . consult-bookmark)
("C-c k" . consult-kmacro)
;; C-x bindings (ctl-x-map)
("C-x M-:" . consult-complex-command) ;; orig. repeat-complet-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
;; 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
("<help> a" . consult-apropos) ;; orig. apropos-command
;; M-g bindings (goto-map)
("M-g e" . consult-compile-error)
("M-g g" . consult-goto-line) ;; orig. goto-line
("M-g M-g" . consult-goto-line) ;; orig. goto-line
("M-g o" . consult-outline)
("M-g m" . consult-mark)
("M-g k" . consult-global-mark)
("M-g i" . consult-imenu)
("M-g I" . consult-project-imenu)
;; M-s bindings (search-map)
("M-s f" . consult-find)
("M-s L" . 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 m" . consult-multi-occur)
("M-s k" . consult-keep-lines)
("M-s u" . consult-focus-lines)
;; Isearch integration
("M-s e" . consult-isearch)
:map isearch-mode-map
("M-e" . consult-isearch) ;; orig. isearch-edit-string
("M-s e" . consult-isearch) ;; orig. isearch-edit-string
("M-s l" . consult-line)) ;; required by consult-line to detect isearch
;; The :init configuration is always executed (Not lazy)
:init
;; Optionally configure the register formatting. This improves the register
;; preview for `consult-register', `consult-register-load',
;; `consult-register-store' and the Emacs built-ins.
(setq register-preview-delay 0
register-preview-function #'consult-register-format)
;; Optionally tweak the register preview window.
;; This adds thin lines, sorting and hides the mode line of the window.
(advice-add #'register-preview :override #'consult-register-window)
;; 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. Note that the preview-key can also be
;; configured on a per-command basis via `consult-config'. The default value
;; is 'any, such that any key triggers the preview.
;; (setq consult-preview-key 'any)
;; (setq consult-preview-key (kbd "M-p"))
;; (setq consult-preview-key (list (kbd "<S-down>") (kbd "<S-up>")))
;; Optionally configure the narrowing key.
;; Both < and C-+ work reasonably well.
(setq consult-narrow-key "<") ;; (kbd "C-+")
;; Optionally make narrowing help available in the minibuffer.
;; Probably not needed if you are using which-key.
;; (define-key consult-narrow-map (vconcat consult-narrow-key "?") #'consult-narrow-help)
;; Optionally configure a function which returns the project root directory.
;; There are multiple reasonable alternatives to chose from:
;; * projectile-project-root
;; * vc-root-dir
;; * project-roots
;; * locate-dominating-file
(autoload 'projectile-project-root "projectile")
(setq consult-project-root-function #'projectile-project-root)
;; (setq consult-project-root-function
;; (lambda ()
;; (when-let (project (project-current))
;; (car (project-roots project)))))
;; (setq consult-project-root-function #'vc-root-dir)
;; (setq consult-project-root-function
;; (lambda () (locate-dominating-file "." ".git")))
)
;; Optionally add the `consult-flycheck' command.
(use-package consult-flycheck
:bind (:map flycheck-command-map
("!" . consult-flycheck)))
@end lisp
@node Custom variables
@section Custom variables
@cindex customization
@strong{TIP:} If you have @uref{https://github.com/minad/marginalia, Marginalia} installed, type @samp{M-x customize-variable RET
^consult} to see all Consult-specific customizable variables with their current
values and abbreviated description. Alternatively, type @samp{C-h a ^consult} to get
an overview of all Consult variables and functions with their descriptions.
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Variable
@tab Default
@tab Description
@item consult-after-jump-hook
@tab '(recenter)
@tab Functions to call after jumping to a location
@item consult-async-default-split
@tab "#"
@tab Separator character used for splitting #async#filter
@item consult-async-input-debounce
@tab 0.25
@tab Input debounce for asynchronous commands
@item consult-async-input-throttle
@tab 0.5
@tab Input throttle for asynchronous commands
@item consult-async-min-input
@tab 3
@tab Minimum numbers of letters needed for async process
@item consult-async-refresh-delay
@tab 0.25
@tab Refresh delay for asynchronous commands
@item consult-bookmark-narrow
@tab @dots{}
@tab Narrowing configuration for @samp{consult-bookmark}
@item consult-buffer-filter
@tab @dots{}
@tab Filter for @samp{consult-buffer}
@item consult-buffer-sources
@tab @dots{}
@tab List of virtual buffer sources
@item consult-completion-in-region-styles
@tab nil
@tab Completion styles used by @samp{consult-completion-in-region}
@item consult-config
@tab nil
@tab Invididual command option configuration
@item consult-find-command
@tab "find @dots{}"
@tab Command line arguments for find
@item consult-fontify-max-size
@tab 1048576
@tab Buffers larger than this limit are not fontified
@item consult-fontify-preserve
@tab t
@tab Preserve fontification for line-based commands.
@item consult-git-grep-command
@tab '(@dots{})
@tab Command line arguments for git-grep
@item consult-goto-line-numbers
@tab t
@tab Show line numbers for @samp{consult-goto-line}
@item consult-grep-max-colums
@tab 250
@tab Maximal number of columns of the matching lines
@item consult-grep-command
@tab "grep @dots{}"
@tab Command line arguments for grep
@item consult-imenu-config
@tab @dots{}
@tab Mode-specific configuration for @samp{consult-imenu}
@item consult-line-numbers-widen
@tab t
@tab Show absolute line numbers when narrowing is active.
@item consult-line-point-placement
@tab 'match-beginning
@tab Placement of the point used by @samp{consult-line}
@item consult-locate-command
@tab "locate @dots{}"
@tab Command line arguments for locate
@item consult-mode-command-filter