+title: Repeat-Help: Key descriptions for Emacs' Repeat Mode

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 [[https://github.com/oantolin/embark#showing-information-about-available-targets-and-actions][Embark indicator]] or a [[https://github.com/justbur/emacs-which-key/][Which Key]] popup:

Embark & Which Key popups: Repeating =diff-hl= commands

+html:

Embark & Which Key popups: Repeating =outline= navigation commands

+html:

For most keymaps, this is simpler, easier and more consistent than defining a custom [[https://github.com/abo-abo/hydra][Hydra]] or [[https://github.com/magit/transient][Transient]] interface (see Alternatives section for [[https://gitlab.com/jjzmajic/hercules.el][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:

+html:

For an introduction to Emacs' =repeat-mode= (including more demos), see [[https://karthinks.com/software/it-bears-repeating][this write-up]].

• Setup Requires Emacs 28 or higher.

Repeat-Help is available on MELPA. After [[https://github.com/melpa/melpa#usage][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.

** With =use-package=

+begin_src emacs-lisp

(use-package repeat-help :ensure t ;; or :straight t :hook (repeat-mode . repeat-help-mode))

+end_src

** Without =use-package= To use repeat-help with Emacs' repeat feature, run

+begin_src emacs-lisp

(add-hook 'repeat-mode-hook #'repeat-help-mode)

+end_src

• Usage 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~.

• Customization 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 a =completing-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 of =n → diff-hl-next-hunk=, and so on.

• Alternatives 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= and =embark-prefix-help-command= will show you available keys (optionally in a menu), but they end the repeat chain and you have to start over.

• [[https://gitlab.com/jjzmajic/hercules.el][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.

• [[https://github.com/abo-abo/hydra/][Hydra]] and [[https://github.com/magit/transient][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.