Mercurial > dotfiles

annotate .zfun/zsh-autosuggestions/README.md @ 499:7392a48b8dcb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
emacs: customize strikes again
author Augie Fackler <raf@durin42.com>
date Sat, 03 Oct 2020 11:15:36 -0400
parents e1ce8897030d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
467
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
1 # zsh-autosuggestions
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
2
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
3 _[Fish](http://fishshell.com/)-like fast/unobtrusive autosuggestions for zsh._
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
4
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
5 It suggests commands as you type, based on command history.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
6
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
7 Requirements: Zsh v4.3.11 or later
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
8
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
9 [![CircleCI](https://circleci.com/gh/zsh-users/zsh-autosuggestions.svg?style=svg)](https://circleci.com/gh/zsh-users/zsh-autosuggestions)
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
10
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
11 <a href="https://asciinema.org/a/37390" target="_blank"><img src="https://asciinema.org/a/37390.png" width="400" /></a>
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
12
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
13
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
14 ## Installation
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
15
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
16 See [INSTALL.md](INSTALL.md).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
17
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
18
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
19 ## Usage
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
20
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
22
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
24
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
25 If you invoke the `forward-word` widget, it will partially accept the suggestion up to the point that the cursor moves to.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
26
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
27
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
28 ## Configuration
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
29
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
30 You may want to override the default global config variables. Default values of these variables can be found [here](src/config.zsh).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
31
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
33
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
34
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
35 ### Suggestion Highlight Style
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
36
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
37 Set `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` to configure the style that the suggestion is shown with. The default is `fg=8`.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
38
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
39
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
40 ### Suggestion Strategy
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
41
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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:
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
43
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
44 - `history`: Chooses the most recent match from history.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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`.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
46
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
47
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
48 ### Widget Mapping
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
49
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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:
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
51
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
52 - `ZSH_AUTOSUGGEST_CLEAR_WIDGETS`: Widgets in this array will clear the suggestion when invoked.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
53 - `ZSH_AUTOSUGGEST_ACCEPT_WIDGETS`: Widgets in this array will accept the suggestion when invoked.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
54 - `ZSH_AUTOSUGGEST_EXECUTE_WIDGETS`: Widgets in this array will execute the suggestion when invoked.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
55 - `ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS`: Widgets in this array will partially accept the suggestion when invoked.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
56 - `ZSH_AUTOSUGGEST_IGNORE_WIDGETS`: Widgets in this array will not trigger any custom behavior.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
57
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
58 Widgets that modify the buffer and are not found in any of these arrays will fetch a new suggestion after they are invoked.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
59
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
60 **Note:** A widget shouldn't belong to more than one of the above arrays.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
61
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
62
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
63 ### Disabling suggestion for large buffers
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
64
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
66 This can be useful when pasting large amount of text in the terminal, to avoid triggering autosuggestion for too long strings.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
67
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
68 ### Enable Asynchronous Mode
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
69
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
71
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
72
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
73 ### Key Bindings
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
74
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
75 This plugin provides a few widgets that you can use with `bindkey`:
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
76
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
77 1. `autosuggest-accept`: Accepts the current suggestion.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
78 2. `autosuggest-execute`: Accepts and executes the current suggestion.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
79 3. `autosuggest-clear`: Clears the current suggestion.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
80 4. `autosuggest-fetch`: Fetches a suggestion (works even when suggestions are disabled).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
81 5. `autosuggest-disable`: Disables suggestions.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
82 6. `autosuggest-enable`: Re-enables suggestions.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
83 7. `autosuggest-toggle`: Toggles between enabled/disabled suggestions.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
84
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
85 For example, this would bind <kbd>ctrl</kbd> + <kbd>space</kbd> to accept the current suggestion.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
86
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
87 ```sh
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
88 bindkey '^ ' autosuggest-accept
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
89 ```
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
90
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
91
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
92 ## Troubleshooting
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
93
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
95
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
96
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
97 ### Reporting an Issue
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
98
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
100
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
101 When reporting an issue, please include:
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
102
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
104 - The version of zsh you're using (`zsh --version`)
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
105 - Which operating system you're running
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
106
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
107
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
108 ## Uninstallation
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
109
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
110 1. Remove the code referencing this plugin from `~/.zshrc`.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
111
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
112 2. Remove the git repository from your hard drive
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
113
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
114 ```sh
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
115 rm -rf ~/.zsh/zsh-autosuggestions # Or wherever you installed
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
116 ```
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
117
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
118
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
119 ## Development
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
120
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
121 ### Build Process
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
122
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
123 Edit the source files in `src/`. Run `make` to build `zsh-autosuggestions.zsh` from those source files.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
124
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
125
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
126 ### Pull Requests
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
127
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
128 Pull requests are welcome! If you send a pull request, please:
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
129
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
130 - Request to merge into the `develop` branch (*NOT* `master`)
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
131 - Match the existing coding conventions.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
132 - Include helpful comments to keep the barrier-to-entry low for people new to the project.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
133 - Write tests that cover your code as much as possible.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
134
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
135
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
136 ### Testing
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
137
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
139
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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`).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
141
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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.
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
143
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
144 Pull the docker image with:
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
145
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
146 ```sh
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
147 docker pull ericfreese/zsh-autosuggestions-test
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
148 ```
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
149
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
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):
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
151
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
152 ```sh
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
153 docker run -it -e TEST_ZSH_BIN=zsh-<version> -v $PWD:/zsh-autosuggestions zsh-autosuggestions-test make test
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
154 ```
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
155
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
156
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
157 ## License
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
158
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
159 This project is licensed under [MIT license](http://opensource.org/licenses/MIT).
e1ce8897030d zsh: import df6f6f9ff41 of zsh-autosuggestions
Augie Fackler <raf@durin42.com>
parents:
diff changeset
160 For the full text of the license, see the [LICENSE](LICENSE) file.