Orderless, an Emacs completion style that matches the parts of your pattern in any order

The problem with order-sensitive completion

Emacs has several completion styles built in, and the familiar ones are all order sensitive. You type a prefix, it matches a prefix. You type a fuzzy sequence, it matches a fuzzy sequence in the same order. That works when you remember the name and are typing it left to right, which is most of the time when you are recalling an exact identifier. It breaks when you are describing rather than recalling. If you know a function involves a list and a search, you may type the search word first and the list word second, and an order sensitive style will find nothing even though the candidate is right there. Orderless is a completion style that divides the pattern into space-separated components and matches candidates that match all of the components in any order. The components are separated by spaces in the minibuffer, so the pattern reads as a set of requirements rather than a string to match, and the result is that you can type the terms in whatever order they come to mind.

One pattern, five ways to match a component

The interesting part is that a component is not required to be a literal. Each component can match in any one of several ways, and the matching style is a function from strings to regexps or predicates, so new ones are easy to define. The styles listed are orderless-regexp, where the component is treated as a regexp that must match somewhere in the candidate, and if the component is not a valid regexp it is ignored; orderless-literal, where the component is a literal string that must occur in the candidate; orderless-literal-prefix, where the literal must occur as a prefix of a candidate; orderless-prefixes, where the component is split at word endings and each piece must match at a word bound; and the initialism and flex styles. By default the regexp and literal matches are enabled, so the out-of-the-box behaviour is a literal or regexp search in any order, and the other styles are opt-in. The flexibility is the point, because the same component meaning can be expressed several ways and a user often wants different ones in different situations.

Initialism matching, and why it is worth a separate style

The worked example in the documentation is the clearest illustration of the whole design. Using describe-function, bound by default to C-h f, you match eis ff. In that particular case eis matched as an initialism and ff matched as a regexp. The initialism style is the one that makes the package genuinely different from ordinary fuzzy matching, because it treats a component as the initials of a sequence of words rather than as a substring. A component like eis is then matched against candidates whose words begin with e, i and s, in order but not adjacently. This is how you recall a function name you know the shape of but not the spelling of, and it is the reason an order-independent style is not redundant with flex matching. The flex style is another of the predefined ones, and the initialism and flex styles are not enabled by default, so a user who wants them turns them on deliberately.

What a completion style is, and where it plugs in

A completion style is a back-end for completion, used from a front-end that provides the completion UI, and the documentation is careful to separate the two. For minibuffer completion, the front ends named are the default Emacs completion UI, sometimes called minibuffer tab completion, the built-in Icomplete package, the icomplete-vertical variant from Emacs 28, and minibuffer completion frameworks such as Mct or Vertico. But the front ends named for the second case are all for minibuffer completion, used when Emacs commands prompt the user in the minibuffer for some input. There is also completion at point in normal buffers, typically used for identifiers in programming languages, and completion styles can be used for that purpose by front ends such as Corfu, Company or the function consult-completion-in-region from Consult. To use a completion style with any of those, you add it as an entry in completion-styles and in completion-category-overrides and completion-category-defaults. The documentation also notes it might still be possible to use orderless with front ends that do not support the standard completion styles, and that there is currently support for Ivy, documented separately.

Why the basic style stays in the list

The configuration examples all keep basic alongside orderless, and the reason given is a good one that is easy to miss. The basic completion style is specified as a fallback in addition to orderless in order to ensure that completion commands which rely on dynamic completion tables work correctly, with completion-table-dynamic and completion-table-in-turn given as the examples. Furthermore, the basic completion style needs to be tried first, not as a fallback, for TRAMP hostname completion to work, and that is achieved by adding an entry for the file completion category in completion-category-overrides. The partial-completion style in the same entry is what allows wildcards in file completion and partial paths, with ~/u/s/l for ~/usr/share/local given as the example. There is a related note for Emacs 31, where partial-completion behaves like substring, and the completion-pcm-leading-wildcard setting is what makes that behaviour available. These are the details that make the difference between a style that works and one that quietly breaks remote file editing.

Installation from a package archive, and the alternative

The package is available from the usual Emacs package archives, with badges for GNU ELPA, GNU-devel ELPA, MELPA releases and MELPA snapshots. The easiest route if you use ELPA or MELPA is package-install. If you use use-package, the example is the one shown earlier, with the ensure, custom and package settings. The alternative, for people who prefer to vendor the file, is to put orderless.el somewhere on your load-path and then require it and set the variables directly, which is the second example in the documentation. The repository itself is small and readable: the top level has orderless.el as the implementation, orderless-kwd.el, which is a separate file for the keyword matching, and orderless.texi, the Texinfo manual, alongside a README.org that is itself the source of the manual, a NEWS.org for the change log and a LICENSE. The primary language recorded for the project is Emacs Lisp, and the licence is GPL-3.0.

The customization surface, and the parts you can change at runtime

The manual's table of contents lists the customization areas, and they are worth knowing because most of them are meant to be adjusted rather than left alone. Component matching styles determine how each part of your pattern is interpreted, and there are style dispatchers that decide which style applies. A component separator regexp controls what splits a pattern into components in the first place, which is what you change when your terms contain characters you would rather not treat as separators. Faces for component matches controls how each match is highlighted, so you can see at a glance which term matched where. A pattern compiler section covers how the pattern is turned into a matcher, and there is a section on interactively changing the configuration, which means you can adjust these settings from inside Emacs rather than only in your init file. The remaining sections cover integration with other completion UIs, with separate subsections for Ivy and for Company.

The awkwardness with Company, and the alternatives

The documentation does not pretend that every front end works out of the box. While Company does support completion styles directly, pressing SPC takes you out of completion, so comfortably using orderless with it takes a bit of configuration, and there is a separate section documenting that. The general case is stated the same way: with a bit of effort it might still be possible to use orderless with other completion UIs even if they do not support the standard Emacs completion styles. The related packages section is where a reader gets the alternatives, and it covers Ivy and Helm, Prescient, and restricting to current matches in Icicles, Ido and Ivy. The last of those is a distinct idea worth separating from the rest: those packages can narrow the candidate list to what is currently visible, which is a different problem from matching a pattern in any order, and the documentation treats them as related rather than as competing.

Editorial conclusion

Adopt Orderless if you spend your day typing partial, unordered terms into the minibuffer and want candidate matching that reflects how you think rather than how the characters are laid out. Skip it if your completion habits are already consistent, because the style does not add anything when you type a full prefix in order. Verify three things before you make it your default: that the fallback style is set alongside it, since orderless alone breaks completion commands that rely on dynamic completion tables and TRAMP hostname completion; that the file completion category still uses partial-completion, or you lose wildcard file paths; and that the matching styles you leave enabled are the ones you want, since literal and regexp matching are on by default and the initialism and flex styles are not.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. oantolin/orderless on GitHub
4. README
5. Releases