transient 
- Description
- Transient commands
- Latest
- transient-0.12.0.0.20260409.182552.tar (.sig), 2026-Apr-09, 630 KiB
- Maintainer
- Jonas Bernoulli <emacs.transient@jonas.bernoulli.dev>
- Website
- https://github.com/magit/transient
- Browse ELPA's repository
- CGit or Gitweb
- All Dependencies
- compat (.tar), cond-let (.tar), seq (.tar)
- 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.12.0.0.20260401.214523.tar.lz | 2026-Apr-02 | 112 KiB |
| transient-0.12.0.0.20260401.202308.tar.lz | 2026-Apr-01 | 112 KiB |
| transient-0.12.0.0.20260331.124943.tar.lz | 2026-Mar-31 | 112 KiB |
| transient-0.12.0.0.20260228.192825.tar.lz | 2026-Feb-28 | 110 KiB |
| transient-0.11.0.0.20251227.224828.tar.lz | 2025-Dec-28 | 108 KiB |
| transient-0.10.1.0.20251115.631.tar.lz | 2025-Nov-15 | 117 KiB |
| transient-0.9.4.0.20250829.152922.tar.lz | 2025-Sep-01 | 117 KiB |
| transient-0.8.8.0.20250530.204059.tar.lz | 2025-Jun-01 | 112 KiB |
| transient-0.7.9.0.20241203.214158.tar.lz | 2024-Dec-04 | 99.3 KiB |
| transient-0.0.20201221.170234.tar.lz | 2020-Dec-21 | 67.2 KiB |
News
# -*- mode: org -*-
* v0.13.0 UNRELEASED
This release adds features useful for visually impaired users.
The relevant options and recommended settings are documented in
the manual in the section "Accessibility Options". To go there,
evaluate this form: (info "(transient)Accessibility Options").
Some of the new options are also potentially useful for sighted
users.
- The menu window can now be selected automatically when activating
a menu, by setting the new option ~transient-select-menu-window~.
Doing so is only encouraged for users of braille output devices.
dd383016
- Added new option ~transient-navigate-to-group-descriptions~.
4087cf7b
- Added new option ~transient-describe-menu~. c9f8f398
- Improve suffix navigation. Support navigating to all cells and
fix restoring position after refresh for all cell types.
5d4a7e71, 0bbd75bd, bf92c158, 250a3c34
- Added new value ~verbose-force~ for ~transient-enable-menu-navigation~,
which causes a message to be echoed, even if it is identical to the
text displayed in the menu. 4d283706
- Added new option ~transient-prefer-reading-value~. 4dfc3e78
- Added new option ~transient-use-accessible-formats~. 63fca1f6
- Added new option ~transient-use-accessible-values~. 1fc27186
Also included in this release are the following changes, which do
not (primarily) concern accessibility.
- ~top-level~ did not exit transient's help and edit modes. b484f759
- Selecting the menu window using the command ~other-window~, is now
supported, but requires the following configuration. 5cd017e5
(define-key transient-predicate-map
[other-window] #'transient--do-move)
- Selecting the menu window using the mouse is now supported.
c5e6e207
- The region is now properly displayed, when using the mouse to
select text in the menu buffer. c5e6e207
- Added new ~transient-object~ base class, which all other classes
ultimately derive from. 8b057d82
- Fixed initial input when reading the value for a suffix whose
~always-read~ slot is non-nil. cde0756f
- Fixed exiting from ~recursive-edit~ to a transient menu. #425
- Added new function ~transient-read-string-from-buffer~. 0e65f5da
- Addressed an incompatibility with third-party help extensions.
#431
- Fixed how the list of suffixes is build, an issue which could
cause ~transient-suffix-object~ to return ~nil~ instead of the object.
https://github.com/magit/magit/issues/5528
- When the value of a suffix contained newline characters, then all
but the first line was discarded. #433
- If an error occurred in a command implemented in C or in an
anonymous commands, that could cause the transient menu to enter
an inconsistent state, because we failed to adequately advise
such commands, to protect against that possibility. 63f90723 ff
- If an error occurred because of a window misconfiguration by some
third-party code, that could cause the transient menu to enter an
inconsistent state, because we did not protect all the places where
that could result in an error. 8b142031, #429
* v0.12.0 2026-01-01
- Fixed a regression when using the ~transient-value-preset~ class,
introduced in v0.10.0. f960acdf
- Stopped creating a new file to save an unmodified default value
(the empty list). 3fdd8043
- Various makefile improvements. 4e6d3fc8..151622e1
- Gave up on determining function arity upfront. 6d1d8656
- Various build improvements.
* v0.11.0 2025-11-18
- At least Emacs 28.1 is required now. Emacs 30.1 was released
earlier this year, so we still support Emacs "oldoldstable".
Because Emacs 28.1 was the first release that bundled this
package, we have to keep support for that release. d361d272
- Use my new Cond-Let package. 87fb8396..1d2710c7
- When Isearch was exited using a key that has no binding in
~isearch-mode-map~, then the Transient state was not resumed.
82baa889
* v0.10.1 2025-10-06
- ~transient--get-savable-value~ now also functions properly when
...
...