chezmoi 实战：用 Git 管理 dotfiles

一、为什么需要一个 dotfiles 管理工具

chezmoi 用 Git 管理 dotfiles，让你在多台机器间一键同步 Shell、编辑器与开发环境配置。每个开发者电脑里都有一堆”点文件”：~/.zshrc、~/.gitconfig、~/.vimrc、SSH 配置、各种 CLI 工具的 rc 文件。换一台新电脑、重装系统，或者临时借用云主机做调试时，最痛苦的事就是把这些配置重新配一遍，而且往往配着配着就和旧机器不一致了。

复制粘贴虽然能救急，但维护两份配置会逐渐分叉：你改了 A 机器的别名忘了同步到 B，三个月后两台机器行为完全不同。更糟的是，手动 cp 很容易把含密钥的文件（比如 ~/.ssh/config、~/.aws/credentials）也一股脑传出去。chezmoi 就是为解决这类问题而生的 dotfiles 管理器：它以 Git 仓库作为唯一数据源，既能版本化、跨设备同步你的配置，又能安全地模板化和加密机密。

二、chezmoi 是什么，解决了什么

chezmoi 是一个用 Go 编写的 dotfiles 管理工具，核心思路是”声明式 + 幂等”：你在 Git 仓库里维护一份”源状态”（source state），chezmoi 负责把源状态可靠地应用到目标机器上的真实文件。它有四个关键特性：

• 以 Git 为唯一真相源：所有配置都进版本库，天然具备历史、回滚与多端同步能力。
• 模板化：同一份 .zshrc 可以通过条件逻辑，在 Mac 和 Linux、工作机和个人机上生成不同内容。
• 幂等应用：反复执行 chezmoi apply 结果一致，不会重复追加或破坏现有文件。
• 机密安全：支持用 age 加密敏感文件，明文永不入库。

和单纯的 stow 符号链接、或手写同步脚本相比，chezmoi 在”多环境差异”和”保密”这两件事上明显更省心。

三、快速安装

chezmoi 是单文件二进制，安装渠道很多。macOS 上用 Homebrew 最方便：

# macOS / Linux (Homebrew)
brew install chezmoi

# 或者用官方一键脚本
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b /usr/local/bin

# Arch / Ubuntu (snap)
snap install chezmoi --classic

# 验证
chezmoi --version

安装完成后，chezmoi 命令即可使用。它不会碰你任何现有配置，所有操作都先发生在独立的源目录里。

四、初始化与目录结构

如果你已经有了一个 dotfiles 的 Git 仓库，直接用 chezmoi init 并指向它；否则先初始化一个本地仓库：

# 方式一：从已有远程仓库初始化并立即应用
chezmoi init --apply git@github.com:yourname/dotfiles.git

# 方式二：本地先建，后补远程
chezmoi init
cd "$(chezmoi source-path)"
git remote add origin git@github.com:yourname/dotfiles.git

chezmoi 的工作目录默认在 ~/.local/share/chezmoi（可用 chezmoi source-path 查看）。源目录里的文件命名有约定：

~/.local/share/chezmoi
├── dot_zshrc            # 对应目标 ~/.zshrc
├── dot_gitconfig        # 对应目标 ~/.gitconfig
├── dot_config/
│   └── nvim/
│       └── init.lua     # 对应 ~/.config/nvim/init.lua
├── dot_zshrc.tmpl       # 模板文件，应用时会先渲染
├── .chezmoiignore       # 忽略规则
└── .chezmoi.toml.tmpl   # 模板化的 chezmoi 配置

规则很简单：dot_ 前缀会变成目标路径里的 .，dot_config_nvim_init.lua 这种下划线会被展开成目录层级。

五、管理第一个配置文件

把现有配置”接管”进来只需一条 add：

# 把现有 ~/.zshrc 纳入管理（自动复制到源目录）
chezmoi add ~/.zshrc

# 查看当前被管理的文件
chezmoi managed

# 编辑源文件（会打开源目录里的版本，而非直接改目标）
chezmoi edit ~/.zshrc

# 应用改动到真实文件，先 dry-run 看看会改什么
chezmoi apply --dry-run --verbose
chezmoi apply

chezmoi apply 之后，~/.zshrc 就会被源目录里的内容覆盖（默认是拷贝，不是符号链接，因此对目标程序完全透明）。日常改动循环就是 edit → apply → 提交 Git。

六、模板化：一份配置适配多台机器

这是 chezmoi 最强的能力。把文件后缀改成 .tmpl，就能用 Go 的 text/template 语法写条件逻辑。比如同一份 .gitconfig，工作和私人邮箱不同：

# dot_gitconfig.tmpl
[user]
    name = "Your Name"
{{- if eq .chezmoi.hostname "work-laptop" }}
    email = "you@company.com"
{{- else }}
    email = "you@gmail.com"
{{- end }}

[core]
    editor = "code --wait"

chezmoi 提供了内建变量：.chezmoi.os、.chezmoi.arch、.chezmoi.hostname、.chezmoi.username。你也可以在 ~/.config/chezmoi/chezmoi.toml 里定义自己的数据：

# ~/.config/chezmoi/chezmoi.toml
[data]
    email = "you@gmail.com"
    github = "yourname"

# 在模板中引用：{{ .email }} / {{ .github }}

这样工作机和个人机的差异被收敛进模板与一份配置数据，再也不用手维护两套文件。

七、与 direnv、mise 等工具协同

chezmoi 只管”文件同步”，但它和站里介绍过的其他环境工具是天然搭档。比如 direnv 用 .envrc 实现项目级环境隔离，把团队共享的环境变量下沉到仓库目录；mise 用 Rust 统一多语言运行时版本，避免每台机器 Node/Python/Go 版本参差。三者配合：chezmoi 负责把 .envrc、.tool-versions、编辑器配置分发到所有机器，direnv 和 mise 再在本地落地运行时环境，整条链路零手动配置。

编辑器方面，VS Code 的插件与设置同步也可以用 chezmoi 管理 settings.json 和 keybindings.json，实现”换机即还原”的完全一致体验。

八、机密信息怎么处理

dotfiles 里最危险的就是 ~/.ssh/、~/.aws/credentials 这类含密钥的文件。绝不能直接明文入库。chezmoi 内置 age 加密：

# 生成 age 密钥对，把公钥写进配置
chezmoi generate-age-key
# 在 ~/.config/chezmoi/chezmoi.toml 中指定：
# [age]
#     recipient = "age1xxxxxxx"

# 加密方式纳入管理
chezmoi add --encrypt ~/.ssh/config
chezmoi add --encrypt ~/.aws/credentials

另一道保险是 .chezmoiignore，用 glob 排除不该同步的文件：

# ~/.local/share/chezmoi/.chezmoiignore
dot_local/share/chezmoi/private_*
dot_config/secret_tool/

原则是：能加密的加密，不能公开的忽略，明文里只放真正通用的偏好设置。

九、日常工作流与多设备同步

日常三板斧：

# 改完源文件后提交
cd "$(chezmoi source-path)" && git add -A && git commit -m "chore: update zshrc" && git push

# 在另一台机器拉取并应用
chezmoi update

# 查看将要发生的变更
chezmoi diff

新机器上一条命令还原全部环境：

sh -c "$(curl -fsLS get.chezmoi.io)" -- -b /usr/local/bin
chezmoi init --apply git@github.com:yourname/dotfiles.git

常用命令对照如下表：

命令	作用
chezmoi add <文件>	把现有文件纳入管理
chezmoi edit <文件>	编辑源模板
chezmoi apply	应用源状态到目标
chezmoi diff	预览真实文件的差异
chezmoi update	拉取仓库并应用
chezmoi managed	列出已管理文件

十、常见坑与排障

现象	原因	解决
模板渲染报 can't evaluate field	引用了不存在的变量	检查 chezmoi.toml 的 [data] 键名
应用后文件没有变化	编辑的是目标文件而非源	用 chezmoi edit 改源目录
机密文件被推到公开库	忘了 --encrypt	改用加密添加并清理历史
chezmoi apply 报权限错误	目标文件只读或属主不同	检查文件权限与 sudo 需求

一个实用习惯：每次 apply 前先 --dry-run --verbose，确认只改了你期望的文件。配合 GitHub Actions 搭建 CI/CD 还能在提交时自动做模板语法校验，避免把错误配置推到所有机器。

十一、落地清单

• 用 chezmoi init 建好 Git 仓库，开启私有仓库。
• 先 add 高频配置：.zshrc、.gitconfig、编辑器设置。
• 多机器差异用 .tmpl + chezmoi.toml 数据收敛。
• 密钥文件一律 --encrypt，配置 .chezmoiignore 兜底。
• 新设备 chezmoi init --apply 一条命令还原。

把环境配置当成代码来维护，是开发者”复利”最高的一件事之一。当你第 N 次换新机器，只需两行命令就找回全部熟悉的 shell 与编辑器，那种踏实感，值得现在就动手。