stow

🛠️ GNU Stow：符号链接农场管理器

1. 本质定义 (Definition)

GNU Stow 是一个基于 Perl 编写的符号链接（Symlink）管理工具。 它通过虚拟映射的方式，将分散在操作系统各处的文件（Target），集中管理在一个仓库目录（Stow Directory）中。

核心哲学：存储与部署分离。

• 物理层：所有配置实体存储在 ~/dotfiles (Git 仓库)。
• 逻辑层：操作系统在 ~/.config 等位置看到的是指向实体的“虚像”（软链接）。

2. 拓扑结构 (Topology)

Stow 采用 “Package Folding” (软件包折叠) 逻辑。它将软件包内部的目录结构，“透明叠加”到目标目录中。

必须遵守的目录规范：

`~/dotfiles` (仓库根目录)
└── `package_name` (如 sway, nvim)
    └── `relative_path_to_target` (必须模仿目标路径结构)
        └── `config_file`

🏗️ 结构可视化示例

假设我们要管理 Sway 的配置（目标位置是 ~/.config/sway/config）：

/home/user/dotfiles/          <-- [Stow Directory] 在此执行命令
├── sway/                     <-- [Package] 包名
│   └── .config/              <-- [Structure] 对应 ~/.config
│       └── sway/
│           └── config        <-- [File] 实体文件
└── zsh/                      <-- [Package] 另一个包
    └── .zshrc                <-- [File] 对应 ~/.zshrc

执行 stow sway 后的效果： ~/.config/sway/config ➡️ ../../dotfiles/sway/.config/sway/config

3. 作战指令集 (Command Reference)

所有命令默认在 ~/dotfiles 目录下执行。

🛡️ 侦察 (Reconnaissance)

在执行任何操作前，务必先进行模拟！

stow -n -v <package>

• -n (—no): 模拟运行，不更改文件系统。
• -v (—verbose): 详细输出，显示将要创建/删除的链接。

🚀 部署 (Deploy)

stow <package>
# 例：
stow sway
stow zsh

• 作用：将包内的结构映射到上一级目录（默认是 ../ 即 ~）。

♻️ 刷新/重载 (Restow)

stow -R <package>

• 场景：当你移动了包内的文件，或者清理了死链（Dead Links）时。
• 逻辑：先 Unstow 再 Stow。

💣 撤销 (Undeploy)

stow -D <package>

• 作用：删除目标目录下的软链接（不会删除仓库里的源文件）。

🎯 指定目标 (Target Override)

stow -t /usr/local/bin <package>

• 场景：管理系统级文件（如 /etc 或 /usr），而非家目录文件。

4. 故障排除 (Troubleshooting)

🔴 冲突：Existing target is not owned by stow

错误信息： CONFLICT: ... stowed_path ... differs from target

原因： 目标位置（如 ~/.config/sway/config）已经存在一个真实的物理文件，为了防止数据丢失，Stow 拒绝覆盖它。

解决方案：

1. 备份/移动：将原文件移动到 Stow 仓库对应的位置。

   mv ~/.config/sway/config ~/dotfiles/sway/.config/sway/config

2. 部署：再次执行 stow sway。

🟡 路径错误：链接到了错误的地方

原因： Stow 包内的目录结构没有正确模仿目标路径。

• 错误：~/dotfiles/sway/config → 会链接为 ~/config
• 正确：~/dotfiles/sway/.config/sway/config → 会链接为 ~/.config/sway/config

5. 战略价值 (Strategic Value)

1. 版本控制 (GitOps)： 系统配置不再是黑盒。每一次修改都有 Commit 记录，可审计，可回滚（git revert）。
2. 模块化 (Modularity)： 可以将工作环境（Work）、游戏环境（Gaming）、开发环境（Dev）拆分为不同的包。 stow work vs stow gaming 实现环境的一键切换。
3. 快速灾难恢复 (Disaster Recovery)： 重装系统耗时从“一天”缩短为“几分钟”。 git clone ... + stow * = 复原。

6. 关联知识

• Symbolic Link: 理解软链接与硬链接的区别。
• Git: Stow 的最佳拍档。
• Ansible: 企业级的 Stow，原理相似（声明式状态）。