2 Usage

Every popup buffers created with a prefix command contains a section named "Actions" listing the available suffix commands. Most buffers also contain a "Switches" and/or an "Options" section which list the two types of infix arguments separately.

Switches are arguments that can be toggled on or off. When a switch is active then it is shown in color, when it is off then it is shown in gray (of course the details depend on the color theme in use).

Options are arguments that have a value. When an option has a value then that is shown after the option itself. Because for some options the empty string is a valid value, options are additionally colorized like switches to indicate whether they are active or not.

The events bound to suffix commands are always single alphabetic characters. The bindings for arguments are always two events long. For switches the first key is always -, for options it is always =. The second key is always an alphabetic character.

By default popup buffers also feature a section listing commands common to all popups. To avoid conflicts with suffix commands, the bindings of these common commands are not alphabetic characters. This section is shown by default so that documentation-resistant users get a chance to notice them.

User Option: magit-popup-show-common-commands

This option controls whether the section that lists the commands that are common to all popups is initially shown.

By default this is not the case, but note that you can temporarily show this section using C-t, which therefore is the only common command you actually have to memorize.

C-t     (magit-popup-toggle-show-common-commands)

Show or hide the section listing the commands shared by all popups.

C-g     (magit-popup-quit)

Quit popup buffer without invoking a suffix command.

Without further action, setting arguments only affects the next suffix command. Invoking the same prefix command again resets the arguments to their default value, but the defaults can be changed directly from the popup buffer itself. For a prefix command named NAME-popup the default values are stored as the value of the custom option named NAME-arguments. While this option can be customized using the Custom interface, it is better to do so directly from the popup buffer.

C-c C-c     (magit-popup-set-default-arguments)

This sets the default value for the arguments for the current popup.

Then the popup buffer is closed without invoking a suffix command; unless a prefix argument is used in which case the popup remains open.

C-x C-s     (magit-popup-save-default-arguments)

This sets the default value for the arguments for the current popup and saves it for future Emacs sessions.

Then the popup buffer is closed without invoking an action; unless a prefix argument is used in which case the popup remains open.

It is also possible to add additional arguments and commands to an existing popup, but that cannot be done directly from the popup (or the Custom interface). See Customizing Existing Popups.

Documentation about a popup’s arguments and commands can be shown directly from the popup.

C-h i     (magit-popup-info)

Show this manual.

?     (magit-popup-help)

This command reads a key sequence and then shows the documentation of the argument or command that sequence is bound to. In other words type the same keys that you would use to invoke the argument or command, but prefix the sequence with ?.

For suffix commands this shows the doc-string. For arguments this command can only show something for popups that have an associated man-page. If the man-page is set, then this command displays it in a separate buffer and puts point on the entry about the argument in question.

The buffer which is used to display the documentation is selected. Simply press q to leave that buffer and restore the old window configuration.

While it isn’t very useful, it is possible to move around in a popup buffer using C-p and C-n, and to invoke the argument or command at point using RET. But it is much more efficient to use the dedicated key bindings instead, so these commands are not listed in popup buffers along with the other common commands.