Git Worktree 完全指南：告别分支切换焦虑

在多个分支间频繁切换，每次都要重新加载环境、重启服务？git worktree 让你同时拥有多个工作目录，互不干扰，效率翻倍。

为什么需要 Worktree？

日常开发中，我们经常面临这样的场景：

• 正在 feature 分支开发新功能，突然要紧急修复 hotfix 分支的 Bug
• 想同时对比两个分支的代码差异，或者并行跑两个版本的服务
• 每次切换分支，IDE 都要重新索引，编译缓存失效，等待时间漫长

常规的 git checkout 或 git switch 虽然能切换分支，但同一时间只能在一个分支上工作。如果你切走再切回来，之前的环境（如依赖安装、编译产物）可能已经丢失或需要重建。

git worktree 的解决方案：在同一个 Git 仓库中，创建多个独立的工作目录，每个目录对应不同的分支，它们共享同一个 .git 对象库（节省磁盘空间），但各自拥有独立的工作区、暂存区和索引。

环境准备

• Git 版本要求：2.5+（推荐 2.15+，功能更完善）
• 查看版本：git --version

一、新增 Worktree

1.1 基于已有分支创建

语法：git worktree add <新目录路径> <分支名>

示例：

git worktree add ../my-project-hotfix hotfix

效果：

• 在当前目录的上一级创建 my-project-hotfix 文件夹
• 该目录自动切换到 hotfix 分支
• 你可以像操作一个独立的 Git 仓库一样，在里面正常 add、commit、push

1.2 基于新分支创建

语法：git worktree add -b <新分支名> <路径>

示例：

git worktree add -b new-feature ../my-project-feature

效果：

• 创建新分支 new-feature（基于当前 HEAD）
• 在新目录中检出该分支

1.3 基于远程分支创建

示例：

git worktree add ../my-project-remote origin/develop

效果：

• 基于远程 develop 分支创建一个本地跟踪分支（自动命名）
• 适合临时查看或测试远程分支代码

1.4 指定分支基点创建

语法：git worktree add -b <新分支名> <路径> <基点>

示例：

git worktree add -b hotfix-v2 ../project-hotfix-v2 v1.0

效果：

• 基于 v1.0 这个 tag 创建 hotfix-v2 分支并检出

1.5 查看所有 Worktree

git worktree list

输出示例：

/path/to/main-repo          abc123 [main]
/path/to/../project-hotfix  def456 [hotfix]
/path/to/../project-feature 789xyz [new-feature]

二、删除 Worktree

2.1 标准删除方式（推荐）

先进入主仓库目录：

cd /path/to/main-repo

删除指定 worktree：

git worktree remove <worktree路径>

示例：

git worktree remove ../my-project-hotfix

这个命令会：

• 删除对应的整个文件夹及其内容
• 清理 .git/worktrees/ 下的注册信息
• 更新内部引用，避免残留

2.2 处理未提交的修改

如果 Worktree 中有未提交的修改，命令会拒绝执行。你可以选择：

方式一：先提交

git add . && git commit -m "save work"

方式二：暂存起来

git stash

方式三：强制删除（丢弃所有未提交修改）

git worktree remove -f <路径>

2.3 如果文件夹已被手动删除

如果你已经直接用 rm -rf 或资源管理器删掉了文件夹，执行：

git worktree prune

这个命令会自动清理所有已经不存在的 worktree 残留记录。

2.4 移动 Worktree 位置

如果需要移动一个 worktree 到其他位置：

# 1. 先正常删除
git worktree remove <旧路径>

# 2. 重新添加到新位置
git worktree add <新路径> <分支名>

注意：如果该分支没有其他 worktree 在使用，可以重新添加。

2.5 删除主仓库本身

主仓库（最初 git clone 的那个目录）不能通过 git worktree remove 删除，只能手动删除整个文件夹：

rm -rf /path/to/main-repo

删除前请确认所有 worktree 已清理完毕。

三、操作速查

新增（基于已有分支）

git worktree add <路径> <分支>

新增（基于新分支）

git worktree add -b <新分支> <路径>

新增（基于指定基点）

git worktree add -b <新分支> <路径> <基点>

列出所有 worktree

git worktree list

列出详细信息

git worktree list --verbose

删除（标准）

git worktree remove <路径>

强制删除（丢弃修改）

git worktree remove -f <路径>

清理残留记录

git worktree prune

锁定 worktree（防止误删）

git worktree lock <路径>

解锁 worktree

git worktree unlock <路径>

修复 worktree 状态

git worktree repair <路径>

查看帮助

git worktree --help

四、常见问题

问：一个分支能同时被多个 worktree 检出吗？

不能。一个分支同时只能被一个 worktree 检出。

问：删除 worktree 后分支还在吗？

在。分支引用保留在主仓库中，不会因为 worktree 删除而丢失。

问：worktree 之间会互相影响吗？

不会。各自有独立的暂存区和工作区，互不干扰。

问：主仓库能用 remove 删除吗？

不能。主仓库只能手动删除整个文件夹。

问：删除前有未提交修改怎么办？

先 commit 或 stash，或者用 -f 强制丢弃。

问：worktree 可以跨磁盘分区吗？

建议在同一文件系统内使用，跨分区可能遇到问题。

问：可以嵌套创建 worktree 吗？

不建议。worktree 目录不能再作为主仓库创建新的 worktree。

问：如何保留文件夹但注销 worktree？

不支持直接保留。可以先 mv 移走文件夹，再执行 git worktree prune 清理记录。

五、实用场景示例

场景一：并行开发与修复

# 主仓库在 main 分支，开发新功能中
git worktree add -b feature-login ../project-login

# 突然收到 hotfix 紧急任务
git worktree add ../project-hotfix hotfix

# 现在你可以：
# - 终端1：在 ../project-login 中继续开发
# - 终端2：在 ../project-hotfix 中修复 Bug
# - 互不干扰，随时切换！

场景二：代码对比与测试

git worktree add ../project-v1 v1.0
git worktree add ../project-v2 v2.0

# 分别进入两个目录，跑起服务，对比功能差异或性能表现

场景三：快速 Code Review

git worktree add -b review-pr ../project-pr origin/pull/123/head
cd ../project-pr
# 查看代码、运行测试，不影响当前开发环境

场景四：Git Bisect 调试

# 用 worktree 进行二分查找，不影响主工作区
git worktree add -b bisect-work ../project-bisect
cd ../project-bisect
git bisect start
git bisect bad HEAD
git bisect good v1.0
# 开始二分查找...

场景五：同时维护多个版本

# 同时维护 v1.x 和 v2.x 两个大版本
git worktree add ../project-v1 v1-branch
git worktree add ../project-v2 v2-branch

# 两个版本可以同时编译、测试、部署

六、进阶技巧

6.1 配合别名简化操作

在 ~/.gitconfig 中添加：

[alias]
    wt = worktree
    wta = worktree add
    wtr = worktree remove
    wtl = worktree list
    wtp = worktree prune

之后使用更简洁：

git wta ../new-feature feature
git wtl
git wtr ../new-feature

6.2 锁定与解锁

防止误删除或修改：

git worktree lock <路径>
git worktree unlock <路径>

被锁定的 worktree 无法被 remove 或 prune。

6.3 修复异常状态

如果 worktree 出现异常，可以修复：

git worktree repair <路径>

七、注意事项

• 所有 worktree 共享 .git/objects，节省磁盘空间，但不要手动修改 .git 目录
• 一个分支同一时间只能被一个 worktree 检出，避免冲突
• 建议 worktree 放在主仓库同级或父级目录，便于管理
• 用完即删，避免积累过多 worktree 导致混乱
• VSCode、JetBrains 系列都可以直接打开 worktree 目录作为独立项目

八、总结

核心记忆点：

• 新增用 add，删除用 remove，清理用 prune
• 不要直接删文件夹 —— 用 remove 更干净
• 删除 worktree 不会删除分支，分支依然存在于主仓库中
• 一个分支同时只能被一个 worktree 检出

Worktree 特别适合多任务并行的开发场景，尤其当你的项目编译或启动耗时较长时。结合 Git 的 bisect、submodule 等功能，worktree 能大幅提升调试效率。

如果团队中有成员还不了解这个功能，建议分享给他们 —— 早用早享受。

你的开发效率，从放弃频繁 git checkout 开始。

如果你有其他关于 Git Worktree 的问题或使用心得，欢迎在评论区交流讨论。