zsh-自动建议

像 Fish 一样快速/不显眼的 zsh 自动建议功能。

它会根据历史记录和补全来建议你输入的命令。

要求: Zsh 4.3.11 或更高版本

<a href="https://asciinema.org/a/37390" target="_blank"><img src="https://yellow-cdn.veclightyear.com/835a84d5/4a0bf2c2-6c7a-4030-9648-d31b8330fd43.png" width="400" /></a>

安装

请参阅 INSTALL.md。

使用方法

当你输入命令时,你会在光标后看到以暗灰色显示的补全建议。你可以通过设置 ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE 变量来更改这个颜色。详见配置。

如果你在缓冲区末尾按下 <kbd>→</kbd> 键（forward-char 小部件）或 <kbd>End</kbd>（end-of-line 小部件），它会接受建议，用建议内容替换命令行缓冲区的内容。

如果你调用 forward-word 小部件，它会部分接受建议，直到光标移动到的位置。

配置

你可能想要覆盖默认的全局配置变量。这些变量的默认值可以在这里找到。

注意: 如果你使用的是 Oh My Zsh，你可以将此配置放在 $ZSH_CUSTOM 目录下的文件中。参见他们关于覆盖内部配置的评论。

建议高亮样式

设置 ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE 来配置建议显示的样式。默认值是 fg=8，这将设置前景色为 256色调色板 中的颜色 8。如果你的终端只支持 8 种颜色，你需要使用 0 到 7 之间的数字。

也可以设置背景色，并且可以将建议样式设为粗体、下划线或突出显示。例如，这会将建议显示为粗体、带下划线的粉色文字，背景为青色：

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#ff00ff,bg=cyan,bold,underline"

更多信息，请阅读 zsh 手册的字符高亮部分：man zshzle 或在线版。

注意: 一些 iTerm2 用户报告无法看到建议。如果你遇到这个问题，很可能是由于颜色设置不正确造成的。要纠正这个问题，请进入 iTerm2 的设置，导航到 profile > colors，确保 Basic Colors > Background 和 ANSI Colors > Bright Black 的颜色不同。

建议策略

ZSH_AUTOSUGGEST_STRATEGY 是一个指定如何生成建议的数组。数组中的策略会依次尝试，直到找到一个建议。目前有三种内置策略可供选择：

• history：从历史记录中选择最近的匹配项。
• completion：根据 tab 补全会建议的内容选择一个建议。（需要 zpty 模块，该模块自 4.0.1 版本起包含在 zsh 中）
• match_prev_cmd：类似于 history，但选择最近的匹配项，其前一个历史项与最近执行的命令匹配（更多信息）。请注意，此策略不会与不保留历史顺序的 ZSH 选项（如 HIST_IGNORE_ALL_DUPS 或 HIST_EXPIRE_DUPS_FIRST）按预期工作。

例如，设置 ZSH_AUTOSUGGEST_STRATEGY=(history completion) 将首先尝试从你的历史记录中找到建议，但如果找不到匹配项，则会从补全引擎中找到建议。

小部件映射

这个插件通过在调用某些 zle 小部件 时触发自定义行为来工作。你可以在这些数组中添加和删除小部件来改变这个插件的行为：

• ZSH_AUTOSUGGEST_CLEAR_WIDGETS：此数组中的小部件在调用时会清除建议。
• ZSH_AUTOSUGGEST_ACCEPT_WIDGETS：此数组中的小部件在调用时会接受建议。
• ZSH_AUTOSUGGEST_EXECUTE_WIDGETS：此数组中的小部件在调用时会执行建议。
• ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS：此数组中的小部件在调用时会部分接受建议。
• ZSH_AUTOSUGGEST_IGNORE_WIDGETS：此数组中的小部件在调用时不会触发任何自定义行为。

修改缓冲区且未在任何这些数组中找到的小部件将在调用后获取新的建议。

注意: 一个小部件不应该同时属于多个上述数组。

为大缓冲区禁用建议

将 ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE 设置为一个整数值，以禁用大缓冲区的自动建议。默认值为未设置，这意味着会对任何大小的缓冲区尝试自动建议。推荐值为 20。 在终端中粘贴大量文本时，这可能很有用，以避免对过长的字符串触发自动建议。

异步模式

在 zsh 5.0.8 及更高版本中，默认情况下异步获取建议。要禁用异步建议并改为同步获取，请在加载插件后 unset ZSH_AUTOSUGGEST_USE_ASYNC。

另外，如果你使用的 zsh 版本低于 5.0.8 并希望启用异步模式，请在加载插件后设置 ZSH_AUTOSUGGEST_USE_ASYNC 变量（可以设置为任何值）。请注意，在低于 5.0.8 的 zsh 版本中存在一个 bug，即在异步获取建议后，<kbd>ctrl</kbd> + <kbd>c</kbd> 无法立即重置提示符。

禁用自动小部件重新绑定

设置 ZSH_AUTOSUGGEST_MANUAL_REBIND（可以设置为任何值）以禁用每次 precmd 时的自动小部件重新绑定。这可以大大提升性能，但如果任何小部件列表发生变化，或者你或其他插件包装了任何自动建议小部件，你需要自己处理重新绑定。要重新绑定小部件，运行 _zsh_autosuggest_bind_widgets。

忽略匹配特定模式的历史建议

将 ZSH_AUTOSUGGEST_HISTORY_IGNORE 设置为一个通配符模式，以防止为匹配该模式的历史条目提供建议。例如，将其设置为 "cd *" 可以避免从历史记录中建议任何 cd 命令。或者设置为 "?(#c50,)" 以避免建议任何长度为50个字符或更长的内容。

**注意：**这只影响 history 和 match_prev_cmd 建议策略。

在某些情况下跳过补全建议

将 ZSH_AUTOSUGGEST_COMPLETION_IGNORE 设置为一个通配符模式，以在缓冲区匹配该模式时防止提供补全建议。例如，将其设置为 "git *" 可以禁用 git 子命令的补全建议。

**注意：**这只影响 completion 建议策略。

快捷键绑定

此插件提供了几个可以用 bindkey 使用的小部件：

1. autosuggest-accept：接受当前建议。
2. autosuggest-execute：接受并执行当前建议。
3. autosuggest-clear：清除当前建议。
4. autosuggest-fetch：获取建议（即使建议被禁用也有效）。
5. autosuggest-disable：禁用建议。
6. autosuggest-enable：重新启用建议。
7. autosuggest-toggle：在启用/禁用建议之间切换。

例如，这将把 <kbd>ctrl</kbd> + <kbd>空格</kbd> 绑定为接受当前建议。

bindkey '^ ' autosuggest-accept

故障排除

如果你遇到问题，请先在 GitHub 上的问题列表 中搜索，看是否有人已经报告过类似问题。

报告问题

在报告问题之前，请尝试暂时禁用可能与此插件冲突的配置部分和其他插件，以隔离问题。

报告问题时，请包括：

• 能够重现问题的最小、最简单的 .zshrc 配置。参见此评论了解一个好的示例。
• 你使用的 zsh 版本（zsh --version）
• 你运行的操作系统

卸载

1. 从 ~/.zshrc 中删除引用此插件的代码。

2. 从你的硬盘中删除 git 仓库

   rm -rf ~/.zsh/zsh-autosuggestions # 或者你安装的位置

开发

构建过程

编辑 src/ 中的源文件。运行 make 从这些源文件构建 zsh-autosuggestions.zsh。

拉取请求

欢迎拉取请求！如果你发送拉取请求，请：

• 请求合并到 develop 分支（不是 master）
• 匹配现有的编码约定。
• 包含有用的注释，以降低新加入项目的人的入门门槛。
• 尽可能为你的代码编写测试。

测试

测试使用 rspec 框架用 ruby 编写。它们使用 tmux 来驱动伪终端，发送模拟的按键并对终端内容进行断言。

测试文件位于 spec/。要运行测试，运行 make test。要运行特定测试，运行 TESTS=spec/some_spec.rb make test。你也可以通过设置 TEST_ZSH_BIN 环境变量来指定要使用的 zsh 二进制文件（例如：TEST_ZSH_BIN=/bin/zsh make test）。

用于测试的 docker 镜像可在 docker hub 上获取。它附带了 ruby、bundler 依赖项以及所有支持的 zsh 版本。

使用以下命令拉取 docker 镜像：

docker pull ericfreese/zsh-autosuggestions-test

要为特定版本的 zsh 运行测试（其中下面的 <version> 替换为 ZSH_VERSIONS 文件中一行的内容）：

docker run -it -e TEST_ZSH_BIN=zsh-<version> -v $PWD:/zsh-autosuggestions zsh-autosuggestions-test make test

许可证

本项目采用 MIT 许可证。 有关许可证的完整文本，请参阅 LICENSE 文件。