Emacs Docs

Appearance

Working with sets of possible targets ​

Besides acting individually on targets, Embark lets you work collectively on a set of target candidates. For example, while you are in the minibuffer the candidates are simply the possible completions of your input. Embark provides three main commands to work on candidate sets:

  • The ‘embark-act-all’ command runs the same action on each of the current candidates. It is just like using ‘embark-act’ on each candidate in turn. (Because you can easily act on many more candidates than you meant to, by default Embark asks you to confirm uses of ‘embark-act-all’; you can turn this off by setting the user option ‘embark-confirm-act-all’ to ‘nil’.)

  • The ‘embark-collect’ command produces a buffer listing all the current candidates, for you to peruse and run actions on at your leisure. The candidates are displayed as a list showing additional annotations. If any of the candidates contain newlines, then horizontal lines are used to separate candidates.

    The Embark Collect buffer is somewhat "dired-like": you can select and deselect candidates through ‘embark-select’ (available as an action in ‘embark-act’, bound to ‘SPC’; but you could also give it a global key binding). In an Embark Collect buffer ‘embark-act’ is bound to ‘a’ and ‘embark-act-all’ is bound to ‘A’; ‘embark-act-all’ will act on all currently marked candidates if there any, and will act on all candidates if none are marked. In particular, this means that ‘a SPC’ will toggle whether the candidate at point is selected, and ‘A SPC’ will select all candidates if none are selected, or deselect all selected candidates if there are some.

  • The ‘embark-export’ command tries to open a buffer in an appropriate major mode for the set of candidates. If the candidates are files export produces a Dired buffer; if they are buffers, you get an Ibuffer buffer; and if they are packages you get a buffer in package menu mode.

    If you use the grepping commands from the Consult package, ‘consult-grep’, ‘consult-git-grep’ or ‘consult-ripgrep’, then you should install the ‘embark-consult’ package, which adds support for exporting a list of grep results to an honest grep-mode buffer, on which you can even use wgrep if you wish.

When in doubt choosing between exporting and collecting, a good rule of thumb is to always prefer ‘embark-export’ since when an exporter to a special major mode is available for a given type of target, it will be more featureful than an Embark collect buffer, and if no such exporter is configured the ‘embark-export’ command falls back to the generic ‘embark-collect’.

These commands are always available as "actions" (although they do not act on just the current target but on all candidates) for ‘embark-act’ and are bound to ‘A’, ‘S’ (for "snapshot"), and ‘E’, respectively, in ‘embark-general-map’. This means that you do not have to bind your own key bindings for these (although you can, of course!), just a key binding for ‘embark-act’.

In Embark Collect or Embark Export buffers that were obtained by running ‘embark-collect’ or ‘embark-export’ from within a minibuffer completion session, ‘g’ is bound to a command that restarts the completion session, that is, the command that opened the minibuffer is run again and the minibuffer contents restored. You can then interact normally with the command, perhaps editing the minibuffer contents, and, if you wish, you can rerun ‘embark-collect’ or ‘embark-export’ to get an updated buffer.