---

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.

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-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 any, then do not require a match but do require non-empty input (or non-nil DEFAULT, since that is substituted for empty input).
• 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.
• format-prompt is called on PROMPT and DEF (or FALLBACK if DEF is nil). This appends ": " to the prompt and may also add the default to the prompt, using the format specified by minibuffer-default-prompt-format and depending on magit-completing-read-default-prompt-predicate.