GNU ELPA - embark

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 top 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, URL, s-expression or defun at point.

Multiple targets can be present at the same location and you can cycle between them by repeating the embark-act key binding. The type of actions offered depend on the type of the target. Here is a sample of a few of the actions offered in the default configuration:

• 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.
• For Emacs Lisp symbols the actions include finding the definition, looking up documentation, evaluating (which for a variable immediately shows the value, but for a function lets you pass it some arguments first). There are some actions specific to variables, such as setting the value directly or though the customize system, and some actions specific to commands, such as binding it to a key.

By default when you use embark-act if you don't immediately select an action, after a short delay Embark will pop up a buffer showing a list of actions and their corresponding key bindings. If you are using embark-act outside the minibuffer, Embark will also highlight the current target. These behaviors are configurable via the variable embark-indicators. Instead of selecting an action via its key binding, you can select it by name with completion by typing C-h after embark-act.

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 particularly easy and requires no programming: the variable embark-keymap-alist associates target types with variables containing keymaps, and those keymaps containing bindings for the actions. (To examine the available categories and their associated keymaps, you can use C-h v embark-keymap-alist or customize that variable.) For example, in the default configuration the type file is associated with the symbol embark-file-map. That symbol names a keymap with single-letter key bindings 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 key bindings and even execute-extended-command can be used to run a command. For example, if you want to replace all occurrences of the symbol at point, just use M-% as the action, there is no need to bind query-replace in one of Embark's keymaps. Also, those action keymaps are normal Emacs keymaps and you should feel free to bind in them whatever commands you find useful as actions and want to be available through convenient bindings.

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

Emacs's minibuffer completion system includes metadata indicating the category of what is being completed. For example, find-file's metadata indicates a category of file and switch-to-buffer's metadata indicates a category of buffer. Embark has the related notion of the type of a target for actions, and by default when category metadata is present it is taken to be the type of minibuffer completion candidates when used as targets. Emacs commands often do not set useful category metadata so the Marginalia package, which supplies this missing metadata, is highly recommended for use with Embark.

Embark's default configuration has actions for the following target types: files, buffers, symbols, packages, URLs, bookmarks, and as a somewhat special case, actions for when the region is active. You can read about the default actions and their key bindings on the GitHub project wiki.

Embark has a notion of default action for a target:

• If the target is a minibuffer completion candidate, then the default action is whatever command opened the minibuffer in the first place. For example if you run kill-buffer, then the default action will be to kill buffers.
• If the target comes from a regular buffer (i.e., not a minibuffer), then the default action is whatever is bound to RET in the keymap of actions for that type of target. For example, in Embark's default configuration for a URL found at point the default action is browse-url, because RET is bound to browse-url in the embark-url-map keymap.

To run the default action you can press RET after running embark-act. Note that if there are several different targets at a given location, each has its own default action, so first cycle to the target you want and then press RET to run the corresponding default action.

There is also embark-dwim which runs the default action for the first target found. It's pretty handy in non-minibuffer buffers: with Embark's default configuration it will:

• Open the file at point.
• Open the URL at point in a web browser (using the browse-url command).
• Compose a new email to the email address at point.
• In an Emacs Lisp buffer, if point is on an opening parenthesis or right after a closing one, it will evaluate the corresponding expression.
• Go to the definition of an Emacs Lisp function, variable or macro at point.
• Find the file corresponding to an Emacs Lisp library at point.

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-snapshot command produces a buffer listing all the current 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-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'll probably want to install and load 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-snapshot.

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, 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.

There is also the embark-collect-live variant of embark-collect-snapshot which produces "live" Embark Collect buffers, meaning they auto-update as the set of candidates changes. Most users of visual completion UIs such as Vertico, Icomplete, Selectrum or Ivy will probably either not want to use this from the minibuffer, to avoid seeing double (the list of candidates is displayed both by Embark and by the completion UI), or to configure their completion UI to hide while using embark-collect-live. See the Embark wiki for sample configuration for Selectrum. This command can also be used outside the minibuffer if you have a relevant candidate collector registered in embark-candidate-collectors. Users of the embark-consult package, for example, get such a candidate collector registered for them, and can produce a live-updating table of contents for any buffer, whose items are the lines matching outline-regexp.

Embark also has the embark-become command which is useful for when you run a command, start typing at the minibuffer and realize you meant a different command. The most common case for me is that I run switch-to-buffer, start typing a buffer name and realize I haven't opened the file I had in mind yet! I'll use this situation as a running example to illustrate embark-become. When this happens I can, of course, press C-g and then run find-file and open the file, but this requires retyping the portion of the file name you already typed. This process can be streamlined with embark-become: while still in the switch-to-buffer you can run embark-become and effectively make the switch-to-buffer command become find-file for this run.

You can bind embark-become to a key in minibuffer-local-map, but it is also available as an action under the letter B (uppercase), so you don't need a binding if you already have one for embark-act. So, assuming I have embark-act bound to, say, C-., once I realize I haven't open the file I can type C-. B C-x C-f to have switch-to-buffer become find-file without losing what I have already typed in the minibuffer.

But for even more convenience, embark-become offers shorter key bindings for commands you are likely to want the current command to become. When you use embark-become it looks for the current command in all keymaps named in the list embark-become-keymaps and then activates all keymaps that contain it. For example, the default value of embark-become-keymaps contains a keymap embark-become-file+buffer-map with bindings for several commands related to files and buffers, in particular, it binds switch-to-buffer to b and find-file to f. So when I accidentally try to switch to a buffer for a file I haven't opened yet, embark-become finds that the command I ran, switch-to-buffer, is in the keymap embark-become-file+buffer-map, so it activates that keymap (and any others that also contain a binding for switch-to-buffer). The end result is that I can type C-. B f to switch to find-file.

By default, if you run embark-act and do not immediately select an action, after a short delay Embark will pop up a buffer called *Embark Actions* containing a list of available actions with their key bindings. You can scroll that buffer with the mouse of with the usual commands scroll-other-window and scroll-other-window-down (bound by default to C-M-v and C-M-S-v).

That functionality is provided by the embark-mixed-indicator, but Embark has other indicators that can provide information about the target and its type, what other targets you can cycle to, and which actions have key bindings in the action map for the current type of target. Any number of indicators can be active at once and the user option embark-indicators should be set to a list of the desired indicators.

Embark comes with the following indicators:

• embark-minimal-indicator: shows a messages in the echo area or minibuffer prompt showing the current target and the types of all targets starting with the current one; this one is on by default.
• embark-highlight-indicator: highlights the target at point; also on by default.
• embark-verbose-indicator: displays a table of actions and their key bindings in a buffer; this is not on by default, in favor of the mixed indicator described next.
• embark-mixed-indicator: starts out by behaving as the minimal indicator but after a short delay acts as the verbose indicator; this is on by default.
• embark-isearch-highlight-indicator: this only does something when the current target is the symbol at point, in which case it lazily highlights all occurrences of that symbol in the current buffer, like isearch; also on by default.

Users of the popular which-key package may prefer to use the embark-which-key-indicator from the Embark wiki. Just copy its definition from the wiki into your configuration and customize the embark-indicators user option to exclude the mixed and verbose indicators and to include embark-which-key-indicator.

As an alternative to reading the list of actions in the verbose or mixed indicators (see the previous section for a description of these), you can press the embark-help-key, which is C-h by default (but you may prefer ? to free up C-h for use as a prefix) after running embark-act. Pressing the help key will prompt you for the name of an action with completion (but feel free to enter a command that is not among the offered candidates!), and will also remind you of the key bindings. You can press embark-keymap-prompter-key, which is @ by default, at the prompt and then one of the key bindings to enter the name of the corresponding action.

You may think that with the *Embark Actions* buffer popping up to remind you of the key bindings you'd never want to use completion to select an action by name, but personally I find that typing a small portion of the action name to narrow down the list of candidates feels significantly faster than visually scanning the entire list of actions.

If you find you prefer entering actions that way, you can configure embark to always prompt you for actions by setting the variable embark-prompter to embark-completing-read-prompter.

By default, if you call embark-act from the minibuffer it quits the minibuffer after performing the action. You can change this by setting the user option embark-quit-after-action to nil. Having embark-act not quit the minibuffer can be useful to turn commands into little "thing managers". For example, you can use find-file as a little file manager or describe-package as a little package manager: you can run those commands, perform a series of actions, and then quit the command.

If you want to control the quitting behavior in a fine-grained manner depending on the action, you can set embark-quit-after-action to an alist, associating commands to either t for quitting or nil for not quitting. When using an alist, you can use the special key t to specify the default behavior. For example, to specify that by default actions should not quit the minibuffer but that using kill-buffer as an action should quit, you can use the following configuration:

(setq embark-quit-after-action '((kill-buffer . t) (t . nil)))

The variable embark-quit-after-action only specifies a default, that is, it only controls whether or not embark-act quits the minibuffer when you call it without a prefix argument, and you can select the opposite behavior to what the variable says by calling embark-act with C-u. Also note that both the variable embark-quit-after-action and C-u have no effect when you call embark-act outside the minibuffer.

If you find yourself using the quitting and non-quitting variants of embark-act about equally often, independently of the action, you may prefer to simply have separate commands for them instead of a single command that you call with C-u half the time. You could, for example, keep the default exiting behavior of embark-act and define a non-quitting version as follows:

(defun embark-act-noquit ()
  "Run action but don't quit the minibuffer afterwards."
  (interactive)
  (let ((embark-quit-after-action nil))
    (embark-act)))

You can customize what happens after the target is inserted at the minibuffer prompt of an action. There are embark-target-injection-hooks, that are run by default after injecting the target into the minibuffer. The variable embark-target-injection-hooks is an alist associating commands to their setup hooks. There are two special keys: if no setup hook is specified for a given action, the hook associated to t is run; and the hook associated to :always is run regardless of the action. (This variable used to have the less explicit name of embark-setup-action-hooks, so please update your configuration.)

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 to run on that file. That's why in Embark's default configuration there is an entry in embark-target-injection-hooks associating shell-command to a hook that includes embark--shell-prep, a simple helper function 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.

Now, the preparation that embark--shell-prep does would be useless if Embark did what it normally does after it inserts the target of the action at the minibuffer prompt, which is to "press RET" for you, accepting the target as is; if Embark did that for shell-command you wouldn't get a chance to type in the command to execute! That is why in Embark's default configuration the entry for shell-command in embark-target-injection-hooks also contains the function embark--allow-edit.

Embark used to have a dedicated variable embark-allow-edit-actions to which you could add commands for which Embark should forgo pressing RET for you after inserting the target. Since its effect can also be achieved via the general embark-target-injection-hooks mechanism, that variable has been removed to simply Embark. Be sure to update your configuration; if you had something like:

(add-to-list 'embark-allow-edit-actions 'my-command)

you should replace it with:

(push 'embark--allow-edit
      (alist-get 'my-command embark-target-injection-hooks))

Also note that while you could abuse embark--allow-edit so that you have to confirm "dangerous" actions such as delete-file, it is better to implement confirmation by adding the embark--confirm function to the appropriate entry of a different hook alist, namely, embark-pre-action-hooks.

Besides embark--allow-edit, Embark comes with another function that is of general utility in action setup hooks: embark--ignore-target. Use it for commands that do prompt you in the minibuffer but for which inserting the target would be inappropriate. This is not a common situation but does occasionally arise. For example it is used by default for shell-command-on-region: that command is used as an action for region targets, and it prompts you for a shell command; you typically do not want the target, that is the contents of the region, to be entered at that prompt!

Embark has two variables, embark-pre-action-hooks and embark-post-action-hooks, which are alists associating commands to hooks that should run before or after the command is used as an action. As with, embark-target-injection-hooks, there are two special keys for the alists: t designates the default hook to run when no specific hook is specified for a command; and the hook associated to :always runs regardless.

The default values of those variables are fairly extensive, adding creature comforts to make running actions a smooth experience. Embark comes with several functions intended to be added to these hooks, and used in the default values of embark-pre-action-hooks and embark-post-action-hooks.

For pre-action hooks:

embark--confirm

Prompt the user for confirmation before executing the action. This is used be default for commands deemed "dangerous", or, more accurately, hard to undo, such as delete-file and kill-buffer.

embark--mark-target

Mark the target as an active region. Most targets at point outside the minibuffer report which region of the buffer they correspond to (this is the information used by embark-highlight-indicator to know what portion of the buffer to highlight); this function marks that region. It is useful as a pre action hook for commands that expect a region to be marked, for example, it is used by default for indent-region so that it works on s-expression targets, or for fill-region so that it works on paragraph targets.

embark--unmark-target

Unmark the active region. Use this for commands you want to act on the region contents but without the region being active. The default configuration uses this function as a pre-action hook for occur and query-replace, for example, so that you can use them as actions with region targets to search the whole buffer for the text contained in the region. Without this pre-action hook using occur as an action for a region target would be pointless: it would search for the the region contents in the region, (typically, due to the details of regexps) finding only one match!

embark--beginning-of-target

Move to the beginning of the target (for targets that report bounds). This is used by default for backward motion commands such as backward-sexp, so that they don't accidentally leave you on the current target.

embark--end-of-target

Move to the end of the target. This is used similarly to the previous function, but also for commands that act on the last s-expression like eval-last-sexp. This allow you to act on an s-expression from anywhere inside it and still use eval-last-sexp as an action.

embark--narrow-to-target

Narrow buffer to current target. Use this as a pre-action hook to localize the effect of actions that don't already work on just the region. In the default configuration it is used for repunctuate-sentences.

embark--xref-push-markers

Push the current location on the xref marker stack. Use this for commands that take you somewhere and for which you'd like to be able to come back to where you were using xref-pop-marker-stack. This is used by default for find-library.

For post-action hooks:

embark--restart

Restart the command currently prompting in the minibuffer, so that the list of completion candidates is updated. This is useful as a post action hook for commands that delete or rename a completion candidate; for example the default value of embark-post-action-hooks uses it for delete-file, kill-buffer, rename-file, rename-buffer, etc.

All internal keymaps are defined with a helper macro embark-define-keymap that you can use to define your own keymaps, whether they are for new categories in embark-keymap-alist or for any other purpose! For example a simple version of the file action keymap could be defined as follows:

(embark-define-keymap embark-file-map
  "Example keymap with a few file actions"
  ("d" delete-file)
  ("r" rename-file)
  ("c" copy-file))

Remember also that these action keymaps are perfectly normal Emacs keymaps, and do not need to be created with this helper macro. You can use the built-in define-key, or your favorite external package such as bind-key or general.el to manage them.

It is easy to configure Embark to provide actions for new types of targets, either in the minibuffer or outside it. I present below two very detailed examples of how to do this. At several points I'll explain more than one way to proceed, typically with the easiest option first. I include the alternative options since there will be similar situations where the easiest option is not available.

Alternatively, Embark does support one other type of action: a non-interactive function of a single argument. The target is passed as argument to the function. For example:

(defun example-action-function (target)
  (message "The target was `%s'." target))

(define-key embark-symbol-map "X4" #'example-action-function)

Note that normally binding non-interactive functions in a keymap is useless, since when attempting to run them using the key binding you get an error message similar to "Wrong type argument: commandp, example-action-function". In general it is more flexible to write any new Embark actions as commands, that is, as interactive functions, because that way you can also run them directly, without Embark. But there are a couple of reasons to use non-interactive functions as actions:

1. You may already have the function lying around, and it is convenient to simply reuse it.
2. For command actions the targets can only be simple string, with no text properties. For certain advanced uses you may want the action to receive a string with some text properties, or even a non-string target.