/zsh-autocomplete

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

Primary LanguageShellMIT LicenseMIT

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! 💝

file-search

(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-search

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.

history menu

Multi-selection

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

multi-select

Recent dirs completion

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

recent dirs

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

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

© 2020-2023 Marlon Richert

License

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