5.1 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 it binds the transient’s infix and suffix commands. In other works, it defines the complete transient, not just the transient prefix command that is used to invoke that transient.

Macro: define-transient-command 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 echo area. 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.