增加 Zsh Tab 补全 by swim233 · Pull Request #395 · RubyMetric/chsrc

swim233 · 2026-09-08T12:27:29Z

新功能描述

目前 chsrc 仅提供 Bash 补全，Zsh 用户无法直接获得命令、选项、菜品和镜像参数的 Tab 补全。

本 PR 增加原生 Zsh 补全，并接入安装、Debian 打包、CI 与回归测试流程。

关联 issue：N/A

方案

新增原生 _chsrc 补全函数，不依赖 bashcompinit。
根据 chsrc 的命令行结构实现状态化补全：
- 命令及全局选项
- -scope=value 与 -scope value
- list 的目标类型
- measure、get、set、reset 的菜品参数
- set 的镜像选择
补全菜单只展示规范名称，将同义命令集中写入说明，避免 measure、mea、m、cesu 等别名重复占据多行；用户手动输入别名后仍能继续补全。
从 src/recipe/menu.c 与 recipe 声明校验菜品别名，避免补全内容与实际注册菜单不同步。
将补全文件接入源码安装和 Debian 包安装流程。

实现

Zsh 补全

新增 tool/completion/_chsrc，支持：

help、issue、list、measure、get、set、reset、version
-dry、-ipv6、-en、-no-color、-scope=
default、project、user、system 作用域
已注册的语言、操作系统和软件类菜品
first、upstream 镜像选择
现有命令和选项别名

补全状态会限制参数位置，例如菜品之后不再建议选项，set 已填写镜像后不再建议第二个镜像。

安装与打包

make install 将 _chsrc 安装到 /usr/share/zsh/site-functions
Debian 包将其安装到 /usr/share/zsh/vendor-completions
Debian 安装测试增加 Bash、Zsh 补全文件检查
修复干净源码树直接执行 make install 时缺少 chsrc-release 构建规则的问题

测试与 CI

新增三类测试：

校验补全中的菜品别名与注册菜单一致
使用模拟补全函数测试状态机与别名分派
使用隔离的 Zsh/ZLE 会话测试真实 Tab 插入行为

CI 会安装 Zsh，并通过 REQUIRE_ZSH=1 确保相关测试不会被跳过。

测试结果：

$ make test-zsh-completion REQUIRE_ZSH=1
Zsh completion dish aliases match the registered menus.
Zsh completion state-machine tests passed.
Real Zsh completion insertion tests passed.

目前仅在arch中手动完成测试

github-actions · 2026-09-08T12:27:40Z

Hi @swim233,

❤️ 感谢你的贡献！你的 PR 当前基于 main 分支，请修改使用 dev 分支

swim233 · 2026-09-08T12:30:49Z

已切换pr分支

ccmywish

需要在 tool/completion/ 目录中增加一个 README，简要介绍 _describe compadd compset 的作用

ccmywish · 2026-09-09T01:32:13Z

+# `install` depends on the release binary by filename.  Build it on demand
+# when installing from a clean source tree; packaging flows that already ran
+# build-in-release-mode can reuse the existing artifact.
+$(ReleaseMode-Target-Name):


应该可以改成：

$(ReleaseMode-Target-Name): build-in-release-mode

另外，注释需要改成中文

ccmywish · 2026-09-09T01:33:52Z

 clean-deb:
 	@$(MAKE) -C pkg/deb deb-clean

+ZSH_COMPLETION_DIR ?= /usr/share/zsh/site-functions


CI的时候用的是另一个目录覆盖了这个变量，可以注释一下二者的区别

ccmywish · 2026-09-09T02:00:23Z

+# -----------------------------------------------------------------------------
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Check that the native Zsh completion contains every alias of every dish
+# registered in src/recipe/menu.c.  Internal sources-only dishes are not menu
+# entries and therefore must not be offered to users.
+# -----------------------------------------------------------------------------


文件标头要像 cli.pl 一样，有维护者信息，以及中文注释

ccmywish · 2026-09-09T02:06:58Z

建议改名为 verify-sync-state-of-zsh-completion

ccmywish · 2026-09-09T02:37:11Z

+
+assert_has() {
+  local expected=$1
+  if (( ! ${captured[(Ie)${expected}]} )); then


这里的 Ie 建议给一下注释是什么意思

ccmywish · 2026-09-09T03:01:39Z

+# -----------------------------------------------------------------------------
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Lightweight tests for the completion state machine.  Completion widgets are
+# mocked so the test does not touch the user's Zsh setup.
+# -----------------------------------------------------------------------------


同其他文件，需要给一个文件标头，写明中文注释。

这个文件应该是自己用函数覆盖了Zsh 的行为，从而模拟 Zsh 的补全。建议更换文件名，清晰表达此含义。

ccmywish · 2026-09-09T04:37:49Z

同理，文件标头要和其他文件一样规范，所有注释需中文

ccmywish · 2026-09-09T06:16:16Z

同理，需要增加文件头，所有注释需要为中文

ccmywish · 2026-09-09T06:34:05Z

👍👍👍 @swim233

感谢你花时间为 chsrc 添加 Zsh 的补全！❤️

你能够持续维护相关的文件吗？因为代码一旦进入 chsrc，我们就势必有人要维护它，比如这个 PR 里的 Perl 脚本，是高度和代码相关的，相关文件一改动，大概率会测试出错。这些代码我已经全部审查完毕，已经基本理解，但是我希望你能补充一些简单的文档能够快速帮助不懂的人去抓住要点。正如 #204 所提到的，我们希望贡献者们能够从中学习到新知识。

另外，可以参照文档第一次贡献者注册你的贡献者信息，以及在相关文件的 header 处添加你自己为 Authors 或 Contributors！

swim233 · 2026-09-09T07:36:22Z

👍👍👍 @swim233

感谢你花时间为 chsrc 添加 Zsh 的补全！❤️

你能够持续维护相关的文件吗？因为代码一旦进入 chsrc，我们就势必有人要维护它，比如这个 PR 里的 Perl 脚本，是高度和代码相关的，相关文件一改动，大概率会测试出错。这些代码我已经全部审查完毕，已经基本理解，但是我希望你能补充一些简单的文档能够快速帮助不懂的人去抓住要点。正如 #204 所提到的，我们希望贡献者们能够从中学习到新知识。

另外，可以参照文档第一次贡献者注册你的贡献者信息，以及在相关文件的 header 处添加你自己为 Authors 或 Contributors！

我会尽量坚持维护，已经补充署名文档稍后补充

swim233 added 2 commits September 8, 2026 20:14

增加 Zsh Tab 补全

35ac91e

修复从干净源码树执行 make install 失败的问题

77ec269

swim233 changed the base branch from main to dev September 8, 2026 12:30

ccmywish mentioned this pull request Sep 9, 2026

【欢迎参与贡献】Shell auto-completion 终端命令自动补全 #204

Open

2 tasks

ccmywish requested changes Sep 9, 2026

View reviewed changes

ccmywish assigned swim233 Sep 9, 2026

ccmywish added 改善加强改善加强 Linux Linux相关挑战挑战 Challenge labels Sep 9, 2026

ccmywish added this to the v0.2.8 milestone Sep 9, 2026

ccmywish requested a review from Gchuchu September 9, 2026 06:20

按照审查意见完善 Zsh 补全

6b2ff7a

swim233 requested a review from ccmywish September 9, 2026 06:32

swim233 added 3 commits September 9, 2026 15:00

添加贡献者信息

f4802c0

完善贡献者署名

2b2f963

撤销错误的署名

e081399

swim233 force-pushed the feat/zsh-completion branch from 2a167e4 to e081399 Compare September 9, 2026 07:34

Uh oh!

Uh oh!

Conversation

swim233 commented Sep 8, 2026

新功能描述

方案

实现

Zsh 补全

安装与打包

测试与 CI

Uh oh!

github-actions Bot commented Sep 8, 2026

Uh oh!

swim233 commented Sep 8, 2026

Uh oh!

ccmywish left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccmywish commented Sep 9, 2026

Uh oh!

swim233 commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants