chezmoi-workflows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chezmoi Workflows

Chezmoi 工作流

When to Use This Skill

何时使用该工具

Use this skill when:

Backing up dotfiles to Git repository
Syncing configuration files across machines
Tracking changes to shell configs, editor settings, or other dotfiles
Managing templated configurations with chezmoi
Troubleshooting dotfile drift between source and target

在以下场景使用该工具：

将dotfiles备份到Git仓库
跨设备同步配置文件
追踪Shell配置、编辑器设置或其他dotfiles的变更
使用chezmoi管理模板化配置
排查源端与目标端之间的dotfiles差异

Architecture

架构

Component	Location	Purpose
Source	`$(chezmoi source-path)`	Git repository with dotfile templates
Target	`~/`	Home directory (deployed files)
Remote	GitHub (private recommended)	Cross-machine sync and backup
Config	`~/.config/chezmoi/chezmoi.toml`	User preferences and settings

组件	位置	用途
Source	`$(chezmoi source-path)`	存储dotfile模板的Git仓库
Target	`~/`	主目录（已部署的文件）
Remote	GitHub（推荐设为私有）	跨设备同步与备份
Config	`~/.config/chezmoi/chezmoi.toml`	用户偏好设置与配置

1. Status Check

1. 状态检查

bash

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

bash

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. Track File Changes

2. 追踪文件变更

After editing a config file, add it to chezmoi:

bash

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

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

bash

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. Track New File

3. 追踪新文件

Add a previously untracked config file:

bash

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

添加之前未被追踪的配置文件：

bash

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. Sync from Remote

4. 从远程仓库同步

Pull changes from GitHub and apply to home directory:

bash

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

从GitHub拉取变更并部署到主目录：

bash

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

5. Push All Changes

5. 推送所有变更

Bulk sync all modified tracked files to remote:

bash

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

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

bash

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. First-Time Setup

6. 首次设置

Install chezmoi

安装chezmoi

bash

brew install chezmoi                   # macOS

bash

brew install chezmoi                   # macOS

Initialize (fresh start)

初始化（全新开始）

bash

/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

bash

/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

Initialize (clone existing)

初始化（克隆已有仓库）

bash

chezmoi init git@github.com:<user>/dotfiles.git
chezmoi apply                          # Deploy to home directory

bash

chezmoi init git@github.com:<user>/dotfiles.git
chezmoi apply                          # Deploy to home directory

7. Configure Source Directory

7. 配置源目录

Move source to custom location (e.g., for multi-account SSH):

bash

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

Edit

~/.config/chezmoi/chezmoi.toml

toml

sourceDir = "~/path/to/dotfiles"

Verify:

bash

chezmoi source-path                    # Should show new location

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

bash

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

编辑

~/.config/chezmoi/chezmoi.toml

：

toml

sourceDir = "~/path/to/dotfiles"

验证：

bash

chezmoi source-path                    # Should show new location

8. Change Remote

8. 更换远程仓库

Switch to different GitHub account or repository:

bash

chezmoi git -- remote -v                                              # View current
chezmoi git -- remote set-url origin git@github.com:<user>/<repo>.git # Change
chezmoi git -- push -u origin main                                    # Push to new remote

切换到不同的GitHub账号或仓库：

bash

chezmoi git -- remote -v                                              # View current
chezmoi git -- remote set-url origin git@github.com:<user>/<repo>.git # Change
chezmoi git -- push -u origin main                                    # Push to new remote

9. Resolve Merge Conflicts

9. 解决合并冲突

bash

/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status                  # 1. Identify conflicted files
chezmoi git -- diff                    # 2. Review conflicts

bash

/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. Validation (SLO)

10. 验证（SLO）

After major operations, verify system state:

bash

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

完成主要操作后，验证系统状态：

bash

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

Reference

参考资料

Setup Guide - Installation, multi-account GitHub, migration
Prompt Patterns - Detailed workflow examples
Configuration - chezmoi.toml settings, templates
Secret Detection - Handling detected secrets

Chezmoi docs: https://www.chezmoi.io/reference/

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

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

Troubleshooting

故障排查

Issue	Cause	Solution
chezmoi not found	Not installed	Install via `brew install chezmoi`
Source path empty	Not initialized	Run `chezmoi init`
Git remote not set	Missing GitHub repo	Run `chezmoi git -- remote add origin URL`
Apply fails	Template error	Check template syntax with `chezmoi diff`
Merge conflicts	Diverged source and target	Use `chezmoi merge` to resolve
Secrets detected	Plain text credentials	Use chezmoi templates with 1Password/Doppler

问题	原因	解决方案
找不到chezmoi	未安装	通过 `brew install chezmoi` 安装
源目录为空	未初始化	运行 `chezmoi init`
Git远程仓库未设置	缺少GitHub仓库	运行 `chezmoi git -- remote add origin URL`
部署失败	模板错误	使用 `chezmoi diff` 检查模板语法
合并冲突	源端与目标端内容分歧	使用 `chezmoi merge` 解决
检测到密钥	明文凭证	使用chezmoi模板结合1Password/Doppler管理