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
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
The default value,
magit-builtin-completing-read, is suitable for the standard completion mechanism,
helm-mode at least.
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,
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
niland the user exits without a choice, then
nilis 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
nilbut FALLBACK is not, then this function always asks the user to choose a candidate, just as if both defaults were
- ": " is appended to PROMPT.
- PROMPT is modified to end with \" (default DEF|FALLBACK): \" provided that DEF or FALLBACK is non-nil, that neither
helm-modeis enabled, and that
magit-completing-read-functionis set to its default value of