8.4.4 How Completion Alternatives Are Chosen

Completion commands work by narrowing a large list of possible completion alternatives to a smaller subset that matches what you have typed in the minibuffer. In Completion Example, we gave a simple example of such matching. The procedure of determining what constitutes a match is quite intricate. Emacs attempts to offer plausible completions under most circumstances.

Emacs performs completion using one or more completion styles—sets of criteria for matching minibuffer text to completion alternatives. During completion, Emacs tries each completion style in turn. If a style yields one or more matches, that is used as the list of completion alternatives. If a style produces no matches, Emacs falls back on the next style.

The list variable completion-styles specifies the completion styles to use. Each list element is the name of a completion style (a Lisp symbol). The default completion styles are (in order):

basic

A matching completion alternative must have the same beginning as the text in the minibuffer before point. Furthermore, if there is any text in the minibuffer after point, the rest of the completion alternative must contain that text as a substring.

partial-completion

This aggressive completion style divides the minibuffer text into words separated by hyphens or spaces, and completes each word separately. (For example, when completing command names, ‘em-l-m’ completes to ‘emacs-lisp-mode’.)

Furthermore, a ‘*’ in the minibuffer text is treated as a wildcard—it matches any string of characters at the corresponding position in the completion alternative.

emacs22

This completion style is similar to basic, except that it ignores the text in the minibuffer after point. It is so-named because it corresponds to the completion behavior in Emacs 22.

The following additional completion styles are also defined, and you can add them to completion-styles if you wish (see Customization):

substring

A matching completion alternative must contain the text in the minibuffer before point, and the text in the minibuffer after point, as substrings (in that same order).

Thus, if the text in the minibuffer is ‘foobar’, with point between ‘foo’ and ‘bar’, that matches ‘afoobbarc’, where a, b, and c can be any string including the empty string.

flex

This aggressive completion style, also known as flx or fuzzy or scatter completion, attempts to complete using in-order substrings. For example, it can consider ‘foo’ to match ‘frodo’ or ‘fbarbazoo’.

initials

This very aggressive completion style attempts to complete acronyms and initialisms. For example, when completing command names, it matches ‘lch’ to ‘list-command-history’.

There is also a very simple completion style called emacs21. In this style, if the text in the minibuffer is ‘foobar’, only matches starting with ‘foobar’ are considered.

You can use different completion styles in different situations, by setting the variable completion-category-overrides. For example, the default setting says to use only basic and substring completion for buffer names.