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.

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

1. 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

2. Add at or near the top of your .zshrc file (before any calls to compdef): zsh source ~/Repos/zsh-autocomplete/zsh-autocomplete.plugin.zsh
3. Remove any calls to compinit from your .zshrc file.
4. Restart your shell.

To update, do:

% git -C ~zsh-autocomplete pull

To uninstall, simply undo the installation steps above in reverse order:

1. Restore the lines you deleted in step 3.
2. Delete the line you added in step 2.
3. Delete the repo you created in step 1.
4. 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.