zsh-autosuggestions/README.md

158 lines
5.6 KiB
Markdown
Raw Normal View History

2013-10-26 18:05:17 +02:00
# zsh-autosuggestions
2015-05-21 20:23:09 +02:00
_[Fish](http://fishshell.com/)-like fast/unobtrusive autosuggestions for zsh._
It suggests commands as you type, based on command history.
2016-02-25 21:20:21 +01:00
<a href="https://asciinema.org/a/37390" target="_blank"><img src="https://asciinema.org/a/37390.png" width="400" /></a>
2013-10-26 18:05:17 +02:00
## Installation
### Manual
2016-02-05 23:14:08 +01:00
1. Clone this repository somewhere on your machine. This guide will assume `~/.zsh/zsh-autosuggestions`.
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
```sh
git clone git://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions
2016-02-05 23:14:08 +01:00
```
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
2. Add the following to your `.zshrc`:
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
```sh
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
2016-02-05 23:14:08 +01:00
```
2015-05-21 20:23:09 +02:00
3. Start a new terminal session.
2015-05-21 20:23:09 +02:00
### Oh My Zsh
1. Clone this repository into `$ZSH_CUSTOM/plugins` (by default `~/.oh-my-zsh/custom/plugins`)
```sh
git clone git://github.com/zsh-users/zsh-autosuggestions $ZSH_CUSTOM/plugins/zsh-autosuggestions
```
2. Add the plugin to the list of plugins for Oh My Zsh to load:
```sh
plugins=(zsh-autosuggestions)
```
3. Start a new terminal session.
2016-02-05 23:14:08 +01:00
## Usage
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
As you type commands, you will see a completion offered after the cursor in a muted gray color. This color can be changed by setting the `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` variable. See [configuration](#configuration).
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
If you press the <kbd></kbd> key (`forward-char` widget) or <kbd>End</kbd> (`end-of-line` widget) with the cursor at the end of the buffer, it will accept the suggestion, replacing the contents of the command line buffer with the suggestion.
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
If you invoke the `forward-word` widget, it will partially accept the suggestion up to the point that the cursor moves to.
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
## Configuration
2015-05-21 20:23:09 +02:00
2016-02-07 22:50:00 +01:00
You may want to override the default global config variables after sourcing the plugin. Default values of these variables can be found [here](src/config.zsh).
2015-05-21 20:23:09 +02:00
**Note:** If you are using Oh My Zsh, you can put this configuration in a file in the `$ZSH_CUSTOM` directory. See their comments on [overriding internals](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals).
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
### Suggestion Highlight Style
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
Set `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` to configure the style that the suggestion is shown with. The default is `fg=8`.
2015-05-21 20:23:09 +02:00
### Suggestion Strategy
Set `ZSH_AUTOSUGGEST_STRATEGY` to choose the strategy for generating suggestions. There are currently two to choose from:
- `default`: Chooses the most recent match.
- `match_prev_cmd`: Chooses the most recent match whose preceding history item matches the most recently executed command ([more info](src/strategies/match_prev_cmd.zsh)).
2016-02-05 23:14:08 +01:00
### Widget Mapping
2016-02-05 23:14:08 +01:00
This plugin works by triggering custom behavior when certain [zle widgets](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Zle-Widgets) are invoked. You can add and remove widgets from these arrays to change the behavior of this plugin:
2016-02-05 23:14:08 +01:00
- `ZSH_AUTOSUGGEST_CLEAR_WIDGETS`: Widgets in this array will clear the suggestion when invoked.
- `ZSH_AUTOSUGGEST_ACCEPT_WIDGETS`: Widgets in this array will accept the suggestion when invoked.
- `ZSH_AUTOSUGGEST_EXECUTE_WIDGETS`: Widgets in this array will execute the suggestion when invoked.
2016-02-05 23:14:08 +01:00
- `ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS`: Widgets in this array will partially accept the suggestion when invoked.
2015-05-21 20:23:09 +02:00
Widgets not in any of these lists will update the suggestion when invoked.
2016-02-05 23:14:08 +01:00
**Note:** A widget shouldn't belong to more than one of the above arrays.
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
### Key Bindings
2015-05-21 20:23:09 +02:00
This plugin provides three widgets that you can use with `bindkey`:
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
1. `autosuggest-accept`: Accepts the current suggestion.
2. `autosuggest-execute`: Accepts and executes the current suggestion.
3. `autosuggest-clear`: Clears the current suggestion.
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
For example, this would bind <kbd>ctrl</kbd> + <kbd>space</kbd> to accept the current suggestion.
2015-05-21 20:23:09 +02:00
2016-02-05 23:14:08 +01:00
```sh
bindkey '^ ' autosuggest-accept
```
2016-02-07 16:52:07 +01:00
## Troubleshooting
If you have a problem, please search through [the list of issues on GitHub](https://github.com/zsh-users/zsh-autosuggestions/issues) to see if someone else has already reported it.
2016-02-07 16:52:07 +01:00
### Reporting an Issue
Before reporting an issue, please try temporarily disabling sections of your configuration and other plugins that may be conflicting with this plugin to isolate the problem.
When reporting an issue, please include:
- The smallest, simplest `.zshrc` configuration that will reproduce the problem. See [this comment](https://github.com/zsh-users/zsh-autosuggestions/issues/102#issuecomment-180944764) for a good example of what this means.
2016-02-07 16:52:07 +01:00
- The version of zsh you're using (`zsh --version`)
- Which operating system you're running
2016-02-05 23:14:08 +01:00
## Uninstallation
2016-02-05 23:14:08 +01:00
1. Remove the code referencing this plugin from `~/.zshrc`.
2016-02-05 23:14:08 +01:00
2. Remove the git repository from your hard drive
2016-02-05 23:14:08 +01:00
```sh
rm -rf ~/.zsh/zsh-autosuggestions # Or wherever you installed
```
2015-05-21 20:23:09 +02:00
## Development
### Build Process
Edit the source files in `src/`. Run `make` to build `zsh-autosuggestions.zsh` from those source files.
### Pull Requests
Pull requests are welcome! If you send a pull request, please:
- Match the existing coding conventions.
- Include helpful comments to keep the barrier-to-entry low for people new to the project.
- Write tests that cover your code as much as possible.
### Testing
Testing is performed with [`shunit2`](https://github.com/kward/shunit2) (v2.1.6). Documentation can be found [here](http://shunit2.googlecode.com/svn/trunk/source/2.1/doc/shunit2.html).
2016-04-15 21:40:18 +02:00
The test script lives at `script/test_runner.zsh`. To run the tests, run `make test`.
2015-05-21 20:23:09 +02:00
## License
This project is licensed under [MIT license](http://opensource.org/licenses/MIT).
For the full text of the license, see the [LICENSE](LICENSE) file.