Consult

The excellent Consult package provides many commands that use minibuffer completion, via the ‘completing-read’ function; plenty of its commands can be considered enhanced versions of built-in Emacs commands, and some are completely new functionality. One common enhancement provided in all commands for which it makes sense is preview functionality, for example ‘consult-buffer’ will show you a quick preview of a buffer before you actually switch to it.

If you use both Consult and Embark you should install the ‘embark-consult’ package which provides integration between the two. It provides exporters for several Consult commands and also tweaks the behavior of many Consult commands when used as actions with ‘embark-act’ in subtle ways that you may not even notice, but make for a smoother experience. You need only install it to get these benefits: Embark will automatically load it after Consult if found.

The ‘embark-consult’ package provides the following exporters:

• You can use ‘embark-export’ from ‘consult-line’, ‘consult-outline’, or ‘consult-mark’ to obtain an ‘occur-mode’ buffer. As with the built-in ‘occur’ command you use that buffer to jump to a match and after that, you can then use ‘next-error’ and ‘previous-error’ to navigate to other matches. You can also press ‘e’ to activate ‘occur-edit-mode’ and edit the matches in place!
• You can export from any of the Consult asynchronous search commands, ‘consult-grep’, ‘consult-git-grep’, or ‘consult-ripgrep’ to get a ‘grep-mode’ buffer. Here too you can use ‘next-error’ and ‘previous-error’ to navigate among matches, and, if you install the wgrep package, you can use it to edit the matches in place.

In both cases, pressing ‘g’ will rerun the Consult command you had exported from and re-enter the input you had typed (which is similar to reverting but a little more flexible). You can then proceed to re-export if that’s what you want, but you can also edit the input changing the search terms or simply cancel if you see you are done with that search.

The ‘embark-consult’ also contains some candidates collectors that allow you to run ‘embark-live’ to get a live-updating table of contents for your buffer:

• ‘embark-consult-outline-candidates’ produces the outline headings of the current buffer, using ‘consult-outline’.
• ‘embark-consult-imenu-candidates’ produces the imenu items of the current buffer, using ‘consult-imenu’.
• ‘embark-consult-imenu-or-outline-candidates’ is a simple combination of the two previous functions: it produces imenu items in buffers deriving from ‘prog-mode’ and otherwise outline headings.

The way to configure ‘embark-live’ (or ‘embark-collect’ and ‘embark-export’ for that matter) to use one of these function is to add it at the end of the ‘embark-candidate-collectors’ list. The ‘embark-consult’ package by default adds the last one, which seems to be the most sensible default.

Besides those exporters and candidate collectors, the ‘embark-consult’ package provides many subtle tweaks and small integrations between Embark and Consult. Some examples are:

• When used as actions, the asynchronous search commands will search only the files associated to the targets: if the targets are files, it searches those files; for buffers it will search either the associated file if there is one, else all files in the buffer’s ‘default-directory’; for bookmarks it will search the file they point to, same for Emacs Lisp libraries. This is particularly powerful when using ‘embark-act-all’ to act on multiple files at once, for example you can use ‘consult-find’ to search among file names and then ‘embark-act-all’ and ‘consult-grep’ to search within the matching files.
  • For all other target types, those that do not have a sensible notion of associated file, a Consult search command (asynchronous or not) will search for the text of the target but leave the minibuffer open so you can interact with the Consult command.
• ‘consult-imenu’ will search for the target and take you directly to the location if it matches a unique imenu entry, otherwise it will leave the minibuffer open so you can navigate among the matches.