Overview

This package provides an ‘orderless’ completion style that divides the pattern into space-separated components, and matches candidates that match all of the components in any order. Each component can match in any one of several ways: literally, as a regexp, as an initialism, in the flex style, or as multiple word prefixes. By default, regexp and literal matches are enabled.

A completion style is a back-end for completion and is used from a front-end that provides a completion UI. Any completion style can be used with the default Emacs completion UI (sometimes called minibuffer tab completion), with the built-in Icomplete package (which is similar to the more well-known Ido Mode), the icomplete-vertical variant from Emacs 28, or with minibuffer completion frameworks such as Mct or Vertico.

All the completion UIs just mentioned are for minibuffer completion, used when Emacs commands prompt the user in the minibuffer for some input, but there is also completion at point in normal buffers, typically used for identifiers in programming languages. Completion styles can also be used for that purpose by completion at point UIs such as Corfu, Company or the function ‘consult-completion-in-region’ from Consult.

To use a completion style with any of the above mentioned completion UIs simply add it as an entry in the variables ‘completion-styles’ and ‘completion-category-overrides’ and ‘completion-category-defaults’ (see their documentation).

The ‘completion-category-defaults’ variable serves as a default value for ‘completion-category-overrides’. If you want to use ‘orderless’ exclusively, set both variables to ‘nil’, but be aware that ‘completion-category-defaults’ is modified by packages at load time.

With a bit of effort, it might still be possible to use ‘orderless’ with other completion UIs, even if those UIs don’t support the standard Emacs completion styles. Currently there is support for Ivy, as documented below. Also, 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 (see below).

If you use ELPA or MELPA, the easiest way to install ‘orderless’ is via ‘package-install’. If you use ‘use-package’, you can use:

(use-package orderless
  :ensure t
  :custom
  (completion-styles '(orderless basic))
  (completion-category-overrides '((file (styles partial-completion))))
  (completion-pcm-leading-wildcard t)) ;; Emacs 31: partial-completion behaves like substring

Alternatively, put ‘orderless.el’ somewhere on your ‘load-path’, and use the following configuration:

(require 'orderless)
(setq completion-styles '(orderless basic)
      completion-category-overrides '((file (styles partial-completion)))
      completion-pcm-leading-wildcard t) ;; Emacs 31: partial-completion behaves like substring

The ‘basic’ completion style is specified as fallback in addition to ‘orderless’ in order to ensure that completion commands which rely on dynamic completion tables, e.g., completion-table-dynamic or completion-table-in-turn, work correctly. Furthermore the ‘basic’ completion style needs to be tried first (not as a fallback) for TRAMP hostname completion to work. In order to achieve that, we add an entry for the ‘file’ completion category in the ‘completion-category-overrides’ variable. In addition, the ‘partial-completion’ style allows you to use wildcards for file completion and partial paths, e.g., /u/s/l for /usr/share/local.

Bug reports are highly welcome and appreciated!