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
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
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
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 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.
some additional work, and any function used in its place has to do
This function performs completion using the built-in
and does some additional magit-specific work.
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.
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,
See the documentation of the latter for more information.
If it does read a value in the minibuffer, then this function acts
completing-read, except for the following:
niland the user exits without a choice, then
nilis returned instead of an empty string.
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
helm-modeis enabled, and that
magit-completing-read-functionis set to its default value of