chezmoi-workflows

Chezmoi 工作流

自我进化的技能：此技能会随着使用不断改进。如果指令有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 将点文件备份到 Git 仓库
• 在多台机器之间同步配置文件
• 跟踪 Shell 配置、编辑器设置或其他点文件的变更
• 使用 chezmoi 管理模板化配置
• 排查源文件与目标文件之间的点文件偏差

架构

组件	位置	用途
源	$(chezmoi source-path)	存放点文件模板的 Git 仓库
目标	~/	主目录（已部署的文件）
远程	GitHub（建议使用私有仓库）	在多台机器之间同步和备份
配置	~/.config/chezmoi/chezmoi.toml	用户偏好和设置

---

1. 检查状态

chezmoi source-path                    # Show source directory
chezmoi git -- remote -v               # Show GitHub remote
chezmoi status                         # Show drift between source and target
chezmoi managed | wc -l                # Count tracked files

---

2. 跟踪文件变更

编辑配置文件后，将其添加到 chezmoi：

chezmoi status                         # 1. Verify file shows as modified
chezmoi diff ~/.zshrc                  # 2. Review changes
chezmoi add ~/.zshrc                   # 3. Add to source (auto-commits if configured)
chezmoi git -- log -1 --oneline        # 4. Verify commit created
chezmoi git -- push                    # 5. Push to remote

---

3. 跟踪新文件

添加先前未跟踪的配置文件：

chezmoi add ~/.config/app/config.toml  # 1. Add file to source
chezmoi managed | grep app             # 2. Verify in managed list
chezmoi git -- push                    # 3. Push to remote

---

4. 从远程同步

从 GitHub 拉取变更并应用到主目录：

chezmoi update                         # 1. Pull + apply (single command)
chezmoi verify                         # 2. Verify all files match source
chezmoi status                         # 3. Confirm no drift

---

5. 推送所有变更

批量将所有已跟踪文件的修改同步到远程：

chezmoi status                         # 1. Review all drift
chezmoi re-add                         # 2. Re-add all managed files (auto-commits)
chezmoi git -- push                    # 3. Push to remote

---

6. 首次设置

安装 chezmoi

brew install chezmoi                   # macOS

初始化（全新开始）

/usr/bin/env bash << 'CONFIG_EOF'
chezmoi init                           # Create empty source
chezmoi add ~/.zshrc ~/.gitconfig      # Add first files
gh repo create dotfiles --private --source="$(chezmoi source-path)" --push
CONFIG_EOF

初始化（克隆现有仓库）

chezmoi init [email protected]:<user>/dotfiles.git
chezmoi apply                          # Deploy to home directory

---

7. 配置源目录

将源目录移至自定义位置（例如，用于多账户 SSH）：

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
mv "$(chezmoi source-path)" ~/path/to/dotfiles
SKILL_SCRIPT_EOF

编辑 ~/.config/chezmoi/chezmoi.toml：

sourceDir = "~/path/to/dotfiles"

验证：

chezmoi source-path                    # Should show new location

---

8. 更改远程仓库

切换到其他 GitHub 账户或仓库：

chezmoi git -- remote -v                                              # View current
chezmoi git -- remote set-url origin [email protected]:<user>/<repo>.git # Change
chezmoi git -- push -u origin main                                    # Push to new remote

---

9. 解决合并冲突

/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status                  # 1. Identify conflicted files
chezmoi git -- diff                    # 2. Review conflicts
# Manually edit files in $(chezmoi source-path)
chezmoi git -- add <resolved-files>    # 3. Stage resolved files
chezmoi git -- commit -m "Resolve merge conflict"
chezmoi apply                          # 4. Apply to home directory
chezmoi git -- push                    # 5. Push resolution
GIT_EOF

---

10. 验证（SLO）

执行重要操作后，验证系统状态：

chezmoi verify                         # Exit 0 = all files match source
chezmoi diff                           # Empty = no drift
chezmoi managed                        # Lists all tracked files
chezmoi git -- log --oneline -3        # Recent commit history

---

11. 忘记（取消跟踪）文件

停止跟踪文件，但不从主目录中删除：

chezmoi managed | grep config.local     # 1. Confirm file is tracked
chezmoi forget --force ~/.config/app/config.local.toml  # 2. Remove from source (--force skips TTY prompt)
chezmoi git -- push                     # 3. Push removal to remote
ls ~/.config/app/config.local.toml      # 4. Verify file still exists in home

适用情况：特定于某台机器的配置、包含不应同步的密钥的文件，以及意外添加的文件。

---

12. 模板管理

使用 Go 模板创建有操作系统／架构条件的配置：

将现有文件转换为模板

chezmoi add --template ~/.config/app/config.toml  # 1. Add as template (creates .tmpl suffix in source)
chezmoi edit ~/.config/app/config.toml             # 2. Edit template in $EDITOR (helix)
chezmoi diff ~/.config/app/config.toml             # 3. Preview what would change
chezmoi apply ~/.config/app/config.toml            # 4. Apply rendered template to home

常见模板模式

# OS-conditional block
{{ if eq .chezmoi.os "darwin" -}}
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" -}}
export HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
{{ end -}}

# Architecture-conditional
{{ if eq .chezmoi.arch "arm64" -}}
ARCH="aarch64"
{{ else -}}
ARCH="x86_64"
{{ end -}}

# Custom data from chezmoi.toml [data] section
git_name = "{{ .git.name }}"
git_email = "{{ .git.email }}"

# 1Password secret (requires op CLI)
api_key = {{ onepasswordRead "op://Vault/Item/Field" }}

验证模板能否正确渲染

chezmoi execute-template < "$(chezmoi source-path)/dot_config/app/config.toml.tmpl"
chezmoi cat ~/.config/app/config.toml   # Show rendered output without applying

---

13. 安全更新（应用前查看差异）

从远程拉取变更并先行检查，比直接运行 chezmoi update 更安全：

chezmoi git -- pull                    # 1. Pull source changes only (no apply)
chezmoi diff                           # 2. Review what WOULD change in home directory
chezmoi apply --dry-run --verbose      # 3. Dry run — shows actions without executing
chezmoi apply                          # 4. Apply after review
chezmoi status                         # 5. Confirm clean state

适用情况：拉取在另一台机器上所做的变更时，或两次同步之间间隔较长时。这样可以避免本地编辑遭到意外覆盖。

---

14. Doctor（诊断）

排查 chezmoi 设置和环境问题：

chezmoi doctor                         # Full diagnostic — checks all components

需要核实的关键字段：

检查项	预期结果	检查失败时的含义
config-file	found ~/.config/chezmoi/chezmoi.toml	配置缺失或路径错误
source-dir	~/gh/vjspc/dotfiles is a git working tree (clean)	源目录有未提交变更或不是 Git 仓库
git-command	found /opt/homebrew/bin/git	未安装 Git
edit-command	found /opt/homebrew/bin/hx	未配置编辑器
1password	found /opt/homebrew/bin/op	模板需要 1Password CLI
age/gpg	info = optional	仅加密文件需要

chezmoi doctor | grep -v "^ok"         # Show only warnings and errors

参考

• 设置指南 - 安装、多账户 GitHub、迁移
• 提示词模式 - 详细的工作流示例
• 配置 - chezmoi.toml 设置、模板
• 密钥检测 - 处理检测到的密钥

Chezmoi 文档：https://www.chezmoi.io/reference/

---

故障排除

问题	原因	解决方案
找不到 chezmoi	尚未安装	通过 brew install chezmoi 安装
源路径为空	尚未初始化	运行 chezmoi init
未设置 Git 远程仓库	缺少 GitHub 仓库	运行 chezmoi git -- remote add origin URL
应用失败	模板错误	使用 chezmoi diff 检查模板语法
合并冲突	源和目标已分叉	使用 chezmoi merge 解决
检测到密钥	明文凭据	使用搭配 1Password/Doppler 的 chezmoi 模板
forget 需要 TTY	需要交互式确认	使用 chezmoi forget --force <path>
找不到模板	缺少 .tmpl 后缀	使用 chezmoi add --template 创建 .tmpl

执行后反思

此技能完成后，在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表。
2. 参数或输出是否有变化？ — 如果底层工具的接口发生变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要变通处理？ — 如果你不得不临时变通（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时遇到同样的问题。

仅在问题确实存在且可复现时更新，不要更新推测性内容。