zsh-autocomplete

Modern, IDE-like autocompletion for the Z Shell:

• Asynchronously lists completions as you type.
  • Includes recent dirs from zsh-z, zoxide, z.lua, rupa/z.sh, autojump, fasd or cdr.
• Adds intuitive key bindings to choose and insert completions
• Automatically corrects misspellings.
  • Don't like a correction? Just press Undo to revert it.
• Works seamlessly with fzf, zsh-autosuggestions and zsh-syntax-highlighting/zdharma/fast-syntax-highlighting.

Table of Contents:

Key Bindings

zsh-autocomplete adds the following key bindings to your command line:

With zsh-autosuggestions

When you source zsh-autosuggestions in your .zshrc file, zsh-autocomplete modifies the following key binding:

With fzf

When you source fzf's shell extensions in your .zshrc file, zsh-autocomplete adds and modifies the following key bindings:

In Completion Menu

zsh-autocomplete adds the following key bindings to the completion menu:

Requirements

Mandatory:

• Zsh needs to be your shell.

Fzf integration:

• You need to source fzf's shell extensions in your .zshrc file to get the full integration. It's not enough for fzf to be in your path!

Installation

There are two ways to install zsh-autocomplete:

Manually

This is the preferred way to install.

1. git clone this repo. (You can optionally use a plugin manager for this.)
2. Add the following to your .zshrc file:

   source path/to/zsh-autocomplete.plugin.zsh

To update, cd into zsh-autocomplete's directory and do git pull (or use your plugin manager's update mechanism).

As a Plugin

zsh-autocomplete should work as a plugin with most frameworks & plugin managers. Please refer to your framework's/plugin manager's documentation for instructions.

If you're experiencing problems, please first install zsh-autocomplete manually instead. (See previous section.)

Note for Oh My Zsh, Prezto and Zimfw users: zsh-autocomplete works best if you use it instead of your framework's supplied completion module.

Configuration

The behavior of zsh-autocomplete can be customized through the zstyle system.

Wait for minimum amount of input

By default, zsh-autocomplete will show completions as soon as you start typing.

To make it stay silent until a minimum number of characters have been typed:

zstyle ':autocomplete:list-choices:*' min-input 3

Shorten or lengthen the autocompletion list

By default, while you are typing, zsh-autocomplete limits the number of lines of completions shown to 50% of $LINES minus $BUFFERLINES to prevent the prompt from jumping around too much while typing.

To limit the list to a different height, use the following:

zstyle ':autocomplete:list-choices:*' max-lines 100%

You can set this to a percentage or to a fixed number of lines. Both work.

Always show matches in named groups

By default, completion groups and duplicates matches are shown only in certain circumstances or when you press ⇤. This allows the automatic listing of completion matches to be as compact and fast as possible.

To always show matches in groups (and thus show duplicate matches, too):

zstyle ':autocomplete:*' groups always

WARNING: Enabling this setting can noticeably decrease autocompletion performance.

Disable "frecent" dirs feature

If you have zoxide, z.lua, z.sh, autojump or fasd installed and have correctly configured it to track your directory changes, then zsh-autocomplete will automatically list "frecent" directories from this tool.

To not include these:

zstyle ':autocomplete:*' frecent-dirs off

Customize autocompletion messages

You can customize the various messages that the autocompletion feature shows.

This is shown when the number of lines needed to display all matches exceeds the available screen space (or the number given by zstyle ':autocomplete:list-choices:*' max-lines):

zstyle ':autocomplete:*:too-many-matches' message \
  'Too many completions to fit on screen. Type more to filter or press Ctrl-Space to open the menu.'

This is shown when the completion system decides, for whatever reason, that it does not want to show any completions yet, until you've typed more input:

zstyle ':autocomplete:*:no-matches-yet' message 'Type more...'

This is shown when, for the given input, the completion system cannot find any matching completions at all:

zstyle ':autocomplete:*:no-matches-at-all' message 'No matching completions found.'

Change ⇥ and ⇤ behavior

By default, ⇥ accepts the top match. The idea is that you just keep typing until the match you want is

• at the top, at which point you press ⇥ to accept it immediately, or
• near the top, at which point you press ↓ to start menu selection. Then, inside the menu, use
  • ↑←↓→ to navigate the menu,
  • ↩︎ to accept a single match,
  • ⇥ to accept multiple matches, and
  • ⇤ to view more matches and/or more info (which also works from the command line).

To use ⇥ and ⇤ to start menu selection:

zstyle ':autocomplete:tab:*' completion select

Note that this also changes ⌃␣ to expand an alias or insert the longest common prefix of a glob expansion (since you don't need it anymore for selecting matches).

To have ⇥ and ⇤ cycle between matches (without starting menu selection):

zstyle ':autocomplete:tab:*' completion cycle

To have ⇥ and ⇤ insert the longest string that all matches listed have in common (and after that, behave as cycle):

zstyle ':autocomplete:tab:*' completion insert

To have ⇥ use fzf's completion feature:

zstyle ':autocomplete:tab:*' completion fzf

Change or disable automagic corrections and expansions

By default, ␣ and / automagically corrects spelling mistakes.

To have space do history expansion, instead of spelling correction:

zstyle ':autocomplete:space:*' magic expand-history

To make it do both:

zstyle ':autocomplete:space:*' magic correct-word expand-history

To disable all automagic corrections and expansions:

zstyle ':autocomplete:*' magic off

Disable fzf key bindings

If you source fzf's shell extensions, then zsh-autocomplete adds additional key bindings.

To not use these:

zstyle ':autocomplete:*' fuzzy-search off

Author

© 2020 Marlon Richert

License

This project is licensed under the MIT License. See the LICENSE file for details.