kud / zsh-autocomplete

🤖 Real-time type-ahead completion for Zsh. Asynchronous find-as-you-type autocompletion.

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

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

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

Note for NixOS

Both the NixOS and the Home Manager modules for Zsh enable completion by default. The option is named the same thing in both: programs.zsh.enableCompletion. Make sure that you explicitly disable this in whichever module you're using - possibly both.

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.

Pass arguments to compinit

If necessary, you can let Autocomplete pass arguments to compinit as follows:

zstyle '*:compinit' arguments -D -i -u -C -w

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() {
  typeset -ga 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() {
  typeset -ga reply=( [code that generates an array of absolute paths] )
}

Start each new line in history search mode

This will make Autocomplete behave as if you pressed CtrlR at the start of each new command line:

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

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

Normally, Autocomplete fetches completions after you stop typing for about 0.05 seconds. You can change this as follows:

zstyle ':autocomplete:*' delay 0.1  # seconds (float)

Don't show completions if the current word matches a pattern

For example, this will stop completions from showing whenver the current word consists of two or more dots:

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

Limit the number of lines shown

By default, Autocomplete let the history menu fill half of the screen, and limits autocompletion and history search to maximum of 16 lines. You can change these limits as follows:

# Autocompletion
zstyle -e ':autocomplete:list-choices:*' list-lines 'reply=( $(( LINES / 3 )) )'

# Override history search.
zstyle ':autocomplete:history-incremental-search-backward:*' list-lines 8

# History menu.
zstyle ':autocomplete:history-search-backward:*' list-lines 256

Note that for autocompletion and history search, the maximum number of lines is additionally capped to the number of lines that fit on screen. However, there is no such limit for the history menu. If that generates more lines than fit on screen, you can simply scroll upwards to see more.

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

© 2020-2023 Marlon Richert

License

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