Chezmoi 工作流指南：多机同步点文件与配置管理最佳实践

chezmoi-workflows by terrylica/cc-skills

118 周安装量

29 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/terrylica/cc-skills --skill chezmoi-workflows

开发运维命令行工具版本控制

🇨🇳中文介绍

Chezmoi 工作流

何时使用此技能

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

将点文件备份到 Git 仓库
在多台机器间同步配置文件
跟踪 shell 配置、编辑器设置或其他点文件的更改
使用 chezmoi 管理模板化配置
排查源文件和目标文件之间的配置漂移问题

架构

组件	位置	用途
源	`$(chezmoi source-path)`	包含点文件模板的 Git 仓库
目标	`~/`	主目录（已部署的文件）
远程	GitHub（建议私有仓库）	跨机器同步和备份
配置

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

2. 跟踪文件更改

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

chezmoi status                         # 1. 确认文件显示为已修改
chezmoi diff ~/.zshrc                  # 2. 查看更改内容
chezmoi add ~/.zshrc                   # 3. 添加到源（如果已配置，会自动提交）
chezmoi git -- log -1 --oneline        # 4. 确认提交已创建
chezmoi git -- push                    # 5. 推送到远程仓库

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

chezmoi add ~/.config/app/config.toml  # 1. 将文件添加到源
chezmoi managed | grep app             # 2. 确认在受管列表中
chezmoi git -- push                    # 3. 推送到远程仓库

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

chezmoi update                         # 1. 拉取 + 应用（单条命令）
chezmoi verify                         # 2. 验证所有文件与源匹配
chezmoi status                         # 3. 确认没有差异

5. 推送所有更改

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

chezmoi status                         # 1. 查看所有差异
chezmoi re-add                         # 2. 重新添加所有受管文件（自动提交）
chezmoi git -- push                    # 3. 推送到远程仓库

brew install chezmoi                   # macOS

初始化（全新开始）

/usr/bin/env bash << 'CONFIG_EOF'
chezmoi init                           # 创建空的源
chezmoi add ~/.zshrc ~/.gitconfig      # 添加首批文件
gh repo create dotfiles --private --source="$(chezmoi source-path)" --push
CONFIG_EOF

初始化（克隆现有仓库）

chezmoi init git@github.com:<user>/dotfiles.git
chezmoi apply                          # 部署到主目录

将源移动到自定义位置（例如，用于多账户 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                    # 应显示新位置

8. 更改远程仓库

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

chezmoi git -- remote -v                                              # 查看当前配置
chezmoi git -- remote set-url origin git@github.com:<user>/<repo>.git # 更改
chezmoi git -- push -u origin main                                    # 推送到新的远程仓库

9. 解决合并冲突

/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status                  # 1. 识别冲突文件
chezmoi git -- diff                    # 2. 查看冲突
# 在 $(chezmoi source-path) 中手动编辑文件
chezmoi git -- add <resolved-files>    # 3. 暂存已解决的文件
chezmoi git -- commit -m "Resolve merge conflict"
chezmoi apply                          # 4. 应用到主目录
chezmoi git -- push                    # 5. 推送解决方案
GIT_EOF

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

chezmoi verify                         # 退出码 0 = 所有文件与源匹配
chezmoi diff                           # 输出为空 = 无差异
chezmoi managed                        # 列出所有跟踪的文件
chezmoi git -- log --oneline -3        # 最近的提交历史

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

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

chezmoi managed | grep config.local     # 1. 确认文件被跟踪
chezmoi forget --force ~/.config/app/config.local.toml  # 2. 从源中移除（--force 跳过 TTY 提示）
chezmoi git -- push                     # 3. 将移除操作推送到远程仓库
ls ~/.config/app/config.local.toml      # 4. 验证文件在主目录中仍然存在

何时使用：机器特定的配置、不应同步的包含秘密的文件、意外添加的文件。

使用 Go 模板创建操作系统/架构条件性配置：

将现有文件转换为模板

chezmoi add --template ~/.config/app/config.toml  # 1. 作为模板添加（在源中创建 .tmpl 后缀）
chezmoi edit ~/.config/app/config.toml             # 2. 在 $EDITOR（helix）中编辑模板
chezmoi diff ~/.config/app/config.toml             # 3. 预览将发生的变化
chezmoi apply ~/.config/app/config.toml            # 4. 将渲染后的模板应用到主目录

# 操作系统条件块
{{ if eq .chezmoi.os "darwin" -}}
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" -}}
export HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
{{ end -}}

# 架构条件
{{ if eq .chezmoi.arch "arm64" -}}
ARCH="aarch64"
{{ else -}}
ARCH="x86_64"
{{ end -}}

# 来自 chezmoi.toml [data] 部分的自定义数据
git_name = "{{ .git.name }}"
git_email = "{{ .git.email }}"

# 1Password 密钥（需要 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   # 显示渲染后的输出，但不应用

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

从远程仓库拉取并包含审查步骤 —— 比盲目的 chezmoi update 更安全：

chezmoi git -- pull                    # 1. 仅拉取源更改（不应用）
chezmoi diff                           # 2. 查看在主目录中将会发生的变化
chezmoi apply --dry-run --verbose      # 3. 模拟运行 —— 显示操作但不执行
chezmoi apply                          # 4. 审查后应用
chezmoi status                         # 5. 确认状态干净

何时使用：当拉取另一台机器上所做的更改时，或者在长时间未同步后。避免本地编辑被意外覆盖。

排查 chezmoi 设置和环境问题：

chezmoi doctor                         # 完整诊断 —— 检查所有组件

需要验证的关键字段：

检查项	期望值	失败的含义
config-file	`found ~/.config/chezmoi/chezmoi.toml`	配置缺失或路径错误
source-dir	`~/own/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"         # 仅显示警告和错误

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

问题	原因	解决方案
chezmoi not found	未安装	通过 `brew install chezmoi` 安装
Source path empty	未初始化	运行 `chezmoi init`
Git remote not set	缺少 GitHub 仓库	运行 `chezmoi git -- remote add origin URL`
Apply fails	模板错误	使用 `chezmoi diff` 检查模板语法
Merge conflicts	源和目标已分叉	使用 `chezmoi merge` 解决
Secrets detected	明文凭据	使用带有 1Password/Doppler 的 chezmoi 模板
forget needs TTY	交互式确认	使用 `chezmoi forget --force <path>`
Template not found	缺少 `.tmpl` 后缀	使用 `chezmoi add --template` 创建 `.tmpl`

🇺🇸English

Chezmoi Workflows

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

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

1. Status Check

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

After editing a config file, add it to 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. Track New File

Add a previously untracked config file:

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

Pull changes from GitHub and apply to home directory:

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

Bulk sync all modified tracked files to remote:

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

Install chezmoi

brew install chezmoi                   # macOS

Initialize (fresh start)

/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)

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

7. Configure Source Directory

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

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

Edit ~/.config/chezmoi/chezmoi.toml:

sourceDir = "~/path/to/dotfiles"

Verify:

chezmoi source-path                    # Should show new location

8. Change Remote

Switch to different GitHub account or repository:

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

/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)

After major operations, verify system state:

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. Forget (Untrack) a File

Stop tracking a file without deleting it from home directory:

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

When to use : Machine-specific configs, files with secrets that shouldn't be synced, files accidentally added.

12. Template Management

Create OS/architecture-conditional configs using Go templates:

Convert existing file to template

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

Common template patterns

# 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" }}

Verify template renders correctly

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

13. Safe Update (Diff Before Apply)

Pull from remote with review step — safer than blind 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

When to use : When pulling changes made on another machine, or after a long gap between syncs. Avoids surprise overwrites of local edits.

14. Doctor (Diagnostic)

Troubleshoot chezmoi setup and environment:

chezmoi doctor                         # Full diagnostic — checks all components

Key fields to verify :

Check	Expected	Meaning if failing
config-file	`found ~/.config/chezmoi/chezmoi.toml`	Config missing or wrong path
source-dir	`~/own/dotfiles is a git working tree (clean)`	Source dirty or not a git repo
git-command	`found /opt/homebrew/bin/git`	Git not installed
edit-command	`found /opt/homebrew/bin/hx`	Editor not configured
1password	`found /opt/homebrew/bin/op`

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

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/

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

Weekly Installs

Repository

terrylica/cc-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode91

gemini-cli90

codex88

cursor87

github-copilot87

amp84

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

104,900 周安装