zsh-autocomplete adds real-time type-ahead autocompletion to Zsh. Find as you type, then
press Tab to insert the top completion, ShiftTab to insert the
bottom one, or ↓/PgDn to select another completion.
Besides live autocompletion, zsh-autocomplete comes with many other useful completion features.
Zsh's completion system is powerful, but hard to configure. So, zsh-autocomplete does it for you,
while providing a manageable list of settings for changing the defaults.
Press ControlR or ControlS to do an interactive, multi-line, fuzzy history search.
Press ↑ or PgUp to browse the last 16 history items. If the command line is not empty, then it will instead list the 16 most recent fuzzy matches.
Press ControlSpace in the completion menu or the history menu to insert more than one item.
Works out of the box with zero configuration, but also supports zsh-z, zoxide, z.lua,
rupa/z.sh, autojump and fasd.
| Key(s) | Action | Widget |
|---|---|---|
| Tab | Accept top completion | complete-word |
| ShiftTab | Accept bottom completion | complete-word |
| ControlSpace | Show additional completions | list-expand |
| ↑ | Cursor up (if able) or history menu | up-line-or-search |
| ↓ | Cursor down (if able) or completion menu | down-line-or-select |
| Alt↑ | Cursor up (always) | up-line |
| Alt↓ | Cursor down (always) | down-line |
| PgUp | History menu (always) | history-search |
| PgDn | Completion menu (always) | menu-select |
| ControlR | Live history search, from newest to oldest | history-incremental-search-backward |
| ControlS | Live history search, from oldest to newest | history-incremental-search-forward |
| Key(s) | Action |
|---|---|
| ↑/↓/←/→ | Change selection |
| Alt↑ | Backward one group |
| Alt↓ | Forward one group |
| PgUp/PgDn | Page up/down |
| Home/End | Beginning/End of menu |
| ControlSpace | Multi-select |
| Tab | Accept selection |
| ShiftTab | Reject selection |
| Enter | Accept command line |
| Key(s) | Action |
|---|---|
| ↑/↓ | Change selection |
| Home/End | Beginning/End of menu |
| ControlSpace | Multi-select |
| ←/→ | Accept selection & move cursor |
| Tab | Accept selection |
| ShiftTab | Reject selection |
| Enter | Accept command line |
Recommended:
- Zsh 5.8 or later.
Minimum:
- Zsh 5.3 or later.
To install:
- Clone the repo:
% cd ~/git # or wherever you keep your Git repos/Zsh plugins % git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git
- Add to your
~/.zshrcfile, before any calls tocompdef:source ~/git/zsh-autocomplete/zsh-autocomplete.plugin.zsh
- Remove any calls to
compinitfrom your~/.zshrcfile.
To update:
git -C ~/git/zsh-autocomplete pullInstead of following the instructions above, you can also install zsh-autocomplete through
whichever Zsh frameworks or plugin manager you use. Please refer to your framework's/plugin
manager's documentation for instructions.
The code below shows all of zsh-autocomplete's settings with their default values. To adjust a
setting, copy-paste it into your .zshrc file and change the value there.
zstyle ':autocomplete:*' default-context ''
# '': Start each new command line with normal autocompletion.
# history-incremental-search-backward: Start in live history search mode.
zstyle ':autocomplete:*' min-delay 0.0 # number of seconds (float)
# 0.0: Start autocompletion immediately when you stop typing.
# 0.4: Wait 0.4 seconds for more keyboard input before showing completions.
zstyle ':autocomplete:*' min-input 0 # number of characters (integer)
# 0: Show completions immediately on each new command line.
# 1: Wait for at least 1 character of input.
zstyle ':autocomplete:*' ignored-input '' # extended glob pattern
# '': Always show completions.
# '..##': Don't show completions when the input consists of two or more dots.
# When completions don't fit on screen, show up to this many lines:
zstyle ':autocomplete:*' list-lines 16 # (integer)
# NOTE: The actual amount shown can be less.
# If any of the following are shown at the same time, list them in the order given:
zstyle ':completion:*:' group-order \
expansions history-words options \
aliases functions builtins reserved-words \
executables local-directories directories suffix-aliases
# NOTE: This is NOT the order in which they are generated.
zstyle ':autocomplete:tab:*' insert-unambiguous no
# no: (Shift-)Tab inserts top (bottom) completion.
# yes: Tab first inserts substring common to all listed completions (if any).
zstyle ':autocomplete:tab:*' widget-style complete-word
# complete-word: (Shift-)Tab inserts top (bottom) completion.
# menu-complete: Press again to cycle to next (previous) completion.
# menu-select: Same as `menu-complete`, but updates selection in menu.
# NOTE: Can NOT be changed at runtime.
zstyle ':autocomplete:tab:*' fzf-completion no
# no: Tab uses Zsh's completion system only.
# yes: Tab first tries Fzf's completion, then falls back to Zsh's.
# NOTE 1: Can NOT be changed at runtime.
# NOTE 2: Requires that you have installed Fzf's shell extensions.
# Add a space after these completions:
zstyle ':autocomplete:*' add-space executables aliases functions builtins reserved-words commands
source path/to/zsh-autocomplete.plugin.zsh
#
# NOTE: All settings below should come AFTER sourcing zsh-autocomplete!
#
bindkey $key[Up] up-line-or-search
# up-line-or-search: Open history menu.
# up-line-or-history: Cycle to previous history line.
bindkey $key[Down] down-line-or-select
# down-line-or-select: Open completion menu.
# down-line-or-history: Cycle to next history line.
bindkey $key[Control-Space] list-expand
# list-expand: Reveal hidden completions.
# set-mark-command: Activate text selection.
bindkey -M menuselect $key[Return] .accept-line
# .accept-line: Accept command line.
# accept-line: Accept selection and exit menu.
# Uncomment the following lines to disable live history search:
# zle -A {.,}history-incremental-search-forward
# zle -A {.,}history-incremental-search-backward© 2020 Marlon Richert
This project is licensed under the MIT License. See the LICENSE file for details.