149 lines
5.6 KiB
Markdown
149 lines
5.6 KiB
Markdown
# `zsh-autocomplete`
|
|
`zsh-autocomplete` adds **real-time type-ahead autocompletion** to Zsh. Find as you type, then
|
|
press <kbd>Tab</kbd> to insert the top completion, <kbd>Shift</kbd><kbd>Tab</kbd> to insert the
|
|
bottom one, or <kbd>↓</kbd>/<kbd>PgDn</kbd> to select another completion.
|
|
|
|
[](https://asciinema.org/a/377611)
|
|
|
|
> Enjoy using this software? [Become a sponsor!](https://github.com/sponsors/marlonrichert).
|
|
|
|
## Other Features
|
|
Besides live autocompletion, `zsh-autocomplete` comes with many other useful completion features.
|
|
|
|
### Optimized completion config
|
|
Zsh's completion system is powerful, but hard to configure. So, `zsh-autocomplete` [does it for
|
|
you](scripts/.autocomplete.config), while providing a manageable list of [configuration
|
|
settings](.zshrc) for changing the defaults.
|
|
|
|
### Live history search
|
|
Press <kbd>Ctrl</kbd><kbd>R</kbd> or <kbd>Ctrl</kbd><kbd>S</kbd> to do live, multi-line history
|
|
search.
|
|
|
|
[](https://asciinema.org/a/379844)
|
|
|
|
### History menu
|
|
Press <kbd>↑</kbd> (or <kbd>Alt</kbd><kbd>↑</kbd> or <kbd>PgUp</kbd>) 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 <kbd>Ctrl</kbd><kbd>Space</kbd> 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 supports `zsh-z`, `zoxide`, `z.lua`,
|
|
`rupa/z.sh`, `autojump` and `fasd`.
|
|
|
|
|
|
|
|
## Key Bindings
|
|
|
|
On the command line:
|
|
| Key(s) | Action | <sub>[Widget](.zshrc)</sub> |
|
|
| ------ | ------ | --- |
|
|
| <kbd>Tab</kbd> | Accept top completion | <sub>`complete-word`</sub> |
|
|
| <kbd>Shift</kbd><kbd>Tab</kbd> | Accept bottom completion | <sub>`complete-word`</sub> |
|
|
| <kbd>Ctrl</kbd><kbd>Space</kbd> | Show additional completions | <sub>`list-expand`</sub> |
|
|
| <kbd>↓</kbd> | Cursor down (if able) or completion menu | <sub>`down-line-or-select`</sub> |
|
|
| <kbd>PgDn</kbd> / <kbd>Alt</kbd><kbd>↓</kbd> | Completion menu (always) | <sub>`menu-select`</sub> |
|
|
| <kbd>↑</kbd> | Cursor up (if able) or [history menu](#history-menu) | <sub>`up-line-or-search`</sub> |
|
|
| <kbd>PgUp</kbd> / <kbd>Alt</kbd><kbd>↑</kbd> | [History menu](#history-menu) (always) | <sub>`history-search`</sub> |
|
|
| <kbd>Ctrl</kbd><kbd>R</kbd> | [Live history search](#live-history-search), newest to oldest | <sub>`history-incremental-search-backward`</sub> |
|
|
| <kbd>Ctrl</kbd><kbd>S</kbd> | [Live history search](#live-history-search), oldest to newest | <sub>`history-incremental-search-forward`</sub> |
|
|
|
|
In the completion menu:
|
|
| Key(s) | Action |
|
|
| ------ | ------ |
|
|
| <kbd>↑</kbd> / <kbd>↓</kbd> / <kbd>←</kbd> / <kbd>→</kbd> | Change selection |
|
|
| <kbd>Alt</kbd><kbd>↑</kbd> | Backward one group |
|
|
| <kbd>Alt</kbd><kbd>↓</kbd> | Forward one group |
|
|
| <kbd>PgUp</kbd> / <kbd>PgDn</kbd> | Page up/down |
|
|
| <kbd>Ctrl</kbd><kbd>R</kbd> | Full text search or previous search match |
|
|
| <kbd>Ctrl</kbd><kbd>S</kbd> | Full text search or next search match |
|
|
| <kbd>Ctrl</kbd><kbd>Space</kbd> | Multi-select |
|
|
| <kbd>Tab</kbd> | Accept selection |
|
|
| <kbd>Shift</kbd><kbd>Tab</kbd> | Accept bottom completion |
|
|
| <kbd>Enter</kbd> | Accept command line |
|
|
| most other keys | Accept selection, then perform usual action |
|
|
|
|
In the history menu:
|
|
| Key(s) | Action |
|
|
| --- | --- |
|
|
| <kbd>↑</kbd>/<kbd>↓</kbd> | Change selection |
|
|
| <kbd>Ctrl</kbd><kbd>Space</kbd> | Multi-select |
|
|
| <kbd>Tab</kbd> | Accept selection |
|
|
| <kbd>Enter</kbd> | Accept command line |
|
|
| most other keys | Accept selection, then perform usual action |
|
|
|
|
## Requirements
|
|
Recommended:
|
|
* Tested to work with [Zsh](http://zsh.sourceforge.net) 5.7 or newer.
|
|
|
|
Minimum:
|
|
* Should theoretically work with Zsh 5.4 or newer, but I'm unable to test that.
|
|
|
|
## Installing & Updating
|
|
If you use [Znap](https://github.com/marlonrichert/zsh-snap), simply add the following to your
|
|
`.zshrc` file:
|
|
```zsh
|
|
znap source marlonrichert/zsh-autocomplete
|
|
```
|
|
Then restart your shell.
|
|
|
|
To update, do
|
|
```zsh
|
|
% znap pull
|
|
```
|
|
|
|
For configuration options, see the included [`.zshrc` file](.zshrc).
|
|
|
|
To uninstall, remove `znap source marlonrichert/zsh-autocomplete` from your `.zshrc` file, then run
|
|
```zsh
|
|
% znap uninstall
|
|
```
|
|
|
|
### Manual installation
|
|
1. Clone the repo:
|
|
```zsh
|
|
% cd ~/Git # ...or wherever you keep your Git repos/Zsh plugins
|
|
% git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git
|
|
```
|
|
1. Add at or near the top of your `.zshrc` file (_before_ any calls to `compdef`):
|
|
```zsh
|
|
source ~/Git/zsh-autocomplete/zsh-autocomplete.plugin.zsh
|
|
```
|
|
1. Remove any calls to `compinit` from your `.zshrc` file.
|
|
1. If you're using Ubuntu, add to your `.zshenv` file:
|
|
```zsh
|
|
skip_global_compinit=1
|
|
```
|
|
Then restart your shell.
|
|
|
|
To update, do:
|
|
```zsh
|
|
% 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.
|
|
1. Delete the line you added in step 2.
|
|
1. Delete the repo you created in step 1.
|
|
Finally, 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.
|
|
|
|
## Troubleshooting
|
|
Try the steps in the [bug report template](.github/ISSUE_TEMPLATE/bug-report.md).
|
|
|
|
## Author
|
|
© 2020-2021 [Marlon Richert](https://github.com/marlonrichert)
|
|
|
|
## License
|
|
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|