Enhancing Minibuffer Completion

Emacs has three types of completion systems:

1. Minibuffer completion assists with picking choices in the minibuffer, such as function names, files and other selections.
2. Keychord completion: Systems to help with keyboard shortcuts.
3. Text completion helps you complete words you type in the buffer (see Writing Prose with Emacs).

The minibuffer is where you find files, call functions and other vital aspects. The minibuffer completion system aims to make it easier to find what you need by providing a search mechanism that provides a list of possible options.

The standard minibuffer Emacs completion system focuses on entering functions, filenames, buffer names and any other selection process in the minibuffer. When typing a partial function or file name, you can hit the TAB key. Emacs will display completion candidates in the minibuffer.

For example, to evaluate the visual-line-mode function to change how Emacs wraps paragraphs, you type M-x visu and TAB. If you hit TAB after each letter, you’ll notice that Emacs narrows the completion candidates as you get closer to your desired selection.

This principle also works with variable names and filenames. As you start looking for a filename, use the TAB key to prevent having to type the whole filename. The TAB key is your secret weapon to help you remember and discover functions, variables, file names, buffer names and other selection candidates.

The minibuffer completion system is highly configurable, and several packages extend this functionality. The approach in this configuration uses a stack of connected packages that provide a seamless experience. This approach showcases the extensibility of Emacs as a modular computing environment.

Vertico

The Vertico package enhances minibuffer completion. This extension uses incremental search, meaning the list of completion candidates is shortened to match your entry as soon as you type a letter.

When, for example, opening a file with C-c C-f, you can start typing any part of the filename to locate the file you seek. Use C-backspace keys to move to a higher directory.

The savehist package remembers your selections and saves your minibuffer history when exiting Emacs. This package ensures that your most popular choices remain on top for further convenience.

  ;; MINIBUFFER COMPLETION

  ;; Enable vertico
  (use-package vertico
    :init
    (vertico-mode)
    :custom
    (vertico-sort-function 'vertico-sort-history-alpha))

  ;; Persist history over Emacs restarts.
  (use-package savehist
    :init
    (savehist-mode))

Orderless

To further enhance our ability to find completion candidates, the orderless package matches patterns, irrespective of the order they are typed in.

For example, typing use pack TAB provides the same results as pack use TAB. The basic configuration sets some variables for integration with the Vertico completion package.

  (use-package orderless
    :custom
    (completion-styles '(orderless basic))
    (completion-category-defaults nil)
    (completion-category-overrides
     '((file (styles partial-completion)))))

Marginalia

Emacs is a self-documenting computing environment, which means that every function and variable includes a text describing what it does.

The marginala package displays these texts next to your completion candidates. When you now type M-x, you will see a list of functions and a brief description of what they do, making it even easier to find the function you need.

  ;; Enable richer annotations using the Marginalia package
  (use-package marginalia
    :init
    (marginalia-mode))

This video by Emacs guru Prot explains minibuffer completion in great detail.

Completion shortens the amount of text you must type and is terrific for discovering new functionality you did not yet realise existed. However, we usually don’t type function names but use keyboard shortcuts.

The Marginalia package shows the relevant keyboard shortcut when displaying the completion candidates to help you discover these shortcuts.

Remembering which keyboard shortcut you need in your next action takes some effort. The which-key package is not so much a completion system but a great help when trying to remember which keyboard shortcut to use. This package provides a minor mode that displays the key bindings following the currently-entered incomplete command (a prefix) in a popup.

Many keyboard shortcuts have multiple parts, such as C-x C-f. The which-key package shows a popup menu that lists all the available options. When, for example, you press C-x, the menu will list all follow-up keys and the function they are bound to. Where it says prefix in the popup, this means that there is a deeper level.

If the number of shortcuts is too large to fit in the popup window, then you can move to the next page with C-h n and the previous page with C-h p. Just typing C-h inside the Which-Key popup displays some additional options to navigate the list of key bindings.

The configuration below displays the popup at the bottom of the screen after you type the partial keyboard shortcut.

  ;; Improve keyboard shortcut discoverability
  (use-package which-key
    :config
    (which-key-mode)
    (which-key-setup-side-window-right))

If you like to support my work, then please purchase the Emacs Writing Studio book.

You can find the source files for the book and the latest configuration files on GitHub:

emacs-writing-studio

Emacs is a malleable system, so everybody will have their personal preferences. Any article on how to use Emacs is thus opinionated. If you have a different way of doing things, please complete the contact form to send me an email or contact me on social media.

The next article discusses the Emacs Writing Studio workflow.