git worktree add 不能直接在已有目录上运行，因为目标路径必须为空或不存在，否则会报错“fatal: 'xxx' is not an empty directory”，这是为防止覆盖文件和混淆分支状态；git 需完全掌控检出过程。
git worktree add 为什么不能直接在已有目录上运行
因为 git worktree add 要求目标路径必须为空或根本不存在。如果目录里有文件（哪怕是 .git 以外的残留），命令会直接报错：fatal: 'xxx' is not an empty directory。
这不是 Git 故意为难，而是为了避免覆盖已有工作内容、混淆不同分支的文件状态。Git 需要完全掌控该目录的检出过程。
- 解决办法：用
rm -rf清空目录（确认无重要未提交内容）再重试 - 更安全的做法是换一个新目录名，比如从
feature/login改成feature/login-v2 - 注意：不要手动把
.git文件挪进去——worktree 的.git是个指向主仓库gitdir的文件，不是普通仓库
多个 worktree 共享同一个 .git 目录但各自独立检出，意味着什么
所有 worktree 都指向同一个 .git 目录（即主工作区的 .git），所以它们共享配置、reflog、对象数据库、hooks 和远程定义；但每个 worktree 有自己独立的 HEAD、index 和工作目录文件。
这带来几个关键行为特征：
- 在一个 worktree 里执行
git checkout dev，不会影响其他 worktree 的当前分支 -
git fetch只需在任一 worktree 中运行一次，所有 worktree 都能立刻看到新 remote 分支 - 但
git pull仍需在每个 worktree 单独执行，因为它 =fetch+merge，而 merge 操作绑定具体工作区 - 如果在 A worktree 中修改了
.git/config（比如加了新 remote），B worktree 立刻可见——这是共享配置的好处，也是风险点
git worktree prune 什么时候必须手动跑
当某个 worktree 目录被直接 rm -rf 删除（而非用 git worktree remove），Git 就会在主仓库的 .git/worktrees/ 下留下一个“僵尸记录”。下次运行 git status 或 git branch 时，可能报错：fatal: invalid reference: refs/worktrees/xxx/HEAD。
这时就得手动清理：
- 先运行
git worktree prune—— 它会扫描并删除所有已丢失路径的 worktree 记录 - 如果提示 “Pruning working tree xxx…”，说明清理成功
- 注意：prune 不会删文件，只删元数据；也不会自动修复损坏的
HEAD符号链接，那种情况得进.git/worktrees/xxx/手动检查HEAD - CI 或自动化脚本中建议定期加一句
git worktree prune -v，避免积压失效条目
和 git clone --shared 或 submodule 相比，worktree 的实际优势在哪
核心就一点：零对象拷贝 + 真实多分支并行编辑。clone --shared 共享对象但仍是完整仓库副本，占用额外磁盘；submodule 是子项目嵌套，不解决“同一仓库多分支开发”问题。
worktree 的真实价值体现在日常高频操作中：
- 切换分支不用
git checkout等待检出，直接cd进对应目录——尤其对大仓库（10w+ 文件），省下数秒到数十秒 - IDE 可以同时打开多个 project 窗口，分别指向不同 worktree，彼此编辑互不干扰，也不用反复刷新索引
- 测试 hotfix 时，可临时
git worktree add ../hotfix-test hotfix/2.1.3，验证完git worktree remove ../hotfix-test，干净利落 - 缺点也很实在：不支持部分克隆（
--filter），也不能单独 push/pull 某个 worktree——它不是远程同步单元，只是本地视图
真正容易被忽略的是：worktree 的 HEAD 是符号链接，一旦你用脚本误删或覆盖了它，Git 就会认为这个 worktree “损坏”，后续 git status 可能卡住或报诡异错误。修法很简单：cd .git/worktrees/xxx && ln -sf ../../refs/heads/main HEAD（按实际分支名替换）。
