zsh-autocomplete
adds real-time type-ahead autocompletion to Zsh, plus many more completion
features.
-
Recent dirs completion:
- Supports
cdr
,zsh-z
,zoxide
,z.lua
,rupa/z.sh
,autojump
andfasd
.
- Supports
-
Automatic incremental history search:
-
History menu (โ/PgUp):
-
Multi-selection with Alt+Space in completion menu (โ/PgDn) and history menu:
- Single selection in menus with Enter.
-
Additional context-sensitive completions:
Key(s) | Action | Widget |
---|---|---|
any | Show completions (asynchronously) | _list_choices |
Tab | Insert top completion | complete-word |
Shift+Tab | Insert bottom completion | expand-word |
Ctrl+Space | Show full completion menu | list-expand |
โ | Enter completion menu or move cursor down (in multi-line buffer) | down-line-or-select |
PgDn | Enter completion menu (always) | menu-select |
โ | Open history menu or move cursor up (in multi-line buffer) | up-line-or-search |
PgUp | Open history menu (always) | history-search |
Key(s) | Action |
---|---|
โ/โ/โ/โ | Change selection |
Enter | Accept and exit |
Alt+Space | Multi-select |
Ctrl+Space | Show full completion menu |
PgUp | Page up |
PgDn | Page Down |
Alt+B | Backward one group (if groups are shown) |
Alt+F | Forward one group (if groups are shown) |
Home | Beginning of line |
End | End of line |
Alt+Shift+, | Beginning of menu |
Alt+Shift+. | End of menu |
other | Accept and exit (then execute the key just typed) |
Key(s) | Action |
---|---|
โ/โ | Change selection |
Enter | Accept and exit |
Alt+Space | Multi-select |
Alt+Shift+, | Beginning of menu |
Alt+Shift+. | End of menu |
other | Accept and exit (then execute the key just typed) |
Recommended:
- Zsh 5.8 or later.
Minimum:
- Zsh 5.3 or later.
git clone
this repo.- Add to your
.zshrc
file:source path/to/zsh-autocomplete.plugin.zsh
cd
intozsh-autocomplete
's directory.- Do
git pull
.
zsh-autocomplete
should work as a plugin with most frameworks & plugin managers. Please refer to
your framework's/plugin manager's documentation for instructions.
To change your settings, just copy-paste any of the code below to your ~/.zshrc
file.
:autocomplete:
namespace, some of them use
:completion:
. This is because the latter are managed by Zsh's own completion system, whereas the
former are unique to zsh-autocomplete
.
- Show completions in named groups
- Show more/less help text
- Disable particular completions
- Wait for a minimum amount of input
- Change the length of the autocompletion list
- Customize the autocompletion messages
- Use your own completion config
- Change Tab behavior
- Change other key bindings
To categorize completions under informative headers:
zstyle ':completion:*' group-name ''
To group completions only when you press Ctrl+Space:
zstyle ':completion:list-expand:*' group-name ''
To show more descriptions:
zstyle ':completion:*' extra-verbose yes
To show fewer descriptions:
zstyle ':completion:*' verbose no
To show more descriptions only when you press Ctrl+Space:
zstyle ':completion:list-expand:*' extra-verbose yes
Any of the extra completions added by zsh-autocomplete
can be disabled through the completion
system's tag-order
setting. For example, to disable history words, recent directories and recent
files:
zstyle ':completion:*' tag-order '! history-words recent-directories recent-files' '-'
To suppress autocompletion until a minimum number of characters have been typed:
zstyle ':autocomplete:*' min-input 3
To change the list length from the default of 10 lines:
zstyle ':autocomplete:*' max-lines 100%
You can set this to a percentage of the available screen space or to a fixed number of lines. Both work.
To change the message shown when the list of completions is too long and gets truncated:
zstyle ':autocomplete:*:too-many-matches' message '(partial list; press Ctrl+Space to expand)'
To change the message shown when no matching completions can be found:
zstyle ':autocomplete:*:no-matches-at-all' message 'No matching completions found.'
To disable zsh-autocomplete
's pre-packaged config:
zstyle ':autocomplete:*' config off
By default, Tab insert the top completion, Shift+Tab inserts the bottom completion, and โ activates menu selection.
widget-style
at runtime has no effect and
changing fzf-completion
at runtime will not function correctly. These settings can be changed in
your ~/.zshrc
file only.
To make Tab first insert any common substring, before inserting full completions:
zstyle ':autocomplete:tab:*' insert-unambiguous yes
To make Tab or Shift+Tab use menu selection:
zstyle ':autocomplete:tab:*' widget-style menu-select
To make Tab and Shift+Tab cycle completions without using menu selection:
zstyle ':autocomplete:tab:*' widget-style menu-complete
To make Tab try Fzf's completion before using Zsh's:
zstyle ':autocomplete:tab:*' fzf-completion yes
widget-style
, insert-unambiguous
and fzf
are mutually compatible and can be used in parallel.
Key bindings other than Tab or Shift+Tab can be overridden with
the bindkey
command, if you do so after sourcing zsh-autocomplete
:
source path/to/zsh-autocomplete.plugin.zsh
# zsh-autocomplete defines an associative array `key` that you can use for this.
bindkey $key[Up] up-line-or-history
bindkey $key[Down] down-line-or-history
bindkey $key[ControlSpace] set-mark-command
# The lines above revert the given keys back to Zsh defaults.
ยฉ 2020 Marlon Richert
This project is licensed under the MIT License. See the LICENSE file for details.