Taking inspiration from prefix keys and prefix arguments, Transient implements a similar abstraction involving a prefix command, infix arguments and suffix commands. We could call this abstraction a "transient command", but because it always involves at least two commands (a prefix and a suffix) we prefer to call it just a "transient".
Transient keymaps are a feature provided by Emacs. Transients as implemented by this package involve the use of transient keymaps.
Emacs provides a feature that it calls "prefix commands". When we talk about "prefix commands" in this manual, then we mean our own kind of "prefix commands", unless specified otherwise. To avoid ambiguity we sometimes use the terms "transient prefix command" for our kind and "regular prefix command" for Emacs’ kind.
When the user calls a transient prefix command, then a transient
(temporary) keymap is activated, which binds the transient’s infix and
suffix commands, and functions that control the transient state are
added to pre-command-hook and post-command-hook. The available suffix
and infix commands and their state are shown in a popup buffer until
the transient state is exited by invoking a suffix command.
Calling an infix command causes its value to be changed. How that is done depends on the type of the infix command. The simplest case is an infix command that represents a command-line argument that does not take a value. Invoking such an infix command causes the switch to be toggled on or off. More complex infix commands may read a value from the user, using the minibuffer.
Calling a suffix command usually causes the transient to be exited; the transient keymaps and hook functions are removed, the popup buffer no longer shows information about the (no longer bound) suffix commands, the values of some public global variables are set, while some internal global variables are unset, and finally the command is actually called. Suffix commands can also be configured to not exit the transient.
A suffix command can, but does not have to, use the infix arguments in
much the same way any command can choose to use or ignore the prefix
arguments. For a suffix command that was invoked from a transient the
variable transient-current-suffixes and the function transient-args
serve about the same purpose as the variables prefix-arg and
current-prefix-arg do for any command that was called after the prefix
arguments have been set using a command such as universal-argument.
The information shown in the popup buffer while a transient is active looks a bit like this:
,----------------------------------------- |Arguments | -f Force (--force) | -a Annotate (--annotate) | |Create | t tag | r release `-----------------------------------------
This is a simplified version of
magit-tag. Info manuals do not support images or colored text, so the above "screenshot" lacks some information; in practice you would be able to tell whether the arguments--forceand--annotateare enabled or not based on their color.
Transient can be used to implement simple "command dispatchers". The
main benefit then is that the user can see all the available commands
in a popup buffer. That is useful by itself because it frees the user
from having to remember all the keys that are valid after a certain
prefix key or command. Magit’s magit-dispatch (on C-x M-g) command is
an example of using Transient to merely implement a command
dispatcher.
In addition to that, Transient also allows users to interactively pass arguments to commands. These arguments can be much more complex than what is reasonable when using prefix arguments. There is a limit to how many aspects of a command can be controlled using prefix arguments. Furthermore what a certain prefix argument means for different commands can be completely different, and users have to read documentation to learn and then commit to memory what a certain prefix argument means to a certain command.
Transient suffix commands on the other hand can accept dozens of different arguments without the user having to remember anything. When using Transient, then one can call a command with arguments that are just as complex as when calling the same function non-interactively using code.
Invoking a transient command with arguments is similar to invoking a command in a shell with command-line completion and history enabled. One benefit of the Transient interface is that it remembers history not only on a global level ("this command was invoked using these arguments and previously it was invoked using those other arguments"), but also remembers the values of individual arguments independently. See Using History.
After a transient prefix command is invoked C-h <key> can be used to
show the documentation for the infix or suffix command that <key> is
bound to (see Getting Help for Suffix Commands) and infixes and
suffixes can be removed from the transient using C-x l <key>. Infixes
and suffixes that are disabled by default can be enabled the same way.
See Enabling and Disabling Suffixes.
Transient ships with support for a few different types of specialized infix commands. A command that sets a command line option for example has different needs than a command that merely toggles a boolean flag. Additionally Transient provides abstractions for defining new types, which the author of Transient did not anticipate (or didn’t get around to implementing yet).