Mercurial > dotfiles

comparison .zfun/zsh-autosuggestions/README.md @ 467:e1ce8897030d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
zsh: import df6f6f9ff41 of zsh-autosuggestions
author Augie Fackler <raf@durin42.com>
date Mon, 03 Dec 2018 22:37:29 -0500
parents
children
comparison
equal deleted inserted replaced
466:f248cf012d9a 467:e1ce8897030d
1 # zsh-autosuggestions
2
3 _[Fish](http://fishshell.com/)-like fast/unobtrusive autosuggestions for zsh._
4
5 It suggests commands as you type, based on command history.
6
7 Requirements: Zsh v4.3.11 or later
8
9 [![CircleCI](https://circleci.com/gh/zsh-users/zsh-autosuggestions.svg?style=svg)](https://circleci.com/gh/zsh-users/zsh-autosuggestions)
10
11 <a href="https://asciinema.org/a/37390" target="_blank"><img src="https://asciinema.org/a/37390.png" width="400" /></a>
12
13
14 ## Installation
15
16 See [INSTALL.md](INSTALL.md).
17
18
19 ## Usage
20
21 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).
22
23 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.
24
25 If you invoke the `forward-word` widget, it will partially accept the suggestion up to the point that the cursor moves to.
26
27
28 ## Configuration
29
30 You may want to override the default global config variables. Default values of these variables can be found [here](src/config.zsh).
31
32 **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).
33
34
35 ### Suggestion Highlight Style
36
37 Set `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` to configure the style that the suggestion is shown with. The default is `fg=8`.
38
39
40 ### Suggestion Strategy
41
42 `ZSH_AUTOSUGGEST_STRATEGY` is an array that specifies how suggestions should be generated. The strategies in the array are tried successively until a suggestion is found. There are currently two built-in strategies to choose from:
43
44 - `history`: Chooses the most recent match from history.
45 - `match_prev_cmd`: Like `history`, but chooses the most recent match whose preceding history item matches the most recently executed command ([more info](src/strategies/match_prev_cmd.zsh)). Note that this strategy won't work as expected with ZSH options that don't preserve the history order such as `HIST_IGNORE_ALL_DUPS` or `HIST_EXPIRE_DUPS_FIRST`.
46
47
48 ### Widget Mapping
49
50 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:
51
52 - `ZSH_AUTOSUGGEST_CLEAR_WIDGETS`: Widgets in this array will clear the suggestion when invoked.
53 - `ZSH_AUTOSUGGEST_ACCEPT_WIDGETS`: Widgets in this array will accept the suggestion when invoked.
54 - `ZSH_AUTOSUGGEST_EXECUTE_WIDGETS`: Widgets in this array will execute the suggestion when invoked.
55 - `ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS`: Widgets in this array will partially accept the suggestion when invoked.
56 - `ZSH_AUTOSUGGEST_IGNORE_WIDGETS`: Widgets in this array will not trigger any custom behavior.
57
58 Widgets that modify the buffer and are not found in any of these arrays will fetch a new suggestion after they are invoked.
59
60 **Note:** A widget shouldn't belong to more than one of the above arrays.
61
62
63 ### Disabling suggestion for large buffers
64
65 Set `ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE` to an integer value to disable autosuggestion for large buffers. The default is unset, which means that autosuggestion will be tried for any buffer size. Recommended value is 20.
66 This can be useful when pasting large amount of text in the terminal, to avoid triggering autosuggestion for too long strings.
67
68 ### Enable Asynchronous Mode
69
70 As of `v0.4.0`, suggestions can be fetched asynchronously using the `zsh/zpty` module. To enable this behavior, set the `ZSH_AUTOSUGGEST_USE_ASYNC` variable (it can be set to anything).
71
72
73 ### Key Bindings
74
75 This plugin provides a few widgets that you can use with `bindkey`:
76
77 1. `autosuggest-accept`: Accepts the current suggestion.
78 2. `autosuggest-execute`: Accepts and executes the current suggestion.
79 3. `autosuggest-clear`: Clears the current suggestion.
80 4. `autosuggest-fetch`: Fetches a suggestion (works even when suggestions are disabled).
81 5. `autosuggest-disable`: Disables suggestions.
82 6. `autosuggest-enable`: Re-enables suggestions.
83 7. `autosuggest-toggle`: Toggles between enabled/disabled suggestions.
84
85 For example, this would bind <kbd>ctrl</kbd> + <kbd>space</kbd> to accept the current suggestion.
86
87 ```sh
88 bindkey '^ ' autosuggest-accept
89 ```
90
91
92 ## Troubleshooting
93
94 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.
95
96
97 ### Reporting an Issue
98
99 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.
100
101 When reporting an issue, please include:
102
103 - 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.
104 - The version of zsh you're using (`zsh --version`)
105 - Which operating system you're running
106
107
108 ## Uninstallation
109
110 1. Remove the code referencing this plugin from `~/.zshrc`.
111
112 2. Remove the git repository from your hard drive
113
114 ```sh
115 rm -rf ~/.zsh/zsh-autosuggestions # Or wherever you installed
116 ```
117
118
119 ## Development
120
121 ### Build Process
122
123 Edit the source files in `src/`. Run `make` to build `zsh-autosuggestions.zsh` from those source files.
124
125
126 ### Pull Requests
127
128 Pull requests are welcome! If you send a pull request, please:
129
130 - Request to merge into the `develop` branch (*NOT* `master`)
131 - Match the existing coding conventions.
132 - Include helpful comments to keep the barrier-to-entry low for people new to the project.
133 - Write tests that cover your code as much as possible.
134
135
136 ### Testing
137
138 Tests are written in ruby using the [`rspec`](http://rspec.info/) framework. They use [`tmux`](https://tmux.github.io/) to drive a pseudoterminal, sending simulated keystrokes and making assertions on the terminal content.
139
140 Test files live in `spec/`. To run the tests, run `make test`. To run a specific test, run `TESTS=spec/some_spec.rb make test`. You can also specify a `zsh` binary to use by setting the `TEST_ZSH_BIN` environment variable (ex: `TEST_ZSH_BIN=/bin/zsh make test`).
141
142 A docker image for testing is available [on docker hub](https://hub.docker.com/r/ericfreese/zsh-autosuggestions-test). It comes with ruby, the bundler dependencies, and all supported versions of zsh installed.
143
144 Pull the docker image with:
145
146 ```sh
147 docker pull ericfreese/zsh-autosuggestions-test
148 ```
149
150 To run the tests for a specific version of zsh (where `<version>` below is substituted with the contents of a line from the [`ZSH_VERSIONS`](ZSH_VERSIONS) file):
151
152 ```sh
153 docker run -it -e TEST_ZSH_BIN=zsh-<version> -v $PWD:/zsh-autosuggestions zsh-autosuggestions-test make test
154 ```
155
156
157 ## License
158
159 This project is licensed under [MIT license](http://opensource.org/licenses/MIT).
160 For the full text of the license, see the [LICENSE](LICENSE) file.