1 Introduction

Vcomplete provides a minor mode which highlights the completion at point the completion list buffer and (optionally) automatically updates it. It builds upon the default completion system, instead of replacing it. As such, it works both when completing in a minibuffer and in normal buffers.

2 Installation

Vcomplete can be installed from NonGNU ELPA:

M-x package-install RET vcomplete RET

• Installing a release
• Installing from the Git repository

$ git clone https://git.sr.ht/~dsemy/vcomplete
$ cd vcomplete
$ make

3 Usage

It is recommended for vcomplete-mode to be enabled:

M-x vcomplete-mode RET

You can also add (vcomplete-mode) to your init file, or enable it through the customize interface.

When vcomplete-mode is enabled, the *Completions* buffer appears and updates automatically (by default), and the completion at point in the *Completions* buffer is highlighted, even if completions-highlight-face (Emacs 29+) is nil.

The following key bindings are also made available when completion is in progress:

C-n

Move point to the next displayed completion in the *Completions* window (vcomplete-next-completion or minibuffer-next-completion on Emacs 29+). This command may be used to move multiple completions at a time with a prefix argument.

C-p

Move point to the next displayed completion in the *Completions* window (vcomplete-prev-completion or minibuffer-previous-completion on Emacs 29+). This command may be used to move multiple completions at a time with a prefix argument.

M-RET

Choose the currently highlighted completion in the *Completions* window (vcomplete-choose-completion or minibuffer-choose-completion on Emacs 29+).

You may use these commands without enabling vcomplete-mode (although they won’t be bound by default). See Completion commands for information regarding defining new commands.

4 Customization

All customization, except for defining custom completion commands can be done through the customize interface:

M-x customize-group RET vcomplete RET

User Option: vcomplete-auto-update ¶

Whether the *Completions* buffer should open and update automatically. Non-nil means automatically open and update. Otherwise, operate according to completion-auto-help. By default, t is used. Note that with completions-detailed (introduced in Emacs 28) enabled, the *Completions* buffer takes much more time to display. This is also true for other “annotation providers” such as the Marginalia package. Consider disabling them or this option on slow computers.

User Option: vcomplete-search-range ¶

Range of search for a *Completions* window during completion. A value of t means consider all windows on all frames, visible means consider all windows on all visible frames, 0 (the number zero) means consider all windows on all visible and iconified frames and any other value means consider only the currently selected frame. By default, 0 is used. In Emacs 29+ this option is unavailable since built-in functions and macros are used, which don’t respect its value. The built-in functions use the equivalent of setting this option to 0.

• Completion commands