Autocomplete for Zsh adds real-time type-ahead autocompletion to Zsh. Find as you type, then press Tab to insert the top completion or ↓to select another completion.
Enjoy using this software? Become a sponsor! 💝
(The look and feel shown in images here might not be up to date.
Besides autocompletion, Autocomplete comes with many other useful completion features.
Zsh's completion system is powerful, but hard to configure. So, let Autocomplete do it for you, while providing a manageable list of configuration settings for changing the defaults.
Press CtrlR to do a real-time history search listing multiple results.
Press ↑ to open a menu with the last 16 history items. If the command line is not empty, then the contents of the command line are used to perform a fuzzy history search.
Press CtrlSpace in the completion menu or the history menu to insert more than one item.
Works out of the box with zero configuration, but also lets you use your favorite tool for tracking directories instead.
- Depending on your terminal, not all keybindings might be available to you.
- Instead of Alt, your terminal might require you to press Escape, Option or Meta.
- In most terminals, Enter is interchangeable with Return, but in some terminals, it is not.
main |
emacs |
vicmd |
viins |
Action |
---|---|---|---|---|
Tab | Tab | Insert top completion | ||
ShiftTab | Insert substring occuring in all listed completions | |||
↑ | CtrlP | K | Cursor up -or- History menu | |
↓ | CtrlN | J | Cursor down -or- Completion menu | |
Alt↑ | AltP | ShiftN | History menu (always) | |
Alt↓ | AltN | N | Completion menu (always) | |
CtrlS | ? | Search through all menu text | ||
CtrlR | / | Toggle history search mode on/off |
Key(s) | Action |
---|---|
↑ ↓ ← → | Change selection |
Alt↑ | Backward one group (completion only) |
Alt↓ | Forward one group (completion only) |
PgUp AltV |
Page up |
PgDn CtrlV |
Page down |
CtrlS | Enter search mode -or- Go to next match |
CtrlR | Enter search mode -or- Go to previous match |
Tab Enter |
Exit search mode -or- Exit menu |
CtrlSpace | Add another completion |
Ctrl- Ctrl/ |
Remove last completion |
CtrlG | Remove all completions |
Other keys | Depends on the keymap from which you opened the menu. See the Zsh manual on menu selection. |
Recommended:
- Tested to work with Zsh 5.8 and newer.
Minimum:
- Should theoretically work with Zsh 5.4, but I'm unable to test that.
If you use Znap, simply add the
following to your .zshrc
file:
znap source marlonrichert/zsh-autocomplete
Then restart your shell.
To update, do
% znap pull
To uninstall, remove znap source marlonrichert/zsh-autocomplete
from your
.zshrc
file, then run
% znap uninstall
- Clone the repo:
% cd ~/Repos # ...or wherever you keep your Git repos/Zsh plugins % git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git
- Add at or near the top of your
.zshrc
file (before any calls tocompdef
):zsh source ~/Repos/zsh-autocomplete/zsh-autocomplete.plugin.zsh
- Remove any calls to
compinit
from your.zshrc
file. - Restart your shell.
To update, do:
% git -C ~zsh-autocomplete pull
To uninstall, simply undo the installation steps above in reverse order:
- Restore the lines you deleted in step 3.
- Delete the line you added in step 2.
- Delete the repo you created in step 1.
- Restart your shell.
To install with another Zsh framework or plugin manager, please refer to your framework's/plugin manager's documentation for instructions. When in doubt, install manually.
If you're using Ubuntu, you additionally need to add the following to your
.zshenv
file:
skip_global_compinit=1
Try the steps in the bug report template.
The following are the most commonly requested ways to configure Autocomplete's
behavior. Add these to your .zshrc
file to use them.
You can reassign Tab to do something else than the default. This includes letting another plugin set it. Here are two examples of what you can do with this:
bindkey '\t' menu-complete "$terminfo[kcbt]" reverse-menu-complete
bindkey '\t' menu-select "$terminfo[kcbt]" menu-select
bindkey -M menuselect '\t' menu-complete "$terminfo[kcbt]" reverse-menu-complete
You can make any completion widget first insert the sequence of characters that's common to all completions, if any, before inserting actual completions:
# all Tab widgets
zstyle ':autocomplete:*complete*:*' insert-unambiguous yes
# all history widgets
zstyle ':autocomplete:*history*:*' insert-unambiguous yes
# ^S
zstyle ':autocomplete:menu-search:*' insert-unambiguous yes
By default, pressing Enter in the menu search exits the search and pressing it otherwise in the menu exits the menu. If you instead want to make Enter always submit the command line, use the following:
bindkey -M menuselect '\r' .accept-line
When inserting a completion, a space is added after certain types of completions. The default list is as follows:
zstyle ':autocomplete:*' add-space \
executables aliases functions builtins reserved-words commands
Modifying this list will change when a space is inserted. If you change the
list to '*'
, a space is always inserted. If you put no elements in the list,
then a space is never inserted.
Autocomplete comes with its own backend for keeping track of and listing recent
directories (which uses part of
cdr
under the hood). However, you can override this and supply Autocomplete with
recent directories from any source that you like. To do so, define a function
like this:
+autocomplete:recent-directories() {
reply=( [code that generates an array of absolute paths] )
}
Out of the box, Autocomplete doesn't track or offer recent files. However, it will do so if you add a backend for it:
+autocomplete:recent-files() {
reply=( [code that generates an array of absolute paths] )
}
zstyle ':autocomplete:*' default-context history-incremental-search-backward
zstyle ':autocomplete:*' min-delay 0.05 # seconds (float)
zstyle ':autocomplete:*' ignored-input '..##'
Normally, Autocomplete will try to one half of the terminal's height with results, be it completions, the history menu or history search. You can change this number of lines overall or for each of these individually:
# Set the value for all.
zstyle -e ':autocomplete:*' list-lines 'reply=( $(( LINES / 3 )) )'
# Override autocompletion.
zstyle -e ':autocomplete:list-choices:*' list-lines 'reply=( $(( LINES / 3 )) )'
# Override history menu.
zstyle ':autocomplete:history-search-backward:*' list-lines 16
# Override history search.
zstyle ':autocomplete:history-incremental-search-backward:*' list-lines 16
zstle -e
creates a dynamic value.
Add any of the following to your .zshrc
file after sourcing Autocomplete:
() {
local -a prefix=( '\e'{\[,O} )
local -a up=( ${^prefix}A ) down=( ${^prefix}B )
local key=
for key in $up[@]; do
bindkey "$key" up-line-or-history
done
for key in $down[@]; do
bindkey "$key" down-line-or-history
done
}
zle -A {.,}history-incremental-search-backward
zle -A {.,}vi-history-search-backward
bindkey -M emacs '^S' history-incremental-search-forward
bindkey -M vicmd '/' vi-history-search-forward
}
© 2020-2023 Marlon Richert
This project is licensed under the MIT License. See the LICENSE file for details.