transient 
- Description
- Transient commands
- Latest
- transient-0.10.0.tar (.sig), 2025-Sep-02, 700 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.9.4.tar.lz | 2025-Aug-01 | 112 KiB |
transient-0.9.3.tar.lz | 2025-Jul-01 | 112 KiB |
transient-0.9.2.tar.lz | 2025-Jun-10 | 112 KiB |
transient-0.9.1.tar.lz | 2025-Jun-03 | 112 KiB |
transient-0.9.0.tar.lz | 2025-Jun-01 | 112 KiB |
transient-0.8.8.tar.lz | 2025-May-12 | 108 KiB |
transient-0.8.7.tar.lz | 2025-Apr-01 | 107 KiB |
transient-0.8.6.tar.lz | 2025-Mar-15 | 107 KiB |
transient-0.8.5.tar.lz | 2025-Mar-02 | 106 KiB |
transient-0.8.4.tar.lz | 2025-Feb-01 | 106 KiB |
transient-0.8.3.tar.lz | 2025-Jan-03 | 103 KiB |
transient-0.8.2.tar.lz | 2025-Jan-01 | 103 KiB |
transient-0.8.1.tar.lz | 2024-Dec-09 | 101 KiB |
transient-0.8.0.tar.lz | 2024-Dec-07 | 101 KiB |
transient-0.7.9.tar.lz | 2024-Nov-05 | 96.5 KiB |
transient-0.7.0.tar.lz | 2024-Jun-18 | 93.1 KiB |
transient-0.6.0.tar.lz | 2024-Mar-31 | 92.1 KiB |
transient-0.5.3.tar.lz | 2023-Dec-16 | 90.2 KiB |
transient-0.4.3.tar.lz | 2023-Aug-25 | 86.4 KiB |
transient-0.3.7.tar.lz | 2021-Oct-25 | 69.8 KiB |
News
# -*- mode: org -*- * v0.10.0 2025-09-01 - Added more context-specific functions for getting the prefix's value and improved the documentation explaining when to use which function and why. b4edb633 (See also the commit message.) - When suffixes are being initialized, no longer drop inactive suffixes (inap suffixes and those on a level that is currently not being used). If/when such a suffix later becomes active, it now uses its set or saved value; previously the default value would have been used. #316, #364, #407 - The value and scope of inapt suffixes are now initialized when the prefix is being initialized, which is useful because they may later become apt. #407 - While setting up suffixes, the suffix being setup can now access suffixes that have already been setup (including their values). #316 - After suffixes have been setup, the value of the prefix's ~value~ slot is now made unbound, to prevent access to this potentially outdated value. 5bf26de9 - Added new face ~transient-inapt-argument~ and use it for arguments and values that are set but aren't being used because the suffix is currently inapt. fed866ba - Added new prefix slot ~remember-value~, which allows specifing various modes of automatically saving the current value. #287 * v0.9.4 2025-08-01 - When using coordinates, trying to insert the same suffix into the same menu twice, caused it to instead be removed the second time. #400 * v0.9.3 2025-07-01 - Improved kludge to work around a bug in Emacs, which may cause a subprocess to be killed, when the user types ~C-g~, expecting that to quit a transient menu. #388 - Fixed an edge-case when trying to put point on the same suffix after refreshing the menu. e508e658 - Removed an unnecessary redraw, which additionally happened too early, before suffixes were refreshed. #397 * v0.9.2 2025-06-09 - Fixed a regression in v0.9.0, which made it impossible to change the level of a suffix, if that was set inline in the prefix definition. * v0.9.1 2025-06-03 - As an additional safety measure, unconditionally reset ~inhibit-quit~ when the emergency exit is taken. b326421f - Including groups that are still defined as a variable, instead of using ~transient-define-group~ (added in v0.9.0), failed in some cases and prevented the menu from being displayed at all. #389 * v0.9.0 2025-06-01 - 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. c4e0cba6 - 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. 1933dda9 - 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. bcc0bf83 - 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. bcc0bf83 - Added new macro ~transient-inline-group~, which inlines an included group into a specific menu. bcc0bf83 - Added new, experimental suffix class ~transient-cons-option~, which is intended for situations where ~transient-args~ should return an alist, instead of a list of strings (arguments). 81727bac, e8eb3ebd - While a transient menu is active, ~inhibit-quit~ is now set to t. #388 * 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 ... ...