GNU ELPA - transient

transient

Description: Transient commands
Latest: transient-0.8.5.tar (.sig), 2025-Mar-02, 630 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.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.8.tar.lz	2024-Nov-02	96.3 KiB
transient-0.7.7.tar.lz	2024-Oct-05	95.1 KiB
transient-0.7.6.tar.lz	2024-Oct-02	94.9 KiB
transient-0.7.5.tar.lz	2024-Sep-01	94.5 KiB
transient-0.7.4.tar.lz	2024-Aug-05	94.6 KiB
transient-0.7.3.tar.lz	2024-Jul-14	94.1 KiB
transient-0.7.2.tar.lz	2024-Jun-24	93.6 KiB
transient-0.7.1.tar.lz	2024-Jun-19	93.2 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.5.0.tar.lz	2023-Nov-28	88.8 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.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 ~resurse~ 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 to 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

- Non-suffix command that aren't accessed via a symbol, were not
  properly wrapped to ensure post-command cleanup happens even in
  case of an error or if the user aborts a minibuffer use, causing
  the menu window to get stuck.  08201f06

* v0.8.4    2025-02-01

- Added new option ~transient-show-docstring-format~.  65cd6cec

- Unless called with a prefix argument, ~transient-toggle-docstrings~
  now only shows docstrings for the current menu invocation.  13f3f5e0

- The ~##~ macro from the ~llama~ package can now be used after keywords
  in group specifications (including suffix bindings).  7c650436

- Suffix commands can now be advised using the new ~advice~ and ~advice*~
  slots available for suffixes and groups.  This feature is still
  experimental.  #340

- ~transient-scope~ can now also match against prefix classes, not just
  specific prefix commands.  #334

- The default level of a suffix command can now be set via its
  prototype, using the new function ~transient-set-default-level~.
  f6c249c7

* v0.8.3    2025-01-03

- Added new constant ~transient-version~.  3022f6d5

* v0.8.2    2025-01-01

- Added support for displaying the transient menu in a dedicated
  frame.  bf58c0bb

- When including a group via a variable, the imported value can now be
  a top-level group.  eebcbe30

- The transient window is now fitted to its buffer horizontally as well.
  fd9811ea

- Added new command ~transient-copy-menu-text~.  042f37aa

- Added new command ~transient-toggle-docstrings~.  52679f98

- Added new command ~transient-describe~, which can be bound as many times
  as needed to show help for arbitrary things.  5a18a791

Bug fixes:

- The use of ~display-buffer-full-frame~ was prevented too aggressively.
  5353464b

- Fixed remembering and restoring the old value of the ~no-other-window~
  window parameter.  de984302

- When a command is bound multiple times and the instances use different
  transient behavior, then the behavior (and color) for the last binding
  was used for all bindings.  fe71a7e7, a99dcda9

- Enabling ~transient-force-single-column~ resulted in an error.
  28347e59

- ~transient-toggle-common~ used to exit the menu.  98c01b84

* v0.8.1    2024-12-08

Bug fixes:

- Interactively setting the level of a transient prefix resulted in
  an error.  #337.

* v0.8.0    2024-12-06

- While the minibuffer is in use, the menu window is now hidden by
  default.  The new option ~transient-show-during-minibuffer-read~ not
  only controls whether the menu stays visible while the minibuffer
  is in use, but also whether it may be resized if necessary.  This
  new option replaces ~transient-hide-during-minibuffer-read~.  #330

- When returning to a prefix whose ~refresh-suffixes~ slot is non-nil,
  its suffixes are now re-initialized.  #327

- Added documentation for ~inapt-if*~ slots to manual.  179545a6

- ~transient-args~ now takes a prefix command or a list of prefix
...
...