git worktree add 正确用法：先确保分支存在或加-b创建，路径须为上层/同级空目录，主工作树必须干净；报错“already checked out”因残留元数据，需git worktree list后remove清理。
git worktree add 命令怎么用才不踩坑
直接执行 git worktree add ../feature-x feature-x 很容易失败，常见报错是 fatal: 'feature-x' is already checked out at ... 或 fatal: invalid reference: feature-x。这不是命令写错了，而是分支不存在、路径已占用或当前目录有未提交改动干扰了主工作树。
- 确保目标分支存在：用
git branch -a确认feature-x已存在；若不存在，加-b参数创建：git worktree add -b feature-x ../feature-x origin/main - 路径不能是子目录：
../feature-x必须是**上层或同级目录**，不能是./sub/feature-x（Git 会拒绝，因可能污染主工作树） - 主工作树必须干净：即使你只是想开新 worktree，Git 仍会检查主工作树的 index 是否 clean；若有 untracked 文件但没被 .gitignore 覆盖，也会卡住——此时可先
git add -f或临时git clean -fd（谨慎）
多个 worktree 共享配置文件（如 .env.local）怎么同步
每个 worktree 是独立工作区，.env.local、.vscode/settings.json 这类文件不会自动复制。手动 cp 容易漏、难维护，尤其当新增 worktree 时。
- 不要用硬链接或 symlink 指向主工作树：worktree 删除后链接失效，IDE 可能报错
- 推荐做法：在
git worktree add后立即运行脚本复制关键配置，例如：git worktree add ../hotfix-123 hotfix/123 && cp .env.local ../hotfix-123/ && cp .vscode/settings.json ../hotfix-123/.vscode/ - 更可持续的方式：把配置模板放在
.gitignore外的templates/目录下，所有 worktree 初始化时统一cp -n templates/.env.local ./（-n避免覆盖已有修改）
git worktree list 显示的路径和分支状态怎么看懂
git worktree list 输出类似：
/Users/a/project 8a3f2c1 [main] /Users/a/project-hotfix 7d1e9b4 [hotfix/123] /Users/a/project-feature f5a0c82 [detached HEAD]
第一列是路径，第二列是 HEAD 提交哈希，方括号内是当前检出状态。注意三个细节：
-
[detached HEAD]表示该 worktree 检出的是某个 commit，不是分支——常见于用git worktree add ../tmp abc123（commit hash）创建，后续无法直接git push，需先git switch -c new-branch - 路径显示为相对或绝对？取决于你添加时用的是相对路径（如
../foo）还是绝对路径（如/tmp/foo），建议统一用相对路径，避免迁移仓库后路径失效 - 如果某 worktree 目录被手动删除但未用
git worktree remove，list仍会显示它，且状态标为prunable；此时要运行git worktree prune清理残留记录，否则git gc可能出错
删除 worktree 时 git worktree remove 和 rm -rf 的区别
直接 rm -rf ../feature-x 看似快，但会留下“幽灵登记”：主仓库 .git/worktrees/ 下仍有对应目录元数据，下次 git worktree list 还显示它，且 git worktree add 会拒绝同名路径。
- 正确流程：先
git worktree remove ../feature-x（它会删目录 + 清理元数据） - 如果目录已删但元数据还在，用
git worktree prune扫描并清理所有失效登记 - 别依赖 IDE 的“删除项目”功能：VS Code 或 WebStorm 删除目录时不会调用 Git 接口，等价于
rm -rf - 注意：remove 不影响远程分支，也不删除本地分支引用——
git branch -d feature-x是另一回事，别混淆
