-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME-elpa
1468 lines (1185 loc) · 63 KB
/
README-elpa
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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONSULT.EL - CONSULTING COMPLETING-READ
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Consult provides search and navigation commands based on the Emacs
completion function [completing-read]. 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 [live preview], [grouping and
narrowing]. Please take a look at the [full list of commands].
Consult is fully compatible with completion systems centered around the
standard Emacs `completing-read' API, notably the default completion
system, [Vertico], [Mct], and [Icomplete].
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], [Embark] and
[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 [Embark integration] documents in detail how Consult
and Embark work together.
Table of Contents
─────────────────
1. Available commands
.. 1. Virtual Buffers
.. 2. Editing
.. 3. Register
.. 4. Navigation
.. 5. Search
.. 6. Grep and Find
.. 7. Compilation
.. 8. Histories
.. 9. Modes
.. 10. Org Mode
.. 11. Help
.. 12. Miscellaneous
2. Special features
.. 1. Live previews
.. 2. Narrowing and grouping
.. 3. Asynchronous search
.. 4. Multiple sources
.. 5. Embark integration
3. Configuration
.. 1. Use-package example
.. 2. Custom variables
.. 3. Project support
.. 4. Fine-tuning
4. Recommended packages
5. Bug reports
6. Hacking
.. 1. Creating asynchronous completion commands
.. 2. Live preview
7. Contributions
8. Acknowledgments
9. Indices
.. 1. Function index
.. 2. Concept index
[completing-read]
<https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html>
[live preview] See section 2.1
[grouping and narrowing] See section 2.2
[full list of commands] See section 1
[Vertico] <https://github.com/minad/vertico>
[Mct] <https://github.com/protesilaos/mct>
[Icomplete]
<https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html>
[Marginalia] <https://github.com/minad/marginalia/>
[Embark] <https://github.com/oantolin/embark/>
[Orderless] <https://github.com/oantolin/orderless>
[Embark integration] See section 2.5
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] 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.
[Marginalia] <https://github.com/minad/marginalia>
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 [other 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.
[other sources] See section 2.4
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.
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 [example
configuration].
• `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'.
[example configuration] See section 3.1
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].
[imenu-anywhere] <https://github.com/vspinu/imenu-anywhere>
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.
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 [project directory] 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.
[project directory] See section 3.3
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'.
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]
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'.
[Cape] <https://github.com/minad/cape>
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'.
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.
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"))
└────
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] or
the default `*Completions*' UI.
• `consult-completion-in-region': In case you don't use [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] 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.
[Mct] <https://git.sr.ht/~protesilaos/mct>
[Corfu] <https://github.com/minad/corfu>
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.
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
[example configuration]. 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] and [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))
└────
[example configuration] See section 3.1
[org-modern] <https://github.com/minad/org-modern>
[hl-todo] <https://github.com/tarsius/hl-todo>
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
[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 [example
configuration]. If [which-key] is installed, the narrowing keys are
automatically shown in the which-key window after pressing the
`consult-narrow-key'.
[multiple sources] See section 2.4
[example configuration] See section 3.1
[which-key] <https://github.com/justbur/emacs-which-key>
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.
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] 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.
[Consult wiki] <https://github.com/minad/consult/wiki>
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] 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] 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.
[Embark manual] <https://github.com/oantolin/embark>
[wgrep] <https://github.com/mhayashi1120/Emacs-wgrep>
3 Configuration
═══════════════
Consult can be installed from [ELPA] or [MELPA] 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], where additional configuration examples
can be contributed.
*IMPORTANT:* It is recommended that you enable [lexical binding] in
your configuration. Many Consult-related code snippets require lexical
binding, since they use lambdas and closures.
[ELPA] <https://elpa.gnu.org/packages/consult.html>
[MELPA] <https://melpa.org/#/consult>
[Consult wiki] <https://github.com/minad/consult/wiki>
[lexical binding]
<https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html>
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], 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)
│ )
└────
[Consult wiki] <https://github.com/minad/consult/wiki>
3.2 Custom variables
────────────────────
*TIP:* If you have [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
consult-grep-args Command line arguments for grep
consult-imenu-config Mode-specific configuration for `consult-imenu'
consult-line-numbers-widen Show absolute line numbers when narrowing is active
consult-line-start-from-top Start the `consult-line' search from the top
consult-locate-args Command line arguments for locate
consult-man-args Command line arguments for man
consult-mode-command-filter Filter for `consult-mode-command'
consult-mode-histories Mode-specific history variables
consult-narrow-key Narrowing prefix key during completion
consult-point-placement Placement of the point when jumping to matches
consult-preview-key Keys which triggers preview
consult-preview-allowed-hooks List of hooks to allow during preview
consult-preview-excluded-buffers Predicate to exclude buffers from preview
consult-preview-excluded-files Regexps matched against file names during preview
consult-preview-max-count Maximum number of files to keep open during preview
consult-preview-partial-size Files larger than this size are previewed partially
consult-preview-partial-chunk Size of the file chunk which is previewed partially
consult-preview-variables Alist of variables to bind during preview
consult-project-buffer-sources List of virtual project buffer sources
consult-project-function Function which returns current project root
consult-register-prefix Prefix string for register keys during completion
consult-ripgrep-args Command line arguments for ripgrep
consult-themes List of themes to be presented for selection
consult-widen-key Widening key during completion
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━