zsh-autosuggestions/README.md

zsh-autosuggestions

Fish-like fast/unobtrusive autosuggestions for zsh.

It suggests commands as you type, based on command history.

Installation

If you already use zsh-syntax-highlighting plugin, then make sure to be loaded before zsh-autosuggestions.

Note: .zshrc is a file that contains user-specific ZSH configuration. ZSH assumes this file in your home directory (i.e. ~/.zshrc), but the location can be changed using ZDOTDIR variable.

Using zgen

Zgen is a simple and fast plugin manager for ZSH. If you don’t use zgen, then use instructions for the manual installation.

1. Load tarruda/zsh-autosuggestions and zsh-users/zsh-syntax-highlighting using zgen in your .zshrc file, for example:

   if ! zgen saved; then
       echo "Creating a zgen save"
   
       zgen load zsh-users/zsh-syntax-highlighting
   
       # autosuggestions should be loaded last
       zgen load tarruda/zsh-autosuggestions
   
       zgen save
   fi
   

2. Enable zsh-autosuggestions; copy the following snippet and put it after the zgen config section in your .zshrc file:

   # Enable autosuggestions automatically.
   zle-line-init() {
       zle autosuggest-start
   }
   zle -N zle-line-init
   

3. Run zgen reset and reopen your terminal.

Manually

1. Clone this repository to ~/.zsh/zsh-autosuggestions (or anywhere else):

   git clone git://github.com/tarruda/zsh-autosuggestions ~/.zsh/zsh-autosuggestions
   

2. Clone zsh-syntax-highlighting repository to ~/.zsh/zsh-syntax-highlighting (or anywhere else):

   git clone git://github.com/zsh-users/zsh-syntax-highlighting ~/.zsh/zsh-syntax-highlighting
   

3. Load and enable autosuggestions; copy the following snippet and put it to your .zshrc file:

   # Load zsh-syntax-highlighting.
   source ~/.zsh/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
   
   # Load zsh-autosuggestions.
   source ~/.zsh/zsh-autosuggestions/autosuggestions.zsh
   
   # Enable autosuggestions automatically.
   zle-line-init() {
       zle autosuggest-start
   }
   zle -N zle-line-init
   

4. Reopen your terminal.

Uninstallation

Just remove the config lines from .zshrc that you’ve added during “installation.” If you don’t use zgen, then also delete ~/.zsh/zsh-autosuggestions and ~/.zsh/zsh-syntax-highlighting.

How to use

As you type commands, you will see a completion offered after the cursor, in a muted gray color (which can be changed, see Configuration). To accept the autosuggestion (replacing the command line contents), hit End, Alt+F, Ctrl+F, or any other key that moves the cursor to the right. If the autosuggestion is not what you want, just ignore it: it won’t execute unless you accept it.

Any widget that moves the cursor to the right (forward-word, forward-char, end-of-line…) will accept parts of the suggested text. For example, vi-mode users can do this:

# Accept suggestions without leaving insert mode
bindkey '^f' vi-forward-word
# or
bindkey '^f' vi-forward-blank-word

You can also use right arrow key to accept the suggested text as in Fish shell; see Configuration section to enable it.

Exposed widgets

This plugin defines some ZLE widgets (think about them as functions) which you can bind to some key using bindkey. For example, to toggle autosuggestions using Ctrl+T add this to your .zshrc:

bindkey '^T' autosuggest-toggle

List of widgets:

• autosuggest-toggle – disable/enable autosuggestions.
• autosuggest-execute-suggestion – accept the suggestion and execute it.

Configuration

You may override default global config variables after plugin load, i.e. put it to your .zshrc after the code that loads plugins.

• AUTOSUGGESTION_HIGHLIGHT_COLOR – suggestion highlight color, default is 'fg=8'.
• AUTOSUGGESTION_HIGHLIGHT_CURSOR – highlight word after cursor, or not. Must be integer value 1 or 0, default is 1.
• AUTOSUGGESTION_ACCEPT_RIGHT_ARROW – complete entire suggestion with right arrow. Must be integer value 1 or 0, default is 0 (right arrow completes one letter at a time).

Known Issues

When I hit Tab and autosuggestions is enabled, it deletes the previous line, and scrolls up the terminal.

This usually happens when autosuggestions is used along with something like “completion waiting dots.” Check which widget is bind to the Tab key; run bindkey "^I". If it prints something other than "^I" expand-or-complete, then this may be the problem.

If you use Oh My Zsh, then make sure that the variable COMPLETION_WAITING_DOTS is not set (it enables this problematic code).

If you use module editor from Prezto, then you must comment out these lines.

License

This project is licensed under MIT license. For the full text of the license, see the LICENSE file.