从 GNU Stow 迁移到 Chezmoi：Dotfiles 管理的现代化演进

背景

长期以来，许多开发者使用 GNU Stow 来管理自己的 dotfiles（点配置文件）。Stow 的核心逻辑是基于符号链接（symlink）：配置文件存储在 Git 仓库中，按目录分组为“包”，执行 Stow 命令后，这些文件会被链接到用户的主目录（home directory）。对于单台机器而言，这种模式简单高效，命令具有幂等性，学习成本极低。

然而，随着设备数量的增加，Stow 的局限性逐渐暴露。作者拥有三台 Mac 设备（一台用于工作的 MacBook Pro、一台用于个人的 MacBook Air 以及一台作为小型服务器的 Mac Mini），并偶尔使用 Linux 虚拟机。在多设备环境下，Stow 的符号链接机制带来了两大痛点：

1. 双向同步导致的冲突：符号链接是双向的。在任何一台机器上对配置文件的修改，都会直接写入该机器克隆的仓库中。这导致不同设备上的仓库副本容易变得“脏”（dirty working trees），且修改往往难以追溯，极易引发合并冲突。
2. 新机器引导（Bootstrap）困难：Stow 无法覆盖已存在的真实文件。在新 Mac 上，Homebrew 等工具运行后，~/.zprofile 或 ~/.gitconfig 等文件可能已经存在。手动删除冲突文件并重新 Stow 所有包的过程繁琐且容易出错。此外，Stow 仅处理文件，无法管理 Homebrew 包或 macOS 系统设置，这些需要额外的脚本按顺序执行。

为了解决这些多设备同步和自动化引导的问题，作者将目光投向了 Chezmoi，一款旨在解决 dotfiles 管理复杂性的现代工具。

核心内容

Chezmoi 采用了一种与 Stow 截然不同的架构，它通过“源目录”（Source Directory）作为唯一真相源（Single Source of Truth），彻底摒弃了符号链接的自动双向同步机制。

1. Chezmoi 的工作原理

Chezmoi 在主目录下维护一个特殊的 Git 仓库，默认路径为 ~/.local/share/chezmoi。

• 添加文件（Add）：使用 chezmoi add 命令可以将现有的配置文件复制到源目录中。Chezmoi 会自动根据文件路径生成源目录中的名称。例如，~/.zshrc 会被命名为 dot_zshrc，~/.config/gh/config.yml 会被命名为 dot_config/gh/config.yml。这种命名方式将主目录结构镜像到源目录中，所有以点开头的文件或目录都加上 dot_ 前缀。
• 应用更改（Apply）：chezmoi apply 命令负责将源目录中的文件“写回”到主目录对应的路径。这些文件是真实的文件，而非符号链接。如果主目录中的文件与源目录中的副本不一致，chezmoi diff 会显示差异，而 apply 会将主目录文件恢复为源目录的状态。
• 权限与模板：
  • private_ 前缀：用于标记敏感文件，Chezmoi 会自动将其权限设置为 0600（仅所有者读写）。
  • .tmpl 后缀：将文件标记为 Go 语言模板，允许读取每台机器的特定数据（如主机名）。

这种“单向同步”机制（从源目录到主目录）是作者最喜爱的特性：除非刻意在仓库中做出更改，否则仓库内容不会因其他机器上的编辑而自动改变，从而避免了意外的冲突。

2. 追踪的内容与配置结构

作者的 Chezmoi 源目录结构简洁，主要包含以下几类内容：

• 核心配置文件：包括 zsh、git、shellcheck、Ghostty 终端和 GitHub CLI (gh) 的配置。
• AI Agent 配置：追踪了 Claude Code 的 settings.json 和 Codex 的 config.toml，确保 AI 代理在所有机器上行为一致。敏感配置（如 gh 的 hosts.yml）使用了 private_ 前缀。
• 多身份 Git 配置：通过三个不同的 gitconfig 文件（dot_gitconfig、dot_gitconfig-pers、dot_gitconfig-werk）区分工作和个人身份。利用 Git 原生的 includeIf 功能，根据仓库路径（~/canvas/pers/ 或 ~/canvas/werk/）自动加载对应的配置文件。Chezmoi 的作用是确保这三个文件在所有机器上始终存在。
• 机器特定数据：仅有一处机器特定数据，即 .chezmoi.toml.tmpl 模板文件。它通过交互式提示询问并存储机器名称，用于设置主机名。作者倾向于保持配置尽可能通用，以减少对 Go 模板语法的依赖。
• 忽略文件：.chezmoiignore 确保 README.md、Brewfile 等文件仅存在于源目录，不会被写入主目录；.gitignore 则排除版本控制中的锁文件。

3. 新机器引导流程

在新 Mac 上初始化 Chezmoi 的过程非常简洁，仅需两条命令：

brew install chezmoi
chezmoi init --apply \
  --promptString machineName=mini \
  https://github.com/rednafi/dotfiles.git

• chezmoi init：将仓库克隆到 ~/.local/share/chezmoi。
• --apply：立即将受跟踪的文件写入主目录。
• --promptString：预先回答模板中的交互问题（如机器名称），避免手动输入。

4. 自动化脚本与 Homebrew 管理

Chezmoi 允许在 .chezmoiscripts 目录下放置脚本，这些脚本会在 apply 期间执行。文件名决定了执行时机：

• before_：在写入任何文件之前执行。
• after_：在所有文件写入后执行。
• run_onchange_：仅在首次 apply 时执行，或当脚本内容发生变化时执行。

作者利用 run_onchange_ 机制优化 Homebrew 的安装流程。脚本中嵌入了 Brewfile 的 SHA256 哈希值。当 Brewfile 内容变更时，哈希值改变，导致脚本渲染内容改变，从而触发 Chezmoi 再次运行该脚本。脚本内部使用 brew bundle check 检查包是否已安装，若未安装则执行 brew bundle install。--no-upgrade 标志确保脚本不会意外升级已安装的包，升级操作保持手动可控。

关键要点

• 单一真相源：Chezmoi 以源目录为唯一配置源，通过 apply 单向同步到主目录，避免了 Stow 符号链接带来的双向同步冲突。
• 文件而非链接：主目录中的文件是真实文件，而非符号链接，这使得文件权限管理和冲突检测更加直观。
• 强大的命名约定：通过 dot_、private_ 和 .tmpl 等前缀/后缀，Chezmoi 在文件名中编码了权限、模板和路径映射信息，简化了管理。
• 智能脚本执行：基于文件名的脚本触发机制（如 run_onchange_）允许精确控制安装脚本的执行时机，结合哈希检查可实现高效的依赖管理。
• 简化多身份管理：Chezmoi 确保所有必要的配置文件（如多套 Git 配置）在所有设备上存在，配合 Git 原生功能实现身份隔离。
• 最小化模板依赖：作者倾向于保持配置通用，仅在必要时（如主机名）使用 Go 模板，以降低维护复杂度。

意义与影响

从 GNU Stow 迁移到 Chezmoi 代表了 dotfiles 管理工具从“简单的文件链接”向“状态管理基础设施”的演进。

1. 解决多设备同步痛点：对于拥有多台开发机或服务器的开发者，Chezmoi 的单向同步模型消除了因符号链接导致的状态不一致和合并冲突，显著降低了维护成本。
2. 提升自动化可靠性：通过集成脚本执行