Autocomplete for Zsh

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

Other Features

Besides autocompletion, Autocomplete comes with many other useful completion features.

Optimized completion config

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.

Fuzzy multi-line history search

Press CtrlR to do a real-time history search listing multiple results.

History menu

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.

Multi-selection

Press CtrlSpace in the completion menu or the history menu to insert more than one item.

Recent dirs completion

Works out of the box with zero configuration, but also lets you use your favorite tool for tracking directories instead.

Key Bindings

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.

On the command line

`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

In the menus

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.

Requirements

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.

Installing & Updating

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

Manual installation

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 to compdef): 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.

Other frameworks/plugin managers

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.

Additional step for Ubuntu

If you're using Ubuntu, you additionally need to add the following to your .zshenv file:

skip_global_compinit=1

Troubleshooting

Try the steps in the bug report template.

Configuration

The following are the most commonly requested ways to configure Autocomplete's behavior. Add these to your .zshrc file to use them.

Reassign `Tab`

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:

Make `Tab` and `ShiftTab` cycle completions on the command line

bindkey '\t' menu-complete "$terminfo[kcbt]" reverse-menu-complete

Make `Tab` go straight to the menu and cycle there

bindkey '\t' menu-select "$terminfo[kcbt]" menu-select
bindkey -M menuselect '\t' menu-complete "$terminfo[kcbt]" reverse-menu-complete

First insert the common substring

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

Make `Enter` submit the command line straight from the menu

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

Add or don't add a space after certain completions

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.

Use a custom backend for recent directories

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] )
}

Add a backend for recent files

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] )
}

Start each new line in history search mode

zstyle ':autocomplete:*' default-context history-incremental-search-backward

Wait with autocompletion until typing stops for a certain amount of seconds

zstyle ':autocomplete:*' min-delay 0.05  # seconds (float)

Don't show completion for current word, if it consists of two or more dots

zstyle ':autocomplete:*' ignored-input '..##'

Limit the number of lines shown

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.

Reset history key bindings to Zsh default

Add any of the following to your .zshrc file after sourcing Autocomplete:

Reset `↑` and `↓`

() {
   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
}

Reset `CtrlR` and `CtrlS`

   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
}

Author

License

This project is licensed under the MIT License. See the LICENSE file for details.

tshu-w/zsh-autocomplete