embark - Emacs Mini-Buffer Actions Rooted in Keymaps

Breaking news (that is, news about things breaking)

If you are already an Embark user and a recent update caused you to lose the package and symbol actions, install Marginalia, activate marginalia-mode and you should be good to go. If you want to read more about these changes see the last section.

Overview

Acting on targets

This package provides a sort of right-click contextual menu for Emacs, accessed through the embark-act command (which you should bind to a convenient key), offering you relevant actions to use on a target determined by the context:

• In the minibuffer, the target is the current best completion candidate.
• In the *Completions* buffer the target is the completion at point.
• In a regular buffer, the target is the region if active, or else the file, symbol or url at point.

The type of actions offered depend on the type of the target:

• For files you get offered actions like deleting, copying, renaming, visiting in another window, running a shell command on the file, etc.
• For buffers the actions include switching to or killing the buffer.
• For package names the actions include installing, removing or visiting the homepage.

If you want a reminder of which actions are available after running embark-act type C-h which will prompt you for an action with completion, and remind you of the keybindings.

Everything is easily configurable: determining the current target, classifying it, and deciding which actions are offered for each type in the classification. The above introduction just mentions part of the default configuration.

Configuring which actions are offered for a type is particulary easy and requires no programming: the variable embark-keymap-alist associates target types with variables containing keymaps, and those keymaps containing binds for the actions. For example, in the default configuration the type file is associated with the symbol embark-file-keymap. That symbol names a keymap with single-letter keybindings for common Emacs file commands, for instance c is bound to copy-file. This means that if you are in the minibuffer after running a command that prompts for a file, such as find-file or rename-file, you can copy a file by running embark-act and then pressing c.

These action keymaps are very convenient but not strictly necessary when using embark-act: you can use any command that reads from the minibuffer as an action and the target of the action will be inserted at the first minibuffer prompt. After running embark-act all of your keybindings and even execute-extended-command can be used to run a command.

The actions in embark-general-map are available no matter what type of completion you are in the middle of. By default this includes bindings to save the current candidate in the kill ring and to insert the current candidate in the previously selected buffer (the buffer that was current when you executed a command that opened up the minibuffer).

You can read about the default actions and their keybindings on the GitHub project wiki.

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 two commands to work on candidate sets:

• The embark-occur command produces a buffer listing all candidates, for you to peruse and run actions on at your leisure. The candidates can be viewed in a grid or as a list showing additional annotations. The embark-live-occur variant produces “live” Embark Occur buffers, meaning they autoupdate as the set of candidates changes.
• 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.

These 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 O, L 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 or embark-act-noexit.

Configuration

Showing a reminder of available actions

If you want a reminder of which actions are available after running embark-act, use embark-heymap-help, which is bound to C-h in all of embark’s action keymaps. That command will prompt you for the name of an action with completion (but feel free to enter a command not among the offered candidates!), and will also remind you of the keybindings.

If you find you prefer entering actions that way, you can configure embark to always prompt you for actions with the embark-prompt-style to the symbol completion.

If you want to see the actions and their key bindings, but want to use the keybindings rather than completing the command name, you can read how to configure which-key to show embark actions on the project wiki.

Allowing the target to be edited before acting on it

By default, for most commands embark inserts the target of the action into the next minibuffer prompt and “presses RET” for you, accepting the target as is.

For some commands this might be undesirable, either for safety (because a command is “hard to undo”, like delete-file or kill-buffer), or because further input is required next to the target (like when using shell-command: the target is the file and you still need to enter a shell command to run on it, at the same prompt). You can add such commands to the embark-allow-edit-commands variable (which by default already contains the examples mentioned, and a few others as well).

Now, automatically pressing RET for most commands is only the default. If you set the variable embark-allow-edit-default to t, then embark will instead give you a chance to edit the target before acting upon it, for all commands except those listed in embark-skip-edit-commands.

Running some setup after injecting the target

You can customize what happens after the target is inserted at the minibuffer prompt of an action. There is a hook, embark-setup-hook, that is run by default after injecting the target into the minibuffer. This hook can be overidden for specific action commands by associating the command to the desired overriding hook in embark-setup-overrides.

For example, consider using shell-command as an action during file completion. It would be useful to insert a space before the target file name and to leave the point at the beginning, so you can immediately type the shell command. That’s why in embark’s default configuration there is an entry in embark-setup-overrides associating shell-command to embark--shell-prep, a simple helper command that quotes all the spaces in the file name, inserts an extra space at the beginning of the line and leaves point to the left of it.

Actions that do not read from the minibuffer

You can also write your own commands that do not read from the minibuffer but act on the current target anyway: just use the embark-target function (exactly once!: it “self-destructs”) to retrieve the current target. See the definitions of embark-insert or embark-save for examples.

Creating your own keymaps

All internal keymaps are generated by a helper function embark-keymap that you can use it to generate keymaps for new categories in embark-keymap-alist or for any other purpose! For example a simple version of the file action keymap coud be defined as follows:

(defvar embark-file-map
  (embark-keymap
   '(("d" . delete-file)
     ("r" . rename-file)
     ("c" . copy-file))
   embark-general-map))

Embark, Marginalia and Consult

Some changes are being made to Embark, to better cooperate with the Marginalia and Consult packages, and prior to being submitted to MELPA. You may wish to hold off on updating Embark, or, help me out by updating aggresively and filing issue reports here on GitHub.

Neither of those packages is a dependency of Embark, but Marginalia is highly recommended, for reasons explained in the rest of this section

Embark comes with actions for symbols (commands, functions, variables with actions such as finding the definition, looking up the documentation, evaluating, etc.) in the embark-symbol-map keymap, and for packages (actions like install, delete, browse url, etc.) in the embark-package-keymap.

Unfortunately Embark no longer automatically offers you these keymaps when relevant, because many built-in Emacs commands don’t report accurate category metadata. For example, a command like describe-package, which reads a package name from the minibuffer, does not have metadata indicating so.

Previously Embark had functions to supply this missing metadata, but they have been moved to Marginalia, which augments many Emacs command to report accurate category metadata. Simply activating marginalia-mode allows Embark to offer you the package and symbol actions when appropriate again.

All annotation functions have been removed from Embark and moved to Marginalia (where they have been improved!). Embark used these old annotation functions for the list view in Embark Occur buffers.

• If you install Marginalia and activate marginalia-mode, the list view in Embark Occur buffers will use the Marginalia annotations automatically.
• If you don’t install Marginalia, you will see only the annotations that come with Emacs (such as keybindings in M-x, or the unicode characters in C-x 8 RET).

Other small changes:

• If you have Consult installed and call embark-occur from consult-line, consult-mark or consult-outline, you will notice the Embark Occur buffer starts in list view by default.
• The function embark-open-externally has been removed following the policy of avoiding overlap with Consult. If you used that action, add the small function to your configuration or install Consult and use consult-file-externally.