embark - Emacs Mini-Buffer Actions Rooted in Keymaps

This package provides a pairs of commands, embark-act and embark-exit-and-act, to execute actions on the top minibuffer completion canidate: the one that would be chosen by minibuffer-force-complete. Additionally, embark-act can act on the completion candidate at point in the completions buffer. You should bind both of them in minibuffer-local-completion-map and also bind embark-act in completion-list-mode-map.

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.

But for additional convenience, embark-act also activates an extra keymap for you, where you can bind commonly used actions to single keys. There is a keymap for each “type” of completion. By default embark recognizes the following types of completion: file names, buffers and symbols (used for functions, variables and commands). The classification is configurable, see the variable embark-classifiers.

For any given type there is a corresponding keymap as noted in embark-keymap-alist. For example, for the completion category file, by default the corresponding keymap is embark-file-map. In this keymap you can bind normal commands you might want to use on file names. For example, by default embark-file-map binds delete-file to “d”, rename-file to “r” and copy-file to “c”, among other bindings.

The default keymaps that come with embark all set embark-general-map as their parent, so that the actions bound there 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.

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.

Showing a reminder of available actions

If you wish to see a reminder of which actions are available, you can install which-key and use which-key-mode with the which-key-show-transient-maps variable set to t. You may want to unclutter the display by removing all of the keybindings for the universal prefix arguments, namely C-u and the digits and minus (as well as their numeric keypad counterparts):

(push '(("^[0-9-]\\|kp-[0-9]\\|kp-subtract\\|C-u$" . nil) . ignore)
      which-key-replacement-alist)

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))