2.7 Enabling and Disabling Suffixes

The user base of a package that uses transients can be very diverse. This is certainly the case for Magit; some users have been using it and Git for a decade, while others are just getting started now.

For that reason a mechanism is that authors can use to classify a transient’s infixes and suffixes along the essentials…everything spectrum. We use the term "levels" to describe that mechanism.

Each suffix command is placed on a level and each transient has a level (called transient-level), which controls which suffix commands are available. Integers between 1 and 7 (inclusive) are valid levels. For suffixes, 0 is also valid; it means that the suffix is not displayed at any level.

The levels of individual transient and/or their individual suffixes can be changed interactively, by invoking the transient and then pressing C-x l to enter the "edit" mode, see below.

The default level for both transients and their suffixes is 4. The transient-default-level option only controls the default for transients. The default suffix level is always 4. The authors of transients should place certain suffixes on a higher level, if they expect that it won’t be of use to most users, and they should place very important suffixes on a lower level, so that they remain available even if the user lowers the transient level.

(Magit currently places nearly all suffixes on level 4 and lower levels are not used at all yet. So for the time being you should not set a lower default level and using a higher level might not give you as many additional suffixes as you hoped.)

User Option: transient-default-level

This option controls which suffix levels are made available by default. It sets the transient-level for transients for which the user has not set that individually.

User Option: transient-levels-file

This file is used to persist the levels of transients and their suffix between Emacs sessions.

C-x l     (transient-set-level)

This command enters edit mode. When edit mode is active, then all infixes and suffixes that are currently usable are displayed along with their levels. The colors of the levels indicate whether they are enabled or not. The level of the transient is also displayed along with some usage information.

In edit mode, pressing the key that would usually invoke a certain suffix does instead prompt the user for the level that that suffix should be placed on.

Help mode is available in edit mode.

To change the transient level press C-x l again.

To exit edit mode press C-g.

Note that edit mode does not display any suffixes that are not currently usable. magit-rebase for example shows different suffixes depending on whether a rebase is already in progress or not. The predicates also apply in edit mode.

Therefore, to control which suffixes are available given a certain state, you have to make sure that that state is currently active.