git worktree用法

‌git worktree 是 Git 从 2.5 版本开始引入的功能，允许你在同一个仓库中创建多个独立的工作目录，每个目录可以检出不同的分支，实现多分支并行开发而无需频繁切换‌。‌‌

什么是 worktree 以及它解决什么问题
worktree 的核心价值是让你在同一套代码库里拥有多个"平行宇宙"，每个工作目录独立检出不同分支，彼此互不干扰。传统 Git 单工作目录模式下，开发者同一时间只能检出一个分支，切换分支时需要频繁使用 stash 保存和恢复工作状态，带来显著的上下文切换成本且容易因状态保存不当导致工作丢失。‌‌
百科
worktree 的巧妙之处在于底层机制：执行 git worktree add 时，Git 不会复制整个.git 文件夹，而是在目标路径创建一个指向原仓库的.git 文件，这意味着所有 worktree 共享同一个对象数据库（commit、blob、tree），但每个 worktree 有自己独立的 HEAD、index 和暂存区。对比直接 git clone 多份代码，假设原仓库 500MB，五个克隆就是 2.5GB，而五个 worktree 只占一份历史加五份工作文件，节省了大量磁盘空间。‌‌
需要注意一个重要限制：同一个分支通常不能同时被两个 worktree 检出，Git 会阻止这种操作以防止两个目录同时修改同一个分支造成混乱。‌‌‌

常用命令和实际用法
创建新 worktree 是最常用的操作，基本语法是 git worktree add <路径> [分支名]。例如 git worktree add …/hotfix 会自动创建名为 hotfix 的新分支并在…/hotfix 目录检出。如果要基于现有分支创建，使用 git worktree add <路径> <分支>，前提是目标分支当前没有在其他 worktree 中被检出。创建 detached HEAD 的临时分析 worktree 可以用 git worktree add --detach <路径> <提交号>，适合复现线上 bug 或分析历史提交。‌‌‌

查看当前所有 worktree 使用 git worktree list，输出会显示每个工作目录的路径、当前检出的提交和分支信息。删除 worktree 使用 git worktree remove <路径>，只有干净的工作区（无未提交修改）才能直接删除，不干净的可以用–force 强制删除。如果手动 rm -rf 删除了目录，Git 那边还留着记录，需要再用 git worktree prune 清理残留元数据。‌‌‌

锁定 worktree 可以防止其管理文件被自动修剪，适合存储在便携设备或网络共享上的工作区，使用 git worktree lock <路径>，解锁用 git worktree unlock。‌‌‌

适合的使用场景和注意事项
worktree 最适合的场景是需要同时在多个分支上工作，比如紧急插入的 hotfix、多分支对照、一边构建一边开发。在现代 AI 编程场景下，开发者通过同时创建多个 worktree 来并行运行独立的 AI 会话，分别处理测试、调试和功能开发等任务，每个目录只给一个清晰目标，AI 在这种清晰边界下更稳定。‌‌‌

使用时有几个关键注意事项：worktree 目录建议建在主仓库目录外面（平级目录），建里面容易跟主工作区的文件搅在一起，也可能被一些工具误扫。每个 worktree 负责自己的同步，不存在主目录更新了其他目录自动跟着更新的情况，进入哪个 worktree 就更新哪个 worktree 当前所在的分支。用完记得用 git worktree remove 清理，直接删目录的话 Git 那边还留着记录。‌‌‌

主流 IDE 如 VS Code 和 IntelliJ 支持多 worktree 的独立打开和管理，打开 worktree 目录后状态栏会明确显示当前分支与 Git 仓库关联关系。‌‌