Autocomplete for Zsh

This plugin for Zsh adds real-time type-ahead autocompletion to your command line, similar to what you find in desktop apps. While you type on the command line, available completions are listed automatically; no need to press any keyboard shortcuts. Press Tab to insert the top completion or ↓ to select a different one.

Additional features:

• Out-of-the-box configuration of Zsh's completion system
• Multi-line history search
• Completion of recent directories
• Useful keyboard shortcuts
• Easy to configure

Enjoy using this software? Become a sponsor! 💝

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.

Installation & setup

Note: In this manual, % represents the command line prompt. If you see it in front of a command, it means you should run it on the command line, not put it in a script.

First, install Autocomplete itself. Here are some way to do so:

• To use only releases (instead of the main branch), install zsh-autocomplete with a package manager. As of this writing, this package is available through Homebrew, Nix, pacman, Plumage, and (as app-shells/zsh-autocomplete) Portage.
• To always use the latest commit on the main branch, do one of the following:
  • Install the AUR package zsh-autocomplete-git^AUR from the Arch User Repository (for example, using yay, an AUR helper):

     yay -S zsh-autocomplete-git

  • Use a Zsh plugin manager to install marlonrichert/zsh-autocomplete. (If you don't have a plugin manager yet, I recommend using Znap.)
  • Clone the repo directly:

    % git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git

After installing, make the following modifications to your shell config:

• In your .zshrc file:
  • Remove any calls to compinit.
  • Add near the top, before any calls to compdef:

    source /path/to/zsh-autocomplete/zsh-autocomplete.plugin.zsh

• When using Ubuntu, add to your .zshenv file:

  skip_global_compinit=1

• When using Nix, add to your home.nix file:

  programs.zsh.enableCompletion = false;
  

Finally, restart your shell. Here's two ways to do so:

• Open a new tab or window in your terminal.
• Replace the current shell with a new one:

  % exec zsh

Updating

If you installed manually, run:

% git -C ~autocomplete pull

Otherwise, simply use your package manager or plugin manager's update mechanisms.

Uninstalling

1. Revert the actions you took to install.
2. Restart your shell.

Keyboard shortcuts

The keyboard shortcuts below are available after installing Autocomplete in clean Zsh environment. Other plugins or scripts might override these bindings. If you find that some shortcuts don't work as expected, then you can fix them by

• changing the order in which you source your plugins or by
• running bindkey commands in your dotfiles after you source your plugins.

Depending on your terminal, not all keybindings might work for you. Also, instead of Alt, your terminal might require you to press Escape, Option or Meta. Finally, for keys that otherwise navigate the terminal buffer, such as PgDn and PgUp, your terminal will require you to additionally press Shift or another modifier key.

On the command line

The table below lists which keyboard shortcuts are available on the command line when a particular keymap is active. The default keymap on the command line is main, which is not an actual keymap but an alias for another one. When Autocomplete adds shortcuts to main, they will actually be added to the keymap for which it at that point is an alias. If you run bindkey -v, then main becomes an alias for viins.

main	emacs	vicmd	Command
Tab			Insert first listed completion
ShiftTab			Expand the current word
↓	CtrlN	J	Cursor down or enter completion menu
Alt↓	AltN	CtrlN	Enter completion menu
↑	CtrlP	K	Cursor up or enter history menu
Alt↑	AltP	CtrlP	Enter history menu
	CtrlX /		Toggle recent path completion
	CtrlR	/	Toggle history completion
	CtrlS	?	Enter completion menu and start text search

Inside each menu

The shortcuts below are available inside both completion and history menus. They are defined in the menuselect keymap and can be modified there. If a key is not bound in menuselect, then its behavior depends on the keymap from which you opened the menu. See the Zsh manual's section on menu selection for more info.

Key sequence	Command
Tab ShiftTab	Next/previous item
→ ← ↓ ↑	Item right/left/down/up
Alt↓ Alt↑	Section down/up
PgDn PgUp	Page down/up
CtrlS CtrlR	Start menu text search or go to next/previous match
Enter Return	Stop text search or exit menu
CtrlSpace	Add another item
Ctrl- Ctrl/	Undo last added item
CtrlC CtrlG	Undo all added items and exit menu

Configuration

See CONFIGURATION.md for the most commonly requested ways to configure Autocomplete's behavior.

Troubleshooting

Try the steps in the bug report template.

Author & License

See the LICENSE file for details.