---

2.7 Enabling and Disabling Suffixes ¶

The user base of a package that uses transient menus can be diverse. This is certainly the case for Magit. Some users have been using it and Git for a decade or more, while others are just getting started now.

For that reason a mechanism is needed, that enables authors to control which infix and suffix commands are shown to which group of users, and for users to override those choices. We use the term levels to describe that mechanism.

Each suffix command is placed on a level and each menu has a level. A suffix commands is available if its (non-zero) level is smaller or equal to the level of the menu. Valid levels are integers between 1 and 7. As a special case, the level of a suffix can be 0, in which case it is never shown, regardless of the menu’s level. The default level for suffix commands is 1.

The default level for menus is controlled using the option transient-default-level, which defaults to 4. To show more suffix commands increase the value of this option or the level of an individual menu. To show fewer suffixes increase such a value. Changing the value of this option affects the menus of all packages, so you might want to only change the value of individual menus.

To control which commands are shown for some menu, invoke it as usual, and then press C-x l. You will be guided through the process. This allows you to change the level of the menu itself, and/or the levels of individual suffix commands for even finer control.

The function transient-set-default-level can be used to change the level of an individual suffix command across all menus, which feature that command and provided no local value is specified. This does not work for all suffix commands, and is thus discouraged.

User Option: transient-default-level ¶

This option controls which suffix levels are made available by default. It specifies the level for menus for which the user has not set a local value. The default is 4.

User Option: transient-levels-file ¶

This option names the file that is used to persist the levels of menus and their suffix commands between Emacs sessions.

Option transient-common-command-prefix controls the prefix key used in the following bindings. For simplicity’s sake the default, C-x, is shown below.

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 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.

C-x a (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.

Function: transient-set-default-level command level ¶

This function sets the default level of the suffix COMMAND to LEVEL.

(The use of this function is currently discouraged, because it does not work for all commands and because even for commands, which would support it, it does not always have an effect.)

A suffix command is made available if its level is smaller than or equal to the level of the menu. The level of a suffix command is determined as follows:

1. The default level for all suffix commands, which is always 1.
2. The level set when the suffix command was defined using transient-define-suffix, transient-define-infix or transient-define-argument.
3. The level set using this function. Use this to override the value set using (2) or the default from (1). (4) and (5) override the value set here. This function can only be used for commands defined using the functions mentioned in (2); else you have to use (5). Unless a command appears in multiple menus, it is better to use (5).
4. The level set when binding the suffix command in a specific menu. Package authors should avoid this, and prefer (2); unless they want to place a command on different levels in different menus.
5. The level interactively set for an individual suffix command in an individual menu, using C-x l.

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)