如何使用 git worktree

Git worktree 是什么？

git worktree 允许 在同一个仓库下同时 checkout 多个分支到不同目录，而无需重复 clone 仓库。

适用于：

• 多分支并行开发
• 修 bug 时不想打断当前分支工作
• 在保持一个干净主目录的同时进行试验
• 减少磁盘占用（相较多次 clone）

一、基础使用

① 查看当前 worktree

git worktree list

② 添加一个新的 worktree（最常用）

列如在目录 ../feature-login 开一个基于 main 的独立目录：

git worktree add ../feature-login main

要创建新分支：

git worktree add ../feature-login -b feature/login

③ 删除一个 worktree

git worktree remove ../feature-login

如果 worktree 已经被手动删除目录，需清理：

git worktree prune

二、典型工作流示例

⭐ 工作流 1：并行开发

你正在 main 上开发，但突然要修紧急 bug：

git worktree add ../hotfix-bugfix -b hotfix/bugfix main

cd ../hotfix-bugfix

修完后合并即可，不会影响你当前正在操作的主目录。

⭐ 工作流 2：大型重构 vs 小型修复并行

• repo/ → 正常开发
• repo-refactor/ → 大型重构
• repo-hotfix/ → 快速补丁

只需：

git worktree add ../repo-refactor -b refactor/v2

git worktree add ../repo-hotfix -b fix/minor-issue

⭐ 工作流 3：对比两个历史版本

git worktree add ../old-v1 v1.0.0

git worktree add ../old-v2 v2.0.0

可方便 diff 和运行代码测试。

⚠️ 三、常见问题与坑

(1) 当前分支不能在多个 worktree 中出现

如果你添加时遇到错误：

fatal: 'main' is already checked out at …

解决方式：

• 新建分支 checkout：

git worktree add ../tmp -b tmp-branch main

(2) 切勿手动删除 worktree 目录

如果你直接 rm -rf worktree-dir

Git 会认为它依旧存在，导致错误。

正确删除：

git worktree remove path

git worktree prune # 若已被强删

(3)

.git

目录并不在 worktree 里

每个 worktree 目录下会有 .git 文件（不是文件夹），指向主仓库的 .git/worktrees/…。

这属于正常结构，不要修改。

️ 四、常用命令速查表

五、进阶技巧

✔ 快速试验代码（不污染当前分支）

git worktree add ../try -b try/code main

# 实验完成后删掉整个目录：

git worktree remove ../try