5.2.1 Group Specifications

The suffix and infix commands of a transient are organized in groups. The grouping controls how the descriptions of the suffixes are outlined visually but also makes it possible to set certain properties for a set of suffixes.

Several group classes exist, some of which organize suffixes in subgroups. In most cases the class does not have to be specified explicitly, but see Group Classes.

Groups are specified in the call to define-transient-command, using vectors. Because groups are represented using vectors, we cannot use square brackets to indicate an optional element and instead use curly brackets to do the latter.

Group specifications then have this form:

[{LEVEL} {DESCRIPTION} {KEYWORD VALUE}... ELEMENT...]

The LEVEL is optional and defaults to 4. See Enabling and Disabling Suffixes.

The DESCRIPTION is optional. If present it is used as the heading of the group.

The KEYWORD-VALUE pairs are optional. Each keyword has to be a keyword symbol, either :class or a keyword argument supported by the constructor of that class.

• One of these keywords, :description, is equivalent to specifying DESCRIPTION at the very beginning of the vector. The recommendation is to use :description if some other keyword is also used, for consistency, or DESCRIPTION otherwise, because it looks better.
• Likewise :level is equivalent to LEVEL.
• Other important keywords include the :if... keywords. These keywords control whether the group is available in a certain situation.

  For example, one group of the magit-rebase transient uses :if magit-rebase-in-progress-p, which contains the suffixes that are useful while rebase is already in progress; and another that uses :if-not magit-rebase-in-progress-p, which contains the suffixes that initiate a rebase.

  These predicates can also be used on individual suffixes and are only documented once, see Predicate Slots.

• Finally the value of :hide, if non-nil, is a predicate that control whether the group is hidden by default. The key bindings for suffixes of a hidden group should all use the same prefix key. Pressing that prefix key should temporarily show the group and its suffixes, which assumes that a predicate like this is used:

  (lambda ()
    (eq (car transient--redisplay-key)
        ?\C-c)) ; the prefix key shared by all bindings
  

The ELEMENTs are either all subgroups (vectors), or all suffixes (lists) and strings. (At least currently no group type exists that would allow mixing subgroups with commands at the same level, though in principal there is nothing that prevents that.)

If the ELEMENTs are not subgroups, then they can be a mixture of lists that specify commands and strings. Strings are inserted verbatim. The empty string can be used to insert gaps between suffixes, which is particularly useful if the suffixes are outlined as a table.

The form of suffix specifications is documented in the next node.