---

4.5 Transient State

Invoking a transient prefix command “activates” the respective transient, i.e., it puts a transient keymap into effect, which binds the transient’s infix and suffix commands.

The default behavior while a transient is active is as follows:

• Invoking an infix command does not affect the transient state; the transient remains active.
• Invoking a (non-infix) suffix command “deactivates” the transient state by removing the transient keymap and performing some additional cleanup.
• Invoking a command that is bound in a keymap other than the transient keymap is disallowed and trying to do so results in a warning. This does not “deactivate” the transient.

But these are just the defaults. Whether a certain command deactivates or “exits” the transient is configurable. There is more than one way in which a command can be “transient” or “non-transient”; the exact behavior is implemented by calling a so-called “pre-command” function. Whether non-suffix commands are allowed to be called is configurable per transient.

• The transient-ness of suffix commands (including infix commands) is controlled by the value of their transient slot, which can be set either when defining the command or when adding a binding to a transient while defining the respective transient prefix command.

  Valid values are booleans and the pre-commands described below.

  • t is equivalent to transient--do-stay.
  • nil is equivalent to transient--do-exit.
  • If transient is unbound (and that is actually the default for non-infix suffixes) then the value of the prefix’s transient-suffix slot is used instead. The default value of that slot is nil, so the suffix’s transient slot being unbound is essentially equivalent to it being nil.
• A suffix command can be a prefix command itself, i.e., a “sub-prefix”. While a sub-prefix is active we nearly always want C-g to take the user back to the “super-prefix”. However in rare cases this may not be desirable, and that makes the following complication necessary:

  For transient-suffix objects the transient slot is unbound. We can ignore that for the most part because, as stated above, nil and the slot being unbound are equivalent, and mean “do exit”. That isn’t actually true for suffixes that are sub-prefixes though. For such suffixes unbound means “do exit but allow going back”, which is the default, while nil means “do exit permanently”, which requires that slot to be explicitly set to that value.

• The transient-ness of certain built-in suffix commands is specified using transient-predicate-map. This is a special keymap, which binds commands to pre-commands (as opposed to keys to commands) and takes precedence over the transient slot.

The available pre-command functions are documented below. They are called by transient--pre-command, a function on pre-command-hook and the value that they return determines whether the transient is exited. To do so the value of one of the constants transient--exit or transient--stay is used (that way we don’t have to remember if t means “exit” or “stay”).

Additionally, these functions may change the value of this-command (which explains why they have to be called using pre-command-hook), call transient-export, transient--stack-zap or transient--stack-push; and set the values of transient--exitp, transient--helpp or transient--editp.

Pre-commands for Infixes

The default for infixes is transient--do-stay. This is also the only function that makes sense for infixes.

Function: transient--do-stay ¶

Call the command without exporting variables and stay transient.

Pre-commands for Suffixes

By default, invoking a suffix causes the transient to be exited.

If you want a different default behavior for a certain transient prefix command, then set its :transient-suffix slot. The value can be a boolean, answering the question "does the transient stay active, when a suffix command is invoked?" t means that the transient stays active, while nil means that invoking a suffix exits the transient. In either case, the exact behavior depends on whether the suffix is itself a prefix (i.e., a sub-prefix), an infix or a regular suffix.

The behavior for an individual suffix command can be changed by setting its transient slot to one of the following pre-commands.

Function: transient--do-exit ¶

Call the command after exporting variables and exit the transient.

Function: transient--do-return ¶

Call the command after exporting variables and return to parent prefix. If there is no parent prefix, then call transient--do-exit.

Function: transient--do-call ¶

Call the command after exporting variables and stay transient.

The following pre-commands are suitable for sub-prefixes. Only the first should ever explicitly be set as the value of the transient slot.

Function: transient--do-recurse ¶

Call the transient prefix command, preparing for return to active transient.

Whether we actually return to the parent transient is ultimately under the control of each invoked suffix. The difference between this pre-command and transient--do-replace is that it changes the value of the transient-suffix slot to transient--do-return.

If there is no parent transient, then only call this command and skip the second step.

Function: transient--do-replace ¶

Call the transient prefix command, replacing the active transient.

Unless transient--do-recurse is explicitly used, this pre-command is automatically used for suffixes that are prefixes themselves, i.e., for sub-prefixes.

Function: transient--do-suspend ¶

Suspend the active transient, saving the transient stack.

This is used by the command transient-suspend and optionally also by “external events” such as handle-switch-frame. Such bindings should be added to transient-predicate-map.

Pre-commands for Non-Suffixes

By default, non-suffixes (commands that are bound in other keymaps beside the transient keymap) cannot be invoked. Trying to invoke such a command results in a warning and the transient stays active.

If you want a different behavior, then set the :transient-non-suffix slot of the transient prefix command. The value can be a boolean, answering the question, "is it allowed to invoke non-suffix commands?"

If the value is t or transient--do-stay, then non-suffixes can be invoked, when it is nil or transient--do-warn (the default) then they cannot be invoked.

The only other recommended value is transient--do-leave. If that is used, then non-suffixes can be invoked, but if one is invoked, then that exits the transient.

Function: transient--do-warn ¶

Call transient-undefined and stay transient.

Function: transient--do-stay ¶

Call the command without exporting variables and stay transient.

Function: transient--do-leave ¶

Call the command without exporting variables and exit the transient.

Special Pre-Commands

Function: transient--do-quit-one ¶

If active, quit help or edit mode, else exit the active transient.

This is used when the user pressed C-g.

Function: transient--do-quit-all ¶

Exit all transients without saving the transient stack.

This is used when the user pressed C-q.

Function: transient--do-suspend ¶

Suspend the active transient, saving the transient stack.

This is used when the user pressed C-z.