Git Worktree 教程 - 面向新手的动手示例

这个教程适合谁

你会 Git。commit、branch、merge 都不是问题。但 git worktree 是你知识里的空白，man page 又没帮上忙。

本教程靠动手教学。你会建一个真实仓库、跑真实命令、看真实结果。每个代码块都能复制粘贴。学完之后：

✅ 你会用过全部 9 个 git worktree 子命令
✅ 你会理解为什么每个存在
✅ 你会判断什么场景该用 worktree
✅ 你会有一套可以每天复用的清理工作流

所需时间： 约 20 分钟。 前置： Git 2.17+（git --version 查看）。

想要参考手册而不是教程？见 Git Worktree 完全指南。

第 1 部分：环境搭建

建一个一次性仓库，方便你跟着做而不冒风险。

mkdir ~/worktree-tutorial && cd ~/worktree-tutorial
git init demo-repo
cd demo-repo

# main 上几个 commit
echo "# Demo Repo" > README.md
git add README.md && git commit -m "Initial commit"

echo "Version 1" > VERSION
git add VERSION && git commit -m "Add VERSION file"

# 建两个后面要用的分支
git branch feat/login
git branch feat/payments

git log --oneline --all

你应该看到三个分支上共两个 commit（main、feat/login、feat/payments）。

第 2 部分：你的第一个 Worktree

# 在 demo-repo 里：
git worktree add ../demo-login feat/login

刚刚发生了什么？

Git 建了 ../demo-login/ 新目录
在其中检出 feat/login
在 .git/worktrees/demo-login/ 加了元数据

验证：

git worktree list
# /home/user/worktree-tutorial/demo-repo   abc123 [main]
# /home/user/worktree-tutorial/demo-login  abc123 [feat/login]

ls ../demo-login
# README.md  VERSION

两个目录包含相同文件（同一 commit），但在不同分支上。

练习： 两个文件夹都用编辑器打开。在一个里改个文件 —— 注意另一个不受影响。

第 3 部分：并行修改

真正用上并行性。

# 在主 worktree（demo-repo）里改：
cd ~/worktree-tutorial/demo-repo
echo "Main branch feature" >> README.md
git add README.md && git commit -m "Update README on main"

然后跳到另一个 worktree：

cd ~/worktree-tutorial/demo-login
cat README.md          # 还是旧版本 —— 不同分支！
echo "Login feature" > LOGIN.md
git add LOGIN.md && git commit -m "Add LOGIN feature"

回到主 worktree：

cd ~/worktree-tutorial/demo-repo
ls                     # 没有 LOGIN.md
git branch             # 你在 main，LOGIN.md 在 feat/login 上

两个分支独立前进。零冲突。

第 4 部分：一步到位创建新分支 Worktree

最常用的真实场景：一条命令同时建新分支和新 worktree。

cd ~/worktree-tutorial/demo-repo
git worktree add -b feat/signup ../demo-signup main

这会：

从 main 建分支 feat/signup
在其上建 worktree ../demo-signup

现在共有四个 worktree：

git worktree list
# /home/user/worktree-tutorial/demo-repo     [main]
# /home/user/worktree-tutorial/demo-login    [feat/login]
# /home/user/worktree-tutorial/demo-signup   [feat/signup]

提示： 把这作为启动任何新任务的默认动作。老习惯 git checkout -b new-branch 其实是 worktree 机会伪装。

第 5 部分：尝试同一分支检出两次

Git 会阻止你造出不一致的状态。演示一下：

cd ~/worktree-tutorial/demo-repo
git worktree add ../demo-login-2 feat/login
# fatal: 'feat/login' is already checked out at '/home/user/worktree-tutorial/demo-login'

教训： 一个分支同一时刻活在一个 worktree 里。同一分支想并行工作，就得开两个不同分支（可能从同一起点分出）。

第 6 部分：列出 Worktree（机器可读）

写脚本时：

git worktree list --porcelain

输出：

worktree /home/user/worktree-tutorial/demo-repo
HEAD abc1234...
branch refs/heads/main

worktree /home/user/worktree-tutorial/demo-login
HEAD def5678...
branch refs/heads/feat/login

用 awk 或 grep 好解析：

git worktree list --porcelain | awk '/^worktree / { print $2 }'

第 7 部分：清理

cd ~/worktree-tutorial/demo-repo

# 干净删除一个 worktree
git worktree remove ../demo-signup

# 验证
git worktree list
# demo-signup 消失

# 分支仍在：
git branch
#   feat/login
#   feat/payments
#   feat/signup   <-- 还在
# * main

# 把分支也删了（未合并，所以用 -D）：
git branch -D feat/signup

如果有未提交改动怎么办？

cd ../demo-login
echo "dirty work" >> LOGIN.md    # 未提交
cd ../demo-repo
git worktree remove ../demo-login
# fatal: contains modified or untracked files, use --force to delete it

两个选择：

# A) 保存工作：
cd ../demo-login && git add . && git commit -m "WIP" && cd -
git worktree remove ../demo-login

# B) 强制删除，丢失工作：
git worktree remove --force ../demo-login

完整清理指南：如何删除 Git Worktree →

第 8 部分：模拟死 Worktree

如果你（或队友）直接删了 worktree 文件夹会怎样？

# 先建一个：
git worktree add ../demo-oops feat/payments

# 模拟失误：
rm -rf ../demo-oops

# Git 还以为它存在：
git worktree list
# /home/user/worktree-tutorial/demo-repo     [main]
# /home/user/worktree-tutorial/demo-oops     (inaccessible)

# 清理：
git worktree prune -v
# Removing worktrees/demo-oops: gitdir file points to non-existent location

git worktree list
# demo-oops 消失

第 9 部分：完整 Worktree 工作流

把它们串起来 —— 日常工作流：

# 每天开始
cd ~/projects/myapp
git worktree list    # 我在搞什么？

# 新任务：开 worktree
git worktree add -b feat/new-thing ../myapp-new-thing origin/main
cd ../myapp-new-thing
# ... 干活、commit、push ...

# 紧急事件：并行热修复
cd ~/projects/myapp
git worktree add -b hotfix/urgent ../myapp-hotfix origin/main
cd ../myapp-hotfix
# ... 修、commit、push、PR ...

# 每天 / 每周结束：清理
cd ~/projects/myapp
git worktree list
# 逐个过，决定保留 / 删除
git worktree remove ../myapp-finished-task
git branch -d feat/finished-task

第 10 部分：用 ParallelCode 的等价操作

上面所有动作，但通过 UI：

打开 ParallelCode，选仓库
点 "+ 新任务"
输入任务名
ParallelCode 创建 worktree、切换到新分支，甚至可以在里面启动 Claude Code / Cursor Agent
完成后点"归档" —— worktree 被删除，分支可选删除

原生 Git 工作流什么都没丢 —— 底下跑的是同样的命令。你获得了跨所有仓库的任务可视化总览，加上对 AI 编程代理的原生集成。

免费下载 ParallelCode →

练习（可选）

自己试试：

多仓库 worktree：在一个仓库里给另一个仓库建 worktree。git worktree list 两个都显示吗？（答：不 —— list 是按仓库的。）
分离 worktree：git worktree add --detach ../demo-at-first-commit abc1234 —— 检视首个 commit 时的代码，然后删掉。
基于 tag 的 worktree：git tag v0.1，然后 git worktree add ../demo-v0.1 v0.1。你在什么分支？（没分支 —— 在 tag 的 commit 上分离。）
重命名 worktree：git worktree move ../demo-login ../demo-auth。分支名会变吗？
锁定 worktree：git worktree lock ../demo-login --reason "test"。然后 remove。解锁再试。

你学到的

✅ git worktree add 的三种形式（已有分支、新分支、分离）
✅ git worktree list 查看
✅ git worktree remove 清理（干净和 --force）
✅ git worktree prune 从 rm -rf 恢复
✅ git worktree move 重命名
✅ git worktree lock / unlock 保护
✅ Worktree、分支、主仓库之间的关系

继续前进

🔧 git worktree add 每个参数 → git worktree add 完整参考
🗑️ 精通清理 → 如何删除 Git Worktree
🚨 修复头号错误 → 无法删除被 worktree 使用的分支
🤖 应用它 → Claude Code + Git Worktree：并行 AI 开发
📖 参考 → Git Worktree 完全指南
⚡ 技巧 → 并行 AI 开发的 5 个技巧

做完这个教程，你已经能上真实并行工作流了。

ParallelCode 把你刚学的一切变成一键 UI，一等公民支持 Claude Code 和 Cursor Agent。

下载 ParallelCode →