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.
transient-toggle-level-limit) ¶This command toggle whether suffixes that are on levels higher than
the level specified by transient-default-level are temporarily
available anyway.
This function sets the default level of the suffix COMMAND to LEVEL.
If a suffix command appears in multiple menus, it may make sense to
consistently change its level in all those menus at once. For
example, the --gpg-sign argument (which is implemented using the
command magit:--gpg-sign), is bound in all of Magit’s menu which
create commits. Users who sometimes sign their commits would want
that argument to be available in all of these menus, while for users
who never sign it is just unnecessary noise in any menus.
To always make --gpg-sign available, use:
(transient-set-default-level 'magit:--gpg-sign 1)
To never make --gpg-sign available, use:
(transient-set-default-level 'magit:--gpg-sign 0)
This sets the level in the suffix prototype object for this command.
Commands only have a suffix prototype if they were defined using one
of transient-define-argument, transient-define-infix and
transient-define-suffix. For all other commands this would signal
an error. (This is one of the reasons why package authors should
use one of these functions to define shared suffix commands, and
especially shared arguments.)
If the user changes the level of a suffix in a particular menu, using C-x l as shown above, then that obviously shadows the default.
It is also possible to set the level of a suffix binding in a
particular menu, either when defining the menu using
transient-define-prefix, or later using transient-insert-suffix. If
such bindings specify a level, then that also overrides the default.
(Per-suffix default levels is a new feature, so you might encounter
this quite often.)