3.1 Defining Prefix Commands

Prefix commands and their infix arguments are defined using the macro magit-define-popup. The key bindings and descriptions of suffix commands are also defined using that macro, but the actual interactive commands have to be defined separately using plain defun.

Macro: magit-define-popup name doc [group [mode [option]]] :keyword value…

This macro defines a popup named NAME. The NAME should begin with the package prefix and by convention end with -popup, it is used as the name of the command which shows the popup and for an internal variable (whose value is used to store information about the popup and should not be accessed directly). DOC is the doc-string of the popup command.

This macro also defines an option and a function both named SHORTNAME-arguments, where SHORTNAME is NAME with the trailing -popup removed. The name of this option and this function can be overwritten using the optional argument OPTION, but that is rarely advisable. As a special case if OPTION is specified but nil, then this option and this function are not defined at all, which is useful for popups that are used as simple dispatchers that offer no arguments.

The option SHORTNAME-arguments holds the value for the popup arguments. It can be customized from within the popup or using the Custom interface. It can also have a buffer local value in any non-popup buffer. The local value for the buffer from which the popup command was invoked, can be set from within the popup buffer.

The function SHORTNAME-arguments returns the currently effective value of the variable by the same name. See below for more information.

Optional argument GROUP specifies the Custom group into which the option is placed. If omitted then the option is placed into some group the same way it is done when directly using defcustom and omitting the group, except when NAME begins with "magit-", in which case the group magit-git-arguments is used.

The optional argument MODE specifies the mode used by the popup buffer. If it is omitted or nil then magit-popup-mode is used.

The remaining arguments should have the form [KEYWORD VALUE]....

The following keywords are meaningful (and by convention are usually specified in that order):

• :actions

  The actions which can be invoked from the popup. VALUE is a list whose members have the form (KEY DESC COMMAND), see magit-define-popup-action for details.

  Actions are regular Emacs commands, which usually have an interactive form setup to consume the values of the popup :switches and :options when invoked from the corresponding popup, else when invoked as the default action or directly without using the popup, the default value of the variable SHORTNAME-arguments. This is usually done by calling the function SHORTNAME-arguments.

  Members of VALUE may also be strings and functions, assuming the first member is a string or function. In that case the members are split into sections and these special elements are used as headings. If such an element is a function then it is called with no arguments and must return either a string, which is used as the heading, or nil, in which case the section is not inserted.

  Members of VALUE may also be nil. This should only be used together with :max-action-columns and allows having gaps in the action grit, which can help arranging actions sensibly.

• :default-action

  The default action of the popup which is used directly instead of displaying the popup buffer, when the popup is invoked with a prefix argument. Also see magit-popup-use-prefix-argument and :use-prefix, which can be used to inverse the meaning of the prefix argument.

• :use-prefix

  Controls when to display the popup buffer and when to invoke the default action (if any) directly. This overrides the global default set using magit-popup-use-prefix-argument. The value, if specified, should be one of default or prefix, or a function that is called with no arguments and returns one of these symbols.

• :max-action-columns

  The maximum number of actions to display on a single line, a number or a function that return a number and takes the name of the section currently being inserted as argument. If there isn’t enough room to display as many columns as specified here, then fewer are used.

• :switches

  The popup arguments which can be toggled on and off. VALUE is a list whose members have the form (KEY DESC SWITCH), see magit-define-popup-switch for details.

  Members of VALUE may also be strings and functions, assuming the first member is a string or function. In that case the members are split into sections and these special elements are used as headings. If such an element is a function then it is called with no arguments and must return either a string, which is used as the heading, or nil, in which case the section is not inserted.

• :options

  The popup arguments which take a value, as in "–opt~OPTVAL". VALUE is a list whose members have the form (KEY DESC OPTION READER), see magit-define-popup-option for details.

  Members of VALUE may also be strings and functions, assuming the first member is a string or function. In that case the members are split into sections and these special elements are used as headings. If such an element is a function then it is called with no arguments and must return either a string, which is used as the heading, or nil, in which case the section is not inserted.

• :default-arguments

  The default arguments, a list of switches (which are then enabled by default) and options with there default values, as in "--OPT=OPTVAL".

• :variables

  Variables which can be set from the popup. VALUE is a list whose members have the form (KEY DESC COMMAND FORMATTER), see magit-define-popup-variable for details.

  Members of VALUE may also be strings and functions, assuming the first member is a string or function. In that case the members are split into sections and these special elements are used as headings. If such an element is a function then it is called with no arguments and must return either a string, which is used as the heading, or nil, in which case the section is not inserted.

  Members of VALUE may also be actions as described above for :actions.

  VALUE may also be a function that returns a list as describe above.

• :sequence-predicate

  When this function returns non-nil, then the popup uses :sequence-actions instead of :actions, and does not show the :switches and :options.

• :sequence-actions

  The actions which can be invoked from the popup, when :sequence-predicate returns non-nil.

• :setup-function

  When this function is specified, then it is used instead of magit-popup-default-setup.

• :refresh-function

  When this function is specified, then it is used instead of calling magit-popup-insert-section three times with symbols magit-popup-switch-button, magit-popup-option-button, and finally magit-popup-action-button as argument.

• :man-page

  The name of the manpage to be displayed when the user requests help for an argument.