---

4.2 Defining Transients ¶

A transient consists of a prefix command and at least one suffix command, though usually a transient has several infix and suffix commands. The below macro defines the transient prefix command and binds the transient’s infix and suffix commands. In other words, it defines the complete transient, not just the transient prefix command that is used to invoke that transient.

Macro: transient-define-prefix name arglist [docstring] [keyword value]... group... [body...] ¶

This macro defines NAME as a transient prefix command and binds the transient’s infix and suffix commands.

ARGLIST are the arguments that the prefix command takes. DOCSTRING is the documentation string and is optional.

These arguments can optionally be followed by keyword-value pairs. Each key has to be a keyword symbol, either :class or a keyword argument supported by the constructor of that class. The transient-prefix class is used if the class is not specified explicitly.

GROUPs add key bindings for infix and suffix commands and specify how these bindings are presented in the menu buffer. At least one GROUP has to be specified. See Binding Suffix and Infix Commands.

The BODY is optional. If it is omitted, then ARGLIST is ignored and the function definition becomes:

(lambda ()
  (interactive)
  (transient-setup 'NAME))

If BODY is specified, then it must begin with an interactive form that matches ARGLIST, and it must call transient-setup. It may, however, call that function only when some condition is satisfied.

All transients have a (possibly nil) value, which is exported when suffix commands are called, so that they can consume that value. For some transients it might be necessary to have a sort of secondary value, called a “scope”. Such a scope would usually be set in the command’s interactive form and has to be passed to the setup function:

(transient-setup 'NAME nil nil :scope SCOPE)

For example, the scope of the magit-branch-configure transient is the branch whose variables are being configured.

Sometimes multiple prefix commands share a common set of suffixes. For example, while magit-diff (d) and magit-diff-refresh (D) offer different suffixes to actually create or update a diff, they both offer the same infix arguments to control how that diff is formatted. Such shared groups should be defined using transient-define-group and then included in multiple prefixes, by using the symbol that identifies the group in the prefix definition, in a location where you would otherwise use a group vector. If an included group is placed at the top-level of a prefix (as opposed of inside inside a vector as a child group), then the symbol should be quoted.

Macro: transient-define-group name group... ¶

This macro define one or more groups and stores them in symbol NAME. GROUPs have the same form as for transient-define-prefix.