SuperAPI AI 工具集

unity-worktree-cow

编程与开发

查看项目

更新于 11-19 04:55

技能介绍

unity-worktree-cow(命令名 uwt)用于在 Unity 项目中创建多个并发 worktree,同时避免每个 worktree 占用完整磁盘空间。其核心做法是:在编辑器关闭时对项目(工作树 + Library/)做一次“黄金快照”,之后每个新 worktree 都是该快照的块克隆,再由 git 将其同步到指定分支。每个 worktree 拥有真实、私有、独立的 Library/,不做符号链接或引用共享;只有磁盘块被共享,写入时分离。

用途与主要能力

工具提供以下命令:doctor 通过实际执行一次克隆并读取引用计数来验证卷是否支持块克隆,同时检查黄金快照与缓存根是否位于项目所在卷、编辑器是否在运行、快照状态,并在 Windows 长路径未启用时警告;seed 对工作树和 Library/(去除拒绝列表项)及 git 索引做快照,编辑器或 Data Store 打开项目时拒绝执行;new 执行 git worktree add --no-checkout、克隆快照、将快照索引交给 git、reset --hard 到分支、校验零跟踪差异、清理继承的未跟踪文件并填充 Library/;hydrate 为以其他方式创建的现有 worktree 提供从黄金快照克隆的 Library/;list 列出仓库所有 worktree 及其分支、锁定状态和 Library/ 来源;measure 按物理块重叠计算各 worktree 与黄金快照的私有磁盘占用;remove 在编辑器互锁保护下执行 git worktree remove。

工具同时支持 Git 和 Unity Version Control(Plastic):根据项目上方最近的 .git 或 .plastic 判断,要求 cm 在 PATH 中且服务器可达。Plastic 工作区的黄金快照位于主工作区的 .plastic/uwt/golden,new 接受分支路径(如 /main/task),缺失分支会在服务器上创建。

使用方式

将技能文件夹提交到仓库中代理读取技能的位置,然后在 Library/ 已导入且编辑器关闭的检出目录中依次运行:doctor(始终先运行)、seed、new BRANCH。对以其他方式创建的 worktree 使用 hydrate PATH。new 默认在仓库旁创建 <repo>-<branch> 目录,可用 --path 指定;黄金快照位于 <repo>/.git/uwt/golden,当 worktree 与仓库不在同一卷时用 UWT_CACHE_ROOT 指定。list、new、remove、measure 支持 --json 输出供代理使用。退出码:0 成功、2 失败、3 被编辑器互锁拒绝。

适用场景

适合需要同时运行多个 Unity 编辑器、并行编译与测试、代理驱动开发,以及大型资源项目需要多个分支工作区的团队。资料给出的实测数据(Windows 11 ReFS)显示,41k 文件、33.7 GiB 的项目用 uwt new 仅占 344 MiB、耗时 29 秒,首次打开并工作后约 1.98 GiB。

限制与注意事项

要求文件系统支持块克隆且黄金快照与 worktree 位于同一卷:Windows 需 ReFS(Dev Drive,Windows 11 24H2 及以上,NTFS 不支持);macOS 为 APFS;Linux 为 btrfs、XFS(reflink=1)或 ZFS ≥ 2.2(measure 除外),ext4 不支持。没有字节复制回退,不支持克隆的卷上所有命令都会拒绝。seed 必须在编辑器关闭时执行;worktree 会重置到其分支,未提交的编辑不会带过去;编辑器升级后需重新 seed;不得在 worktree 之间互相克隆,只能从黄金快照克隆;Windows 上需保持 worktree 根路径较短(除非启用 LongPathsEnabled);大小写折叠卷上仅大小写不同的路径会被拒绝;子模块默认不初始化(--init-submodules 为 git 专用);不支持部分(Gluon)和动态工作区。并行编辑器需各自指定 -logFile,并按项目路径显式定位。首次打开仍需完整脚本编译,生产项目四编辑器并发时耗时 396–419 秒,应预留分钟级时间并错开首次打开。DataStore 在重导入触发段压缩时会转为私有,需按“after”列而非 uwt new 列估算磁盘。