zsh-autocomplete
Find-as-you-type completion for the Z Shell!
- Asynchronously shows completions as you type.
- With IDE-like keybindings to choose completions and insert them.
- Automagically corrects misspellings, expands aliases and does history expansions.
- Don't like a correction/expansion? Just press Undo to revert it.
- Integrates seamlessly with
fzf,zsh-autosuggestionsandzsh-syntax-highlighting/zdharma/fast-syntax-highlighting. - Includes completion results from
zoxide,z.lua,z.sh,autojumpandfasd.
Demo
Key Bindings
zsh-autocomplete adds the following key bindings to your command line:
| Key(s) | Action |
|---|---|
| any | List choices (automatic) |
| ⇥ | Insert top completionnote |
| ⌃␣ | Select another completionnote |
| ⇤ | List more choices/info |
| ␣ | Insert space and correct spelling or do history expansion |
| ⌥␣ | Insert space (without correct spelling or history expansion) |
With zsh-autosuggestions
When you source zsh-autosuggestions in your .zshrc file, zsh-autocomplete modifies the following key binding:
| Key(s) | Action |
|---|---|
| ⇥ | Accept autosuggested word (when available) or insert top completion |
With fzf
When you source fzf's shell extensions in your .zshrc file, zsh-autocomplete adds and modifies the following key bindings:
| Key(s) | Action |
|---|---|
| ↓ | Select a completion or (in multi-line buffer) move cursor down |
| ↑ | Do fuzzy history search or (in multi-line buffer) move cursor up |
| ⌃␣ | Change directory (in empty buffer), expand alias, insert longest common prefix (on glob expression) or do fuzzy file search |
| ⌥↓ | Enter completion menu (also in multi-line buffer) |
| ⌥↑ | Do fuzzy history search (also in multi-line buffer) |
Completion Menu
zsh-autocomplete adds the following key bindings to the completion menu:
| Key(s) | Action |
|---|---|
| ↑←↓→ | Change selection |
| ⌥↓ | Jump to next group of matches (if groups are shown) |
| ⌥↑ | Jump to previous group of matches (if groups are shown) |
| ↩︎ | Insert single match (exit menu) |
| ⇥ | Insert multiple matches (stay in menu) |
| ⇤ | List more choices/info (does not work in "corrections" menu) |
| ⌃␣ | Insert single match + fuzzy file search |
| other | Insert single match + insert character (exit menu) |
Requirements
Mandatory:
- Zsh needs to be your shell.
Fzf integration:
- You need to source
fzf's shell extensions in your.zshrcfile to get the full integration. It's not enough forfzfto be in your path!
Installation
There are two ways to install zsh-autocomplete:
As a Plugin
Please refer to your framework's/plugin manager's documentation for instructions.
Note for Prezto users: You need you load zsh-autocomplete after or instead of Prezto's built-in completion module.
Manually
git clonethis repo.- Add the following to your
.zshrcfile:source path/to/zsh-autocomplete.plugin.zsh
To update, cd into zsh-autocomplete's directory and do git pull.
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 the autocompletion list
By default, while you are typing, zsh-autocomplete lists as many completions as it can fit on the screen.
To limit the list to a smaller height, use the following:
zstyle ':autocomplete:list-choices:*' max-lines 40%
You can set this to a percentage of the total screen height 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.
Tweak or disable automagic corrections
By default, ␣ and / both automagically correct your spelling.
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, including history expansion:
zstyle ':autocomplete:*' magic off
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 use ⇥ and ⇤ to start menu selection:
zstyle ':autocomplete:tab:*' completion select
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
Note: This last option also changes the listings slightly to not do completion to the left of what you've typed (unless that would result in zero matches).
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.'
Author
© 2020 Marlon Richert
License
This project is licensed under the MIT License. See the LICENSE file for details.
