Git Worktree开发指南

1. 核心概念git worktree允许在同一个 Git 仓库下同时检出多个分支到不同目录避免频繁stash/checkout切换上下文。main-repo/ ← 主工作目录如 main ├── .git/ ← 唯一的 Git 对象库所有 worktree 共享 └── ... ../feature-login/ ← worktree 1独立目录检出 feature/login ../hotfix-urgent/ ← worktree 2独立目录检出 hotfix/urgent一个.git数据库多个工作目录所有 worktree 共享对象库、ref、config每个 worktree 绑定唯一分支同一分支不能同时被两个 worktree 检出完全独立的暂存区和工作区互不干扰无需 stash2. 创建 Worktree基本语法gitworktreeadd路径分支名常见场景场景命令说明检出现有分支git worktree add ../feature-login feature/login最常用创建新分支并检出git worktree add -b feature/login ../feature-login main基于 main 新建分支基于远程分支创建git worktree add ../hotfix origin/hotfix/urgent自动跟踪远程分支临时调试detached HEADgit worktree add --detach ../debug-temp abc1234不绑定分支排查问题用路径建议将 worktree 放在主仓库的同级目录而非子目录内避免被主仓库的.gitignore或构建工具误扫描。3. 日常使用在 worktree 中正常工作进入对应目录后所有 Git 操作与主仓库完全一致cd../feature-logingitstatus# 只反映当前 worktree 的状态gitadd/ commit / push / pull# 正常操作npminstall/ mvn compile# 独立构建不影响主目录查看所有 worktreegitworktree list输出示例/home/user/project abc1234 [main] /home/user/feature-login def5678 [feature/login] /home/user/hotfix-urgent ghi9012 [hotfix/urgent]⚠️ 关键限制同一分支不能被两个 worktree 同时检出会报错每个 worktree 有独立的 index暂存区git add只影响当前目录submodule 不会自动初始化需在每个 worktree 中手动git submodule update --init4. 删除 Worktree正确删除流程# 1. 先删除工作目录或直接 rm -rfrm-rf../feature-login# 2. 清理 worktree 元数据必须gitworktree prune一步到位推荐Git 2.17gitworktree remove../feature-login⚠️切勿只删目录不 prune残留元数据会导致git worktree list显示幽灵条目后续创建同名路径时出错。分支处理删除 worktree不会删除分支若该分支已合并且不再需要单独删除git branch -d feature/login5. 维护与最佳实践定期健康检查# 检查是否有失效的 worktree 引用gitworktree list--porcelain|grep-cprunable# 自动修复gitworktree prune-vIDE / 编辑器配置每个 worktree 应作为独立项目打开不要在一个窗口中混合多个 worktreenode_modules、target、.venv等构建产物需在各 worktree 中独立安装VS Code 推荐使用 “Add Folder to Workspace” 管理多个 worktreeCI / 脚本注意事项脚本中避免硬编码路径使用git rev-parse --show-toplevel获取当前 worktree 根目录git worktree内的GIT_DIR指向.git/worktrees/name/而非主.git/与 filter-repo 的兼容性执行git filter-repo前必须先删除所有 worktree重写完成后重新创建 worktree旧 worktree 引用的 commit hash 已失效6. 常见问题远程分支与本地分支冲突❓ 本地已有 test 分支能否基于 origin/test 再建 worktree不能直接检出同名分支。Git worktree 的硬性规则同一分支引用在同一时刻只能被一个工作目录检出。fatal: test is already checked out at /path/to/main-repo✅ 正确做法创建不同名的新分支只要新 worktree 检出的本地分支名与已检出的test不同就不会有任何冲突。远程origin/test只是只读跟踪引用不参与唯一性约束检查。# 基于 origin/test 创建新分支 my-test-fix并在新 worktree 中检出gitworktreeadd../my-test-fix-bmy-test-fix origin/test执行后状态工作目录检出的本地分支追踪的远程分支是否冲突主仓库testorigin/test—../my-test-fixmy-test-fixorigin/test自动设置上游✅ 无冲突其他替代方案方案命令适用场景Detached HEADgit worktree add --detach ../test-temp origin/test临时查看/测试无需提交移动现有分支先git checkout main再git worktree add ../test-work test让新 worktree 接管原分支⚠️特别提醒不要尝试手动修改.git/worktrees/下的元数据来绕过唯一性限制。这会导致多个 worktree 同时写入同一个 ref 文件造成索引损坏和历史混乱。7. Worktree vs 其他方案对比方案磁盘占用切换速度并行开发适用场景git checkout最低慢大项目❌简单串行开发git stash最低中❌临时保存修改git clone多份高N倍快✅完全隔离环境git worktree低共享对象库即时✅多分支并行开发推荐8. 速查清单# 创建gitworktreeadd../my-feature-bfeature/my-feature main# 基于远程分支创建不与本地同名分支冲突gitworktreeadd../my-test-fix-bmy-test-fix origin/test# 使用cd../my-featuregitstatusnpmtest# 查看gitworktree list# 删除gitworktree remove../my-feature# 维护gitworktree prune-v