词元广场TOKPUB.COM - 欢迎您，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
Git Worktree：多分支并行开发的优雅姿势 | OpenCode 教程
Git Worktree：多分支并行开发
💡 一句话总结： git worktree让你在同一个仓库中同时检出多个分支，切换就是cd，不用 stash。
学完你能做什么
/workspaces 快速切换工作区你现在的困境
feature/new-api 分支开发新功能，代码改了一半。突然：hotfix 紧急修复什么时候用这一招
🎒 开始前的准备
确保你已经完成以下事项：
核心概念
什么是 Git Worktree？
# 传统方式：一个目录，一次只能在一个分支
my-project/ ← 只能是 main 或 feature，不能同时
# Worktree 方式：多个目录，多个分支并行
my-project/ ← main 分支
my-project-hotfix/ ← hotfix 分支（独立的目录）
my-project-review/ ← PR 分支（独立的目录）为什么比其他方案更好？
| 对比项 | git stash | git clone | git worktree |
|---|---|---|---|
| 磁盘占用 | 无 | 高（完整复制） | 低（共享 .git） |
| 分支并行 | ❌ 串行 | ✅ 并行 | ✅ 并行 |
| 上下文保留 | ❌ 丢失 | ✅ 独立 | ✅ 独立 |
| 同步成本 | 无 | 高（分别 fetch） | 低（共享数据） |
| 适用场景 | 临时切换（几分钟） | 需要完全隔离 | 长期并行开发 |
工作原理
git worktree add ../hotfix hotfix-branch：1.
../hotfix/2.
hotfix-branch 的文件放到这个目 录3.
.git 是一个文件，指向主仓库git fetch 一次，全部更新跟我做
第 1 步：查看当前 worktree
了解当前仓库的工作树状态。
/path/to/your-project abc1234 [main]第 2 步：创建一个新的 worktree
在不影响当前工作的情况下，同时开发另一个分支。
main 分支，需要去 hotfix/login 修 bug：Preparing worktree (checking out 'hotfix/login')
HEAD is now at abc1234 Fix login validation目录位置建议
../项目名-分支名），而不是项目内部。git worktree add ./hotfix✅ 推荐：
git worktree add ../my-project-hotfix第 3 步：在 worktree 中工作
体验独立的开发环境，互不干扰。
第 4 步：查看所有 worktree
确认你的工作树列表。
/path/to/your-project abc1234 [main]
/path/to/my-project-hotfix def5678 [hotfix/login]第 5 步：删除 worktree
任务完成后清理，避免工作树堆积。
第 6 步：在 OpenCode 中使用工作区
配合 OpenCode 的实验性工作区功能，在 TUI 中快速切换。
opencode tui，输入：/workspaces| 操作 | 说明 |
|---|---|
| 选择工作区 | 切换到对应的 worktree 目录 |
| + New workspace | 创建新的 worktree |
| 按 Delete 键 | 删除选中的 worktree |
检查点 ✅
git worktree add 创建新的工作树git worktree list 查看所有工作树git worktree remove 删除工作树/workspaces 切换进阶：最佳实践
1. 裸仓 库模式（Bare Repo Pattern）
code/
├── repo.git/ # 裸仓库（只有 .git 数据）
│ └── main/ # worktree：main 分支
├── feature/ # worktree：feature 分支
└── hotfix/ # worktree：hotfix 分支fetch 一次，全部 worktree 更新2. 命名规范
| 风格 | 示例 | 适用场景 |
|---|---|---|
| 项目-分支 | my-project-hotfix | 临时 worktree |
| 分支名直接用 | feature/login | 裸仓库模式 |
| 项目名 + 用途 | my-project-review | PR review 专用 |
3. 定期清理
4. 配合 IDE
踩坑提醒
⚠️ 同一分支不能同时检出
⚠️ worktree 目录不要放在项目内部
⚠️ node_modules 会重复
⚠️ stash 是全局的
实际应用场景
场景一：紧急 Bug 修复
你在 feature/new-api 开发新功能
→ 产品：「生产环境挂了！」
→ git worktree add ../hotfix hotfix/urgent
→ cd ../hotfix，修复，部署
→ cd ../feature，继续开发场景二：PR Review
同事：「帮我 review 一下这个 PR」
→ git fetch origin
→ git worktree add ../review origin/their-branch
→ cd ../review，运行测试，查看代码
→ review 完成，删除 worktree场景三：并行对比测试
想对比新旧实现的效果
→ git worktree add ../old-version v1.0.0
→ git worktree add ../new-version v2.0.0
→ 两个目录同时运行，对比结果常用命令速查
| 命令 | 用途 |
|---|---|
git worktree add <path> <branch> | 创建 worktree |
git worktree add -b <new-branch> <path> | 创建新分支 + worktree |
git worktree list | 列出所有 worktree |
git worktree remove <path> | 删除 worktree |
git worktree remove --force <path> | 强制删除（有未提交修改） |
git worktree prune | 清理孤立记录 |
git worktree lock <path> | 锁定（防止误删） |
git worktree move <path> <new-path> | 移动 worktree |
本课小结
| 概念 | 要点 |
|---|---|
| 是什么 | 一个仓库，多个工作目录，共享 .git 数据 |
| 解决什么 | 分支切换成本高、stash 风险、clone 浪费空间 |
| 何时使用 | 紧急修复、并行开发、PR review、对比测试 |
| 最佳实践 | 裸仓库模式、规范命名、定期清理 |
| OpenCode 集成 | /workspaces 快速切换 |
下一课预告
下一课我们学习 附录：实验性功能汇总。 你会了解到： 所有实验性功能的完整列表 按需启用哪些功能 环境变量配置技巧
附录：源码参考
点击展开查看源码位置
更新时间：2026-03-22
| 功能 | 文件路径 | 行号 |
|---|---|---|
| Worktree 适配器 | src/control-plane/adaptors/worktree.ts | 1-46 |
| 工作区路由中间件 | src/control-plane/workspace-router-middleware.ts | 38-49 |
| 实验性开关 | src/flag/flag.ts | 68 |
| TUI 工作区对话框 | src/cli/cmd/tui/component/dialog-workspace-list.tsx | 146-326 |
OPENCODE_EXPERIMENTAL_WORKSPACES=1：启用 TUI 工作区支持