better-chezmoi

更好地使用 chezmoi

通过“检查、预览、应用、验证”的循环使用 chezmoi。区分源状态、目标状态、本地配置、远程 Git 和外部影响，避免便捷命令悄然扩大用户请求的范围。

操作约定

• 当前参考依据：chezmoi 官方文档和版本 v2.71.0，核对日期为 2026-07-15。
• 本地实测的命令范围：macOS 上的 chezmoi v2.70.2，包括完全隔离的源、目标、配置、缓存和持久状态测试环境。
• 版本规则：使用依赖版本的标志前，先运行 chezmoi --version 并查看 chezmoi <command> --help。已安装的二进制文件决定可执行语法；抓取的文档提供当前概念、示例和新发布的行为。
• 权限规则：用户明确要求添加、编辑、应用、更新、合并或移除某个指定目标，即授权执行该范围内的操作。但这并不授权应用所有目标、启用自动推送、改写远程历史记录、暴露机密，或销毁源和目标状态。
• 可移植性：为 Windows 用户提供 PowerShell 原生写法。不要将 POSIX shell 数组、命令替换或 mktemp 作为可移植的 Windows 语法。

为任务选择路径

用户目标	阅读	用途
检查、添加、编辑、捕获、预览、应用或同步点文件	references/daily-workflows.md	选择范围最小的日常循环并进行验证
初始化仓库、引导新机器或分离特定机器的状态	references/setup-and-machines.md	选择 init、源/配置放置位置和跨机器边界
构建或调试模板、数据、机密、加密文件或脚本	references/templates-secrets-and-scripts.md	测试渲染，并避免将敏感或会产生影响的数据纳入源历史记录
诊断漂移、冲突、锁、合并或破坏性清理	references/recovery-and-safety.md	确认状态归属并选择可逆的恢复路径
需要精确命令、标志、输出或退出语义	references/commands.md	核实当前命令形式及影响类别
需要最新官方详情，或想刷新/搜索打包的语料	references/official-documentation.md	运行确定性抓取器并检查来源信息

仅加载任务所需的行。若只需解释简单的 status，不要加载设置、模板或恢复材料。

先对影响分类

影响类别	示例	默认处理方式
读取/检查	--version、help、source-path、target-path、status、diff、verify、doctor --no-network	有用时运行；仍需考虑模板求值、钩子和缓存的外部内容
写入源	add、edit、re-add、forget、init、Git pull	限定到指定目标；在支持的情况下先预览；验证源差异
写入目标	apply、edit --apply、默认的 update、init --apply	除非用户明确要求立即应用，否则先预览
本地配置/状态	edit-config、init 配置模板、脚本状态、purge	更改前检查路径和恢复方式
远程/网络	Git fetch/pull、外部内容、密码管理器、自动提交/推送	限制读取范围；远程写入或访问机密需明确授权
破坏性操作	destroy、广泛的移除规则、purge	要求明确范围、独立备份、可用时先预览，并检查操作后的状态

--dry-run 保证 chezmoi 不会修改目标目录。它并非通用的无副作用模式：init 仍可能创建源 Git 状态；钩子即使在 dry-run 模式下也会运行；模板或外部内容可能调用依赖网络的组件。请准确说明这项保证的有限范围。

核心工作流

1. 检查当前上下文

运行最精简且有用的一组命令：

chezmoi --version
chezmoi source-path
chezmoi target-path
chezmoi status --exclude=scripts

如果需要检查设置或依赖项的健康状况，请运行 chezmoi doctor --no-network。在使用随附文档中的标志之前，先查看相关命令的本地帮助。

**满足条件：**已知已安装的版本、源和目标根目录、请求的目标范围，以及可能产生的影响类型。

2. 检查差异

对于常见的目标偏差或源文件编辑：

chezmoi diff --exclude=scripts --no-pager

对于目标写入预览：

chezmoi apply --dry-run --verbose --exclude=scripts

如果非交互式预览会因冲突提示而停止，只有在确认本地帮助和 dry-run 标志后，才可以将 --force 与 --dry-run 搭配使用。实际应用时不要带上 --force。

**满足条件：**可以看到拟议的源或目标更改，已考虑脚本和钩子的影响，并且已在修改前解决冲突或意外目标。

3. 仅执行已授权的操作

使用范围最窄的目标列表。如果请求范围较窄，优先指定单个文件或子树，而不是不指定范围地应用更改。对于 chezmoi v2.71.0 或更高版本，仅在本地帮助确认支持 --error-on-conflict 后，才在非交互式自动化中使用它；对于更早的版本，应停止操作，而不是用 --force 代替冲突处理。

只有在明确授权远程操作及其范围时，才启用 git.autoPush 或执行远程推送。不要将明文密钥留在源历史记录中；请改用用户支持的加密或密钥管理器集成。

**满足条件：**仅指定的源、目标、配置或远程范围发生了更改，且命令返回了文档所述的成功结果。

4. 验证后置条件

使用以下一项或多项：

chezmoi status --exclude=scripts
chezmoi diff --exclude=scripts --no-pager
chezmoi verify --exclude=scripts

正确解读结果：diff 即使显示差异也可能返回 0；status 通过两列传达偏差情况；所选目标匹配时 verify 返回 0，不匹配时返回 1。

报告检查的版本、源和目标范围、运行的命令、观察到的影响，以及任何剩余偏差或未执行的操作。

**满足条件：**请求的后置条件可以独立验证，且任何非零结果均已归类为预期偏差、冲突、操作失败或不支持的语法。

官方文档语料库

软件包包含所选官方页面的可搜索快照，以及一个使用 Python 标准库的工具：

python3 scripts/official_docs.py search "error-on-conflict"
python3 scripts/official_docs.py list
python3 scripts/official_docs.py refresh

refresh 会获取并比较内容，但不会替换随附的快照。仅当获准更新该语料库时，才在规范检出目录中使用 --write；它会替换本地文件，不会替换远程仓库。刷新或更改源列表前，请阅读 references/official-documentation.md；遵循其中的说明，以保留来源信息、支持安全回滚的分阶段替换方式，以及离线验证流程。

如果某条指令失败，或快照内容与已安装的帮助信息冲突，请使用相关且版本匹配的官方依据选择安全替代方案。如果无法获取来源信息，请保留不确定性。提出规范技能更正时，应附上失败的命令、版本或来源，以及隔离的复现步骤；不要擅自重写已安装的副本，也不要发布提议。

注意事项

1. update 不是预览命令。它通常会拉取源仓库并应用目标更改。如果用户希望将这些操作分开，请使用 update --apply=false，或采用经过审查的 pull → diff → apply 顺序。
2. re-add 不会更新模板化的源文件。请改用 edit、merge 或有意进行的模板更改。
3. --source-path 下的相对参数会相对于当前工作目录解析。请使用绝对源路径，或从源目录运行。
4. 默认路径样式下，managed --format=json 不一定会输出结构化 JSON。请核实确切的输出格式；v2.70.2 要获得文档所述的键值结构，必须指定 --path-style=all。
5. 多个 chezmoi 进程可能会争用持久状态锁。不要从 chezmoi 的 run_ 脚本中递归调用 chezmoi。

完成门槛

只有在检查过本地命令界面、所有影响均未超出用户范围、秘密信息和远程写入均受到限制、已验证请求的状态，并且如实说明版本或网络限制而未将其伪装成成功后，才算完成。