transient 
- Description
- Transient commands
- Latest
- transient-0.8.8.0.20250520.104007.tar (.sig), 2025-May-21, 660 KiB
- Maintainer
- Jonas Bernoulli <emacs.transient@jonas.bernoulli.dev>
- Website
- https://github.com/magit/transient
- Browse ELPA's repository
- CGit or Gitweb
- Badge
- Manual
- transient
To install this package from Emacs, use package-install or list-packages.
Full description
1. Transient command menus
Transient is the library used to implement the keyboard-driven “menus” in Magit. It is distributed as a separate package, so that it can be used to implement similar menus in other packages.
1.1. Some things that Transient can do
- Display current state of arguments
- Display and manage lifecycle of modal bindings
- Contextual user interface
- Flow control for wizard-like composition of interactive forms
- History & persistence
- Rendering arguments for controlling CLI programs
1.2. Complexity in CLI programs
Complexity tends to grow with time. How do you manage the complexity
of commands? Consider the humble shell command ls. It now has over
fifty command line options. Some of these are boolean flags (ls -l).
Some take arguments (ls --sort=s). Some have no effect unless paired
with other flags (ls -lh). Some are mutually exclusive. Some shell
commands even have so many options that they introduce subcommands
(git branch, git commit), each with their own rich set of options
(git branch -f).
1.3. Using Transient for composing interactive commands
What about Emacs commands used interactively? How do these handle
options? One solution is to make many versions of the same command,
so you don't need to! Consider: delete-other-windows vs.
delete-other-windows-vertically (among many similar examples).
Some Emacs commands will simply prompt you for the next "argument"
(M-x switch-to-buffer). Another common solution is to use prefix
arguments which usually start with C-u. Sometimes these are sensibly
numerical in nature (C-u 4 M-x forward-paragraph to move forward 4
paragraphs). But sometimes they function instead as boolean
"switches" (C-u C-SPACE to jump to the last mark instead of just
setting it, C-u C-u C-SPACE to unconditionally set the mark). Since
there aren't many standards for the use of prefix options, you have to
read the command's documentation to find out what the possibilities
are.
But when an Emacs command grows to have a truly large set of options
and arguments, with dependencies between them, lots of option values,
etc., these simple approaches just don't scale. Transient is designed
to solve this issue. Think of it as the humble prefix argument C-u,
raised to the power of 10. Like C-u, it is key driven. Like the
shell, it supports boolean "flag" options, options that take
arguments, and even "sub-commands", with their own options. But
instead of searching through a man page or command documentation,
well-designed transients guide their users to the relevant set of
options (and even their possible values!) directly, taking into
account any important pre-existing Emacs settings. And while for
shell commands like ls, there is only one way to "execute" (hit
Return!), transients can "execute" using multiple different keys tied
to one of many self-documenting actions (imagine having 5 different
colored return keys on your keyboard!). Transients make navigating
and setting large, complex groups of command options and arguments
easy. Fun even. Once you've tried it, it's hard to go back to the
C-u what can I do here again? way.
Old versions
| transient-0.8.8.0.20250516.103135.tar.lz | 2025-May-19 | 111 KiB |
| transient-0.8.8.0.20250511.180821.tar.lz | 2025-May-12 | 108 KiB |
| transient-0.8.7.0.20250401.165541.tar.lz | 2025-Apr-01 | 107 KiB |
| transient-0.8.0.0.20241206.220403.tar.lz | 2024-Dec-07 | 101 KiB |
| transient-0.7.9.0.20241203.214158.tar.lz | 2024-Dec-04 | 99.3 KiB |
| transient-0.7.9.0.20241120.93248.tar.lz | 2024-Nov-20 | 96.9 KiB |
| transient-0.6.0.0.20240609.202011.tar.lz | 2024-Jun-14 | 92.7 KiB |
| transient-0.5.3.0.20240311.163849.tar.lz | 2024-Mar-11 | 91.1 KiB |
| transient-0.4.3.0.20231127.163229.tar.lz | 2023-Nov-27 | 86.5 KiB |
| transient-0.0.20201221.170234.tar.lz | 2020-Dec-21 | 67.2 KiB |
News
# -*- mode: org -*- * v0.9.0 UNRELEASED - Key descriptions (as returned by ~key-description~ and understood by ~kbd~) are now the only key binding format understood by Transient. Vectors are no longer supported. - Vectors are now preferred to identify a suffix or group in a menu by coordinates. It is still possible, but discouraged, to use a list. - The internal format used to store menu layouts has been improved. The old format is still supported and translated on the fly when encountered. Instead of rely on that translation, users are advised to recompile dependent packages after updating Transient to this release. - Added new macro ~transient-define-group~, which defines one or more groups of suffixes to be included in multiple menus. Such included groups are no longer immediately inlined when referenced in a menu definition, which makes it possible for users to make changes to included group and have those change affect all menus that include them. - Added new macro ~transient-inline-group~, which inlines an included group into a specific menu. * v0.8.8 2025-05-01 - Added option ~transient-common-command-prefix~ to allow using a key other than ~C-x~ as the prefix key used for many commands common to all transient menus. Because the use of the ~C-x~ prefix for these commands causes many global bindings to be shadowed even for menus that allow invoking non-suffix commands, I highly recommend that users customize this. 7d08039c - Added option ~transient-error-on-insert-failure~, defaulting to ~nil~. I.e., go back to the pre-v0.8.7 behavior by default but let users opt-in to errors for certain minor issues. #374 - Address a conflict with the keyboard used by the Android port. #376. * v0.8.7 2025-04-01 - Added new hook ~transient-post-exit-hook~. 55050b60 - ~transient-insert-suffix~ and ~transient-append-suffix~ now signal error if the specified location is invalid. #374 Bug fixes: - Autoloaded commands were loaded too late in ~transient-init-suffix~, resulting in the suffix prototype object not being used. 00112c11 * v0.8.6 2025-03-15 Bug fixes: - ~transient-show-summary~ errored for commands that have neither a summary nor a docstring. 0886651d - ~transient-format-description~ errored for ~transient-information~ and ~transient-information*~ suffixes. #366 - ~transient--wrap-command~ failed to load autoloaded commands. 40308623 - ~transient-suffix-object~ errored if a command is bound more than once and is invoked using the mouse or ~RET~. f69e1286 - For some releases ~transient-suffix-object~ errored if it could not identify a unique suffix, which helped establish that it is in fact legitimate to use this function as a predicate. No longer error if there are zero matches, but continue to error if their are multiple matches that cannot be disambiguated. 4a06aeb0 * v0.8.5 2025-03-01 - Added new faces ~transient-key-recurse~ and ~transient-key-stack~. 58e22554 Bug fixes: - ~transient--setup-recursion~ did not consider the ~recurse~ shorthand. 32a7e256 - The parent group was not always stored in suffix objects. #354 - Invoking a suffix of a sub-prefix (which is configured to return to the outer prefix), did exit instead of returning, if the suffix's own behavior was not explicitly specified. #352 - The color of a suffix that returns to the outer prefix, was wrong when there isn't actually an outer prefix. e88005d2 - When potentially removing other bindings for the same command while adding a new binding, false-negative avoidance was too heavily favored over false-positive avoidance. #355 - Defining the ~transient-higher-level~ face involves calling ~face-attributes~ on another face. That call requested the value for the current frame (which may not exist yet) instead of using the default. #359 - When the transient window is hidden while the minibuffer is used, then it was not restored if using Helm. #361 ... ...