# GitHub Fork + git worktree 的标准工作流

GitHub Fork + git worktree 的标准工作流

一、这个 workflow 解决什么问题？

使用 git worktree 的目标是：

• ✅ 多个分支同时开发，不用频繁 checkout
• ✅ main 永远干净、只做同步
• ✅ 每个功能一个独立目录（非常适合 AI Agent）
• ✅ PR 基线永远正确（upstream/main）

---

二、核心约定（非常重要）

仓库角色

• upstream：主项目仓库（只读）
• origin：你的 Fork（可写）
• 主工作区：只用于同步 main
• worktree 目录：只用于功能分支开发

分支约定

• ❌ 不在 main 上开发
• ✅ 每个功能分支 = 一个 worktree
• ✅ PR 一定从 worktree 分支发起

---

三、一次性初始化（只做一次）

git clone git@github.com:yourname/project.git
cd project
git remote add upstream git@github.com:org/project.git
git fetch upstream

让 fork 的 main 对齐上游：

git checkout main
git reset --hard upstream/main
git push origin main --force

此时：

• 主目录 = 干净 main
• 不在这里写代码

---

四、日常开发的标准流程（重点）

1️⃣ 确保 main 是最新（每天 / 每个任务前）

在 主目录：

git checkout main
git fetch upstream
git reset --hard upstream/main
git push origin main --force

⚠️ main 只做一件事：跟 upstream 同步

---

2️⃣ 为新功能创建 worktree + 分支（关键步骤）

git worktree add ../project-feat-login -b feat/login

结果：

• 新目录：../project-feat-login
• 新分支：feat/login
• 基线：当前 main（即 upstream/main）

目录结构示例：

project/                # main（只同步）
project-feat-login/     # 功能分支
project-fix-order/      # 另一个功能

---

3️⃣ 在 worktree 中开发（只在这里写代码）

cd ../project-feat-login

正常开发：

git status
git add .
git commit -m "feat: add login validation"

✅ 不影响其他分支
✅ 不影响 main
✅ 可并行多个 worktree

---

4️⃣ PR 前同步上游（非常重要）

在 功能 worktree 目录：

git fetch upstream
git rebase upstream/main

• 保证 PR 是干净直线历史
• 没有 merge commit

---

5️⃣ 推送分支并创建 PR

git push origin feat/login

GitHub 上创建 PR：

• base：org/project:main
• compare：yourname:feat/login

---

6️⃣ Review 修改（仍然在 worktree）

# 修改代码
git add .
git commit -m "fix: address review comments"
git push origin feat/login

❌ 不新建分支
❌ 不新建 PR

---

7️⃣ PR 合并后清理 worktree

回到 主目录：

cd project
git worktree remove ../project-feat-login
git branch -D feat/login
git push origin --delete feat/login

---

五、同时开发多个功能（git worktree 的优势）

git worktree add ../project-feat-a -b feat/a
git worktree add ../project-fix-b  -b fix/b

你可以：

• 一个 worktree 给 Claude
• 一个给 Cursor
• 一个给你自己

互不干扰 👍

---

六、完整流程总结（给 AI 的一句话）

main 只同步 upstream → 每个功能一个 worktree → 在 worktree 提交 → rebase → PR → 合并后删除 worktree

---

七、常见错误 & 规避

❌ 错误 1：在 main 写代码

👉 main 永远只做 reset --hard upstream/main

❌ 错误 2：PR 基于旧分支

👉 worktree 创建前一定先同步 main

❌ 错误 3：worktree 不清理

👉 PR 合并后必须 remove

❌ 错误 4：merge upstream

👉 永远 rebase，不 merge

---

八、这套 workflow 特别适合你现在的场景

结合你之前的背景（量化 / agent / 多 AI 协作）：

• ✔ 每个 Agent = 一个 worktree
• ✔ PR 天然干净
• ✔ 可自动化（脚本 / Bot）
• ✔ 维护者体验极好

---