2.1 Customizing Existing Popups

It is possible to define additional infix arguments and suffix commands to an existing popup using the following functions.

You can find some examples which use the below commands at https://github.com/magit/magit/wiki/Additional-proposed-infix-arguments-and-suffix-commands.

Function: magit-define-popup-switch popup key desc switch &optional enable at prepend

In POPUP, define KEY as SWITCH.

POPUP is a popup command defined using magit-define-popup. SWITCH is a string representing an argument that takes no value. KEY is a character representing the second event in the sequence of keystrokes used to toggle the argument. (The first event, the prefix, is shared among all switches, defaults to -, and can be changed in magit-popup-mode-keymap).

DESC is a string describing the purpose of the argument, it is displayed in the popup.

If optional ENABLE is non-nil then the switch is on by default.

SWITCH is inserted after all other switches already defined for POPUP, unless optional PREPEND is non-nil, in which case it is placed first. If optional AT is non-nil then it should be the KEY of another switch already defined for POPUP, the argument is then placed before or after AT, depending on PREPEND.

Function: magit-define-popup-option popup key desc option &optional reader value at prepend

In POPUP, define KEY as OPTION.

POPUP is a popup command defined using magit-define-popup. OPTION is a string representing an argument that takes a value. KEY is a character representing the second event in the sequence of keystrokes used to set the argument’s value. (The first event, the prefix, is shared among all options, defaults to =, and can be changed in magit-popup-mode-keymap).

DESC is a string describing the purpose of the argument, it is displayed in the popup.

If optional VALUE is non-nil then the option is on by default, and VALUE is its default value.

READER is used to read a value from the user when the option is invoked and does not currently have a value. (When the option has a value, then invoking the option causes it to be unset.) This function must take two arguments but may choose to ignore them. The first argument is the name of the option (with ": \" appended, unless it ends with "=") and can be used as the prompt. The second argument is nil or the value that was in effect before the option was unset, which may be suitable as initial completion input. If no reader is specified, then read-from-minibuffer is used.

OPTION is inserted after all other options already defined for POPUP, unless optional PREPEND is non-nil, in which case it is placed first. If optional AT is non-nil then it should be the KEY of another option already defined for POPUP, the argument is then placed before or after AT, depending on PREPEND.

Function: magit-define-popup-action popup key desc command &optional at prepend

In POPUP, define KEY as COMMAND.

POPUP is a popup command defined using magit-define-popup. COMMAND can be any command but should usually consume the popup arguments in its interactive form. KEY is a character representing the event used invoke the action, i.e. to interactively call the COMMAND.

DESC is a string describing the purpose of the action, it is displayed in the popup.

COMMAND is inserted after all other commands already defined for POPUP, unless optional PREPEND is non-nil, in which case it is placed first. If optional AT is non-nil then it should be the KEY of another command already defined for POPUP, the command is then placed before or after AT, depending on PREPEND.

Function: magit-define-popup-sequence-action popup key desc command &optional at prepend

Like magit-define-popup-action, but modifies the value of the :sequence-actions property instead of :actions.

Function: magit-define-popup-variable popup key desc command formatter &optional at prepend

In POPUP, define KEY as COMMAND.

POPUP is a popup command defined using magit-define-popup. COMMAND is a command which calls magit-popup-set-variable. FORMATTER is a function which calls magit-popup-format-variable. These two functions have to be called with the same arguments.

KEY is a character representing the event used interactively call the COMMAND.

DESC is the variable or a representation thereof. It’s not actually used for anything.

COMMAND is inserted after all other commands already defined for POPUP, unless optional PREPEND is non-nil, in which case it is placed first. If optional AT is non-nil then it should be the KEY of another command already defined for POPUP, the command is then placed before or after AT, depending on PREPEND."

Function: magit-change-popup-key popup type from to

In POPUP, bind TO to what FROM was bound to. TYPE is one of :action, :sequence-action, :switch, or :option. Bind TO and unbind FROM, both are characters.

Function: magit-remove-popup-key popup type key

In POPUP, remove KEY’s binding of TYPE. POPUP is a popup command defined using magit-define-popup. TYPE is one of :action, :sequence-action, :switch, or :option. KEY is the character which is to be unbound.

It is also possible to change other aspects of a popup by setting a property using plist-put. See Defining Prefix Commands for valid properties. The most likely change Magit users might want to make is:

(plist-put magit-show-refs-popup :use-prefix nil)