Emacs 28+ includes a minor mode named repeat
that enables calling commands under a shared prefix key easily, without having to type in the prefix each time. So you can switch windows repeatedly with C-x o o o...
instead of C-x o C-x o C-x o...
, undo repeatedly with C-x u u u...
, jump through headings with n
and p
instead of C-c @ C-n
and C-c @ C-p
, and so on.
This package adds key a description popup when a “repeat map” is active, showing you the available keys and commands. This is available through a generic interface, with built-in support for an Embark indicator or a Which Key popup:
Embark & Which Key popups: Repeating diff-hl
commands
Embark & Which Key popups: Repeating outline
navigation commands
For most keymaps, this is simpler, easier and more consistent than defining a custom Hydra or Transient interface (see Alternatives section for Hercules). There is no separate “setup” phase: You activate the repeat functionality through the regular Emacs keybinding for the command. And no “dismiss” phase: the popup disappears when you do press a key (like typing text) that’s not included in the repeat map.
Here’s repeat-help
applied to the smerge-mode
keymap, which is used by Emacs when resolving Git conflicts. The window to the right lists the invoked keys:
repeat-help-smerge-which-key-demo.mp4
For an introduction to Emacs’ repeat-mode
(including more demos), see this write-up.
Requires Emacs 28 or higher.
Repeat-Help is available on MELPA. After adding MELPA to your package archives, you can install it by running M-x package-install⮐
repeat-help
in Emacs, or with the below use-package
block.
Alternatively: Clone this repository and call M-x package-install-from-file⮐
on the directory.
(use-package repeat-help
:ensure t ;; or :straight t
:hook (repeat-mode . repeat-help-mode))
To use repeat-help with Emacs’ repeat feature, run
(add-hook 'repeat-mode-hook #'repeat-help-mode)
To use this feature, turn on repeat-mode
(part of Emacs) and repeat-help-mode
.
By default, the persistent key description popup is available as a toggle bound to C-h
.
You can change the toggle key using the variable repeat-help-key
. If you want the popup to be automatic instead of a toggle, you can customize repeat-help-auto
.
Repeat-Help tries to use an Embark indicator by default, falling back on Which Key and the built-in echo area message system. To specify a backend you can customize repeat-help-popup-type
.
You can also plug in your own key description function into the interface. For example, it should be possible to:
- Tweak
embark-prefix-help-command
so you can select a command from acompleting-read
menu and then continue to use the repeat map. - Provide a which-key function with modified defaults that removes the leading part of each description, showing
n → next-hunk
instead ofn → diff-hl-next-hunk
, and so on.
There are many ways to create a temporary mode for quick access to a keymap. The Emacs API facilitates this through setting transient keymaps with set-transient-map
. For visual aid and to group together disparate commands, there are the following built-in commands and third party packages:
prefix-help-command
andembark-prefix-help-command
will show you available keys (optionally in a menu), but they end the repeat chain and you have to start over.- Hercules: Repeat-Help is closest in spirit to Hercules, which also uses existing keymaps as the basis for a repeat interface. This package is more basic in that it only augments the built-in
repeat-mode
functionality and does not provide any macros for defining custom behavior. - Hydra and Transient provide significantly more powerful interfaces for dispatching commands, but require explicit definitions with full key listings and lots of boilerplate. They’re well suited for more complicated tasks than repeating small sets of commands.
Repeat Mode with Repeat Help is not as powerful, but much simpler and more uniform as an extension of built-in functionality.