Skip to main content

4.5.5 Support for Completion Frameworks

The built-in option completing-read-function specifies the low-level function used by completing-read to ask a user to select from a list of choices. Its default value is completing-read-default. Alternative completion frameworks typically activate themselves by substituting their own implementation.

Mostly for historic reasons Magit provides a similar option named magit-completing-read-function, which only controls the low-level function used by magit-completing-read. This option also makes it possible to use a different completing mechanism for Magit than for the rest of Emacs, but doing that is not recommend.

You most likely don’t have to customize the magit-specific option to use an alternative completion framework. For example, if you enable ivy-mode, then Magit will respect that, and if you enable helm-mode, then you are done too.

However if you want to use Ido, then ido-mode won’t do the trick. You will also have to install the ido-completing-read+ package and use magit-ido-completing-read as magit-completing-read-function.

user option magit-completing-read-function​

The value of this variable is the low-level function used to perform completion by code that uses magit-completing-read (as opposed to the built-in completing-read).

The default value, magit-builtin-completing-read, is suitable for the standard completion mechanism, ivy-mode, and helm-mode at least.

The built-in completing-read and completing-read-default are not suitable to be used here. magit-builtin-completing-read performs some additional work, and any function used in its place has to do the same.

function magit-builtin-completing-read prompt choices \&optional predicate require-match initial-input hist def​

This function performs completion using the built-in completing-read and does some additional magit-specific work.

function magit-ido-completing-read prompt choices \&optional predicate require-match initial-input hist def​

This function performs completion using ido-completing-read+ from the package by the same name (which you have to explicitly install) and does some additional magit-specific work.

We have to use ido-completing-read+ instead of the ido-completing-read that comes with Ido itself, because the latter, while intended as a drop-in replacement, cannot serve that purpose because it violates too many of the implicit conventions.

function magit-completing-read prompt choices \&optional predicate require-match initial-input hist def fallback​

This is the function that Magit commands use when they need the user to select a single thing to act on. The arguments have the same meaning as for completing-read, except for FALLBACK, which is unique to this function and is described below.

Instead of asking the user to choose from a list of possible candidates, this function may just return the default specified by DEF, with or without requiring user confirmation. Whether that is the case depends on PROMPT, this-command and magit-dwim-selection. See the documentation of the latter for more information.

If it does read a value in the minibuffer, then this function acts similar to completing-read, except for the following:

  • COLLECTION must be a list of choices. A function is not supported.
  • If REQUIRE-MATCH is nil and the user exits without a choice, then nil is returned instead of an empty string.
  • If REQUIRE-MATCH is non-nil and the users exits without a choice, an user-error is raised.
  • FALLBACK specifies a secondary default that is only used if the primary default DEF is nil. The secondary default is not subject to magit-dwim-selection — if DEF is nil but FALLBACK is not, then this function always asks the user to choose a candidate, just as if both defaults were nil.
  • ": " is appended to PROMPT.
  • PROMPT is modified to end with \" (default DEF|FALLBACK): \" provided that DEF or FALLBACK is non-nil, that neither ivy-mode nor helm-mode is enabled, and that magit-completing-read-function is set to its default value of magit-builtin-completing-read.