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 needed 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 transients 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.
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.
This option names the file that is used to persist the levels of transients and their suffixes between Emacs sessions.
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 instead prompts the user for the level 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.