- 开发工具
- CLI
- 配置管理
【免费下载链接】chezmoi
Manage your dotfiles across multiple diverse machines, securely.
导读
completion是 chezmoi 提供的一个内部命令，用于按需生成指定 shell（bash、fish、powershell、zsh）的补全脚本，配合--output参数即可一次性把补全写入 shell 的配置目录。本文以 completion 命令参考文档 为骨架，结合 completioncmd.go 源码、completion.txtar 测试 与 completion_unix.txtar 测试，完整讲解命令用法、各 shell 的安装方式、completion.custom自定义补全配置、completion模板函数，以及仓库内置补全脚本与打包分发的关系，读完即可在自己的多台机器上为 chezmoi 配好命令行补全。
命令概览与基本用法
命令的完整用法为：
chezmoi completion shell其中shell必须是bash、fish、powershell、zsh四者之一。命令会生成对应 shell 的补全代码并输出到标准输出（stdout），不会直接写入任何文件，因此你可以自由选择把它重定向到 shell 补全目录，或配合--output参数直接指定目标文件。
参考文档给出的两个示例：
# 生成 bash 补全代码，直接打印到终端 chezmoi completion bash # 生成 fish 补全代码，并写入 fish 的 completions 目录 chezmoi completion fish --output=~/.config/fish/completions/chezmoi.fish第二个示例利用的是 chezmoi 全局参数--output：它把命令输出写入指定路径，因此这条命令一次调用即可完成补全脚本的落地，是日常安装最常用的形态。
源码层面对参数与行为的约束
从 completioncmd.go 可以确认命令的严格定义：
Use: "completion shell"，即必须且只能带一个位置参数；ValidArgs限定为bash、fish、powershell、zsh，配合 cobra 的Args: cobra.ExactArgs(1)在参数数量或取值不合法时报错；- 命令被归入
groupIDInternal内部命令分组； - 标注了
doesNotRequireValidConfig（不要求存在合法配置即可运行）与persistentStateModeNone（不读写持久化状态），这意味着即使你还没有初始化配置文件，也可以先为 chezmoi 生成补全。
实际的补全代码生成逻辑在completion()函数中（completioncmd.go），它针对不同 shell 调用 cobra 的不同生成器：
| shell | 底层生成器 | 输出特征 |
|---|---|---|
| bash | GenBashCompletionV2（含描述） | 以# bash completion V2 for chezmoi开头 |
| fish | GenFishCompletion（含描述） | 以# fish completion for chezmoi开头 |
| powershell | GenPowerShellCompletionWithDesc | 包含Register-ArgumentCompleter注册逻辑 |
| zsh | GenZshCompletion | 以#compdef chezmoi开头 |
传入未知 shell 时返回%s: unsupported shell错误。生成结果最终通过c.writeOutputString(completion, 0o666)输出，即默认以0666权限位写出（实际受 umask 影响），并受--output参数控制落盘位置。
这些输出特征正是仓库测试的断言依据：completion.txtar 分别执行四个 shell 的生成命令，并用stdout断言各自的标记行，例如 zsh 输出必须包含#compdef chezmoi，powershell 输出必须包含Register-ArgumentCompleter。
各 Shell 的补全安装方式
chezmoi 为四种 shell 均内置补全，若你通过包管理器安装 chezmoi，补全脚本通常已随包安装完毕（见 打包指南 中"请将completions目录中的补全脚本装入 shell 对应目录"的说明）。若需要手动安装，可按以下方式操作。
bash
将生成的 bash 补全脚本放入 bash-completion 的加载路径即可：
chezmoi completion bash | sudo tee /etc/bash_completion.d/chezmoi > /dev/null或写入用户级目录（配合 bash-completion 的自动加载）：
chezmoi completion bash --output ~/.local/share/bash-completion/completions/chezmoifish
fish 会自动加载~/.config/fish/completions/下以*.fish命名的补全文件，因此参考文档中的示例即为 fish 的标准安装方式：
chezmoi completion fish --output=~/.config/fish/completions/chezmoi.fishzsh
zsh 的补全目录约定为fpath中的目录，通常使用用户级目录：
chezmoi completion zsh --output=${fpath[1]}/_chezmoi更稳妥的做法是安装到~/.oh-my-zsh/completions/（若使用 oh-my-zsh）或~/.zsh/completions/并把该目录加入fpath，确保autoload -Uz compinit && compinit在补全脚本加载之前执行。
powershell
官方 FAQ（usage.md）特别指出：PowerShell 的补全需要手动把脚本加入 profile，因为包管理器一般不会自动处理。做法是：
chezmoi completion powershell | Out-String | Invoke-Expression要持久生效，先把补全内容写入 profile 再重开终端：
chezmoi completion powershell --output $PROFILE写入后可在 PowerShell 中键入chezmoi ap后按 Tab，验证是否补全出apply。
让补全结果更智能：completion.custom 配置
默认生成的补全是 cobra 基于命令与参数定义的标准补全，可以补全子命令、参数名以及--flag的取值。而 chezmoi 还提供了一类"自定义补全"能力：让补全程序根据当前源状态（source state）动态补全目标文件路径、chattr属性等 chezmoi 特有内容。
在配置文件中开启（variables.md.yaml）：
[completion] custom = true配置键为completion.custom（布尔类型，对应源码中completionCmdConfig.Custom bool字段，支持 JSON / mapstructure / YAML 三种配置映射，见 completioncmd.go）。
开启后，config.go 的 targetValidArgs 函数 会接管目标路径类参数的补全：它遍历源状态中的全部条目，生成目标路径作为候选，目录条目会在末尾追加/，并按用户当前输入的前缀进行过滤；如果toComplete是相对路径，还会去掉工作目录前缀，使补全结果与用户的输入风格保持一致。若未开启custom，则直接返回cobra.ShellCompDirectiveDefault，交由 shell 做默认补全。
completion_unix.txtar 完整验证了这类自定义补全（其测试配置中即设置了[completion] custom = true）：
chezmoi __complete apply --include=d只补全出以d开头的取值dirs；chezmoi __complete chattr p补全出属性名private；chezmoi __complete cat $HOME/.f能补全出$HOME/.file等实际托管的目标文件；chezmoi __complete cat .f（在$HOME目录下执行）能补全出相对路径.file；chezmoi __complete cat private $HOME对目录补全出$HOME/.dir/（带尾部斜杠）。
与之配套，completion.txtar 验证了大量标志取值的自动补全，例如--color的t/true、--config-format的json/toml/yaml、--mode的file/symlink、apply --exclude/--include的 entry type 集合（dirs、files、scripts、symlinks、templates、encrypted、externals及其no前缀变体）、add --secrets的error/ignore/warning、archive/data/dump/dump-config --format的输出格式、managed/status/unmanaged --path-style的路径风格等。这些补全由 cobra 的ValidArgsFunction与__complete隐藏命令驱动，测试通过exec chezmoi __complete ...直接与补全引擎交互，校验每个标志的候选值与退出码。
在模板与 dotfiles 中使用 completion 模板函数
除了命令行，chezmoi 还提供了同名模板函数completion，它返回指定 shell 的补全代码，用法与命令一一对应（函数参考文档）：
{{ completion "zsh" }}shell参数同样只能是bash、fish、powershell、zsh之一。FAQ（usage.md）指出：补全脚本既可以一次性手动生成，也可以作为 dotfiles 仓库的一部分随 chezmoi 管理。典型做法是在源目录中维护一个模板文件，例如：
# 由 chezmoi 模板生成，不要手动编辑 {{ completion "zsh" }}这样，chezmoi apply后 zsh 补全脚本会以托管文件的形式出现在目标机器上；换新机器时执行chezmoi init与chezmoi apply即可自动恢复补全能力，无需再手动执行生成命令。这正是命令形式与模板函数形式互补的价值：命令适合一次性手动安装，模板函数适合把补全纳入 dotfiles 的声明式管理。
仓库内已生成的补全脚本与打包分发
值得说明的是，仓库根目录下已包含四个预生成的补全脚本，与completion命令的输出等价：
- completions/chezmoi-completion.bash
- completions/chezmoi.fish
- completions/chezmoi.ps1
- completions/chezmoi.zsh
这些文件主要用于发行与打包场景：打包指南 明确要求打包者将completions目录中的脚本安装到各 shell 的对应目录（如/usr/share/bash-completion/completions/、/usr/share/fish/vendor_completions.d/等）。如果你使用系统包管理器安装 chezmoi，补全很可能已随之就位，无需手动执行completion命令。需要验证时，可对照上文表格中的输出特征（如 bash 的# bash completion V2 for chezmoi、zsh 的#compdef chezmoi）检查已安装脚本的内容是否与仓库版本一致。
小结
chezmoi completion shell是一个轻量但完整的补全生成入口：支持 bash、fish、powershell、zsh 四种 shell，输出直达 stdout、可配合--output一键落盘；通过配置completion.custom = true可获得基于源状态的目标路径与属性补全；模板函数{{ completion "shell" }}则让补全脚本可以像其他 dotfiles 一样被声明式地管理。无论是手动一次性安装，还是把补全纳入跨机器同步的 dotfiles 仓库，这个命令都能覆盖。若你想进一步了解补全在仓库中的完整测试覆盖，可阅读 completion.txtar 与 completion_unix.txtar。
- 开发工具
- CLI
- 配置管理
【免费下载链接】chezmoi
Manage your dotfiles across multiple diverse machines, securely.
相关推荐
mise completion 命令完全指南：为 zsh / bash / fish / PowerShell 生成与安装 Shell 补全
mise completion 命令完全指南：为 zsh / bash / fish / PowerShell 生成与安装 Shell 补全 mise comp
开发工具CLIminikube completion 命令完全指南：为 bash、zsh、fish 与 PowerShell 生成 Shell 自动补全
minikube completion 命令完全指南：为 bash、zsh、fish 与 PowerShell 生成 Shell 自动补全 导读 minikub
云原生容器编排CLI开发工具rclone completion 命令详解：为 bash/zsh/fish/PowerShell 一键生成自动补全脚本
rclone completion 命令详解：为 bash/zsh/fish/PowerShell 一键生成自动补全脚本 rclone completion 是
CLI数据同步对象存储
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
