2.9 Configuration

More options are described in Common Suffix Commands, in Saving Values, in Using History and in Enabling and Disabling Suffixes.

Essential Options

Also see Common Suffix Commands.

User Option: transient-show-popup

This option controls whether the current transient’s infix and suffix commands are shown in the popup buffer.

  • If t (the default) then the popup buffer is shown as soon as a transient prefix command is invoked.
  • If nil, then the popup buffer is not shown unless the user explicitly requests it, by pressing an incomplete prefix key sequence.
  • If a number, then the a brief one-line summary is shown instead of the popup buffer. If zero or negative, then not even that summary is shown; only the pressed key itself is shown.

    The popup is shown when the user explicitly requests it by pressing an incomplete prefix key sequence. Unless this is zero, the popup is shown after that many seconds of inactivity (using the absolute value).

User Option: transient-enable-popup-navigation

This option controls whether navigation commands are enabled in the transient popup buffer.

While a transient is active the transient popup buffer is not the current buffer, making it necessary to use dedicated commands to act on that buffer itself. This is disabled by default. If this option is non-nil, then the following features are available:

  • UP moves the cursor to the previous suffix.
  • DOWN moves the cursor to the next suffix.
  • RET invokes the suffix the cursor is on.
  • mouse-1 invokes the clicked on suffix.
  • C-s and C-r start isearch in the popup buffer.
User Option: transient-display-buffer-action

This option specifies the action used to display the transient popup buffer. The transient popup buffer is displayed in a window using (display-buffer BUFFER transient-display-buffer-action).

The value of this option has the form (FUNCTION . ALIST), where FUNCTION is a function or a list of functions. Each such function should accept two arguments: a buffer to display and an alist of the same form as ALIST. See (elisp)Choosing Window, for details.

The default is:

(display-buffer-in-side-window
  (side . bottom)
  (inhibit-same-window . t)
  (window-parameters (no-other-window . t)))

This displays the window at the bottom of the selected frame. Another useful FUNCTION is display-buffer-below-selected, which is what magit-popup used by default. For more alternatives see (elisp)Buffer Display Action Functions, and see (elisp)Buffer Display Action Alists.

Note that the buffer that was current before the transient buffer is shown should remain the current buffer. Many suffix commands act on the thing at point, if appropriate, and if the transient buffer became the current buffer, then that would change what is at point. To that effect inhibit-same-window ensures that the selected window is not used to show the transient buffer.

It may be possible to display the window in another frame, but whether that works in practice depends on the window-manager. If the window manager selects the new window (Emacs frame), then that unfortunately changes which buffer is current.

If you change the value of this option, then you might also want to change the value of transient-mode-line-format.

Accessibility Options

User Option: transient-force-single-column

This option controls whether the use of a single column to display suffixes is enforced. This might be useful for users with low vision who use large text and might otherwise have to scroll in two dimensions.

Auxiliary Options

User Option: transient-mode-line-format

This option controls whether the transient popup buffer has a mode-line, separator line, or neither.

If nil, then the buffer has no mode-line. If the buffer is not displayed right above the echo area, then this probably is not a good value.

If line (the default), then the buffer also has no mode-line, but a thin line is drawn instead, using the background color of the face transient-separator. Text-mode frames cannot display thin lines, and therefore fall back to treating line like nil.

Otherwise this can be any mode-line format. See (elisp)Mode Line Format, for details.

User Option: transient-semantic-coloring

This option controls whether prefixes and suffixes are colored in a Hydra-like fashion.

If non-nil, then the key binding of each suffix is colorized to indicate whether it exits the transient state or not. The color of the prefix is indicated using the line that is drawn when the value of transient-mode-line-format is line.

For more information about how Hydra uses colors see https://github.com/abo-abo/hydra#color and https://oremacs.com/2015/02/19/hydra-colors-reloaded.

User Option: transient-highlight-mismatched-keys

This option controls whether key bindings of infix commands that do not match the respective command-line argument should be highlighted. For other infix commands this option has no effect.

When this option is non-nil, the key binding for an infix argument is highlighted when only a long argument (e.g., --verbose) is specified but no shorthand (e.g., -v). In the rare case that a shorthand is specified but the key binding does not match, then it is highlighted differently.

Highlighting mismatched key bindings is useful when learning the arguments of the underlying command-line tool; you wouldn’t want to learn any short-hands that do not actually exist.

The highlighting is done using one of the faces transient-mismatched-key and transient-nonstandard-key.

User Option: transient-substitute-key-function

This function is used to modify key bindings. If the value of this option is nil (the default), then no substitution is performed.

This function is called with one argument, the prefix object, and must return a key binding description, either the existing key description it finds in the key slot, or the key description that replaces the prefix key. It could be used to make other substitutions, but that is discouraged.

For example, = is hard to reach using my custom keyboard layout, so I substitute ( for that, which is easy to reach using a layout optimized for lisp.

(setq transient-substitute-key-function
      (lambda (obj)
        (let ((key (oref obj key)))
          (if (string-match "\\`\\(=\\)[a-zA-Z]" key)
              (replace-match "(" t t key 1)
            key))))
User Option: transient-read-with-initial-input

This option controls whether the last history element is used as the initial minibuffer input when reading the value of an infix argument from the user. If nil, there is no initial input and the first element has to be accessed the same way as the older elements.

User Option: transient-hide-during-minibuffer-read

This option controls whether the transient buffer is hidden while user input is being read in the minibuffer.

User Option: transient-align-variable-pitch

This option controls whether columns are aligned pixel-wise in the popup buffer.

If this is non-nil, then columns are aligned pixel-wise to support variable-pitch fonts. Keys are not aligned, so you should use a fixed-pitch font for the transient-key face. Other key faces inherit from that face unless a theme is used that breaks that relationship.

This option is intended for users who use a variable-pitch font for the default face.

User Option: transient-force-fixed-pitch

This option controls whether to force the use of a monospaced font in popup buffer. Even if you use a proportional font for the default face, you might still want to use a monospaced font in transient’s popup buffer. Setting this option to t causes default to be remapped to fixed-pitch in that buffer.

Developer Options

These options are mainly intended for developers.

User Option: transient-detect-key-conflicts

This option controls whether key binding conflicts should be detected at the time the transient is invoked. If so, this results in an error, which prevents the transient from being used. Because of that, conflicts are ignored by default.

Conflicts cannot be determined earlier, i.e., when the transient is being defined and when new suffixes are being added, because at that time there can be false-positives. It is actually valid for multiple suffixes to share a common key binding, provided the predicates of those suffixes prevent that more than one of them is enabled at a time.

User Option: transient-highlight-higher-levels

This option controls whether suffixes that would not be available by default are highlighted.

When non-nil then the descriptions of suffixes are highlighted if their level is above 4, the default of transient-default-level. Assuming you have set that variable to 7, this highlights all suffixes that won’t be available to users without them making the same customization.