From 64ade3772a82653e8fb5adddbe09f068942e1a04 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Sun, 26 Apr 2026 17:02:15 +0800 Subject: [PATCH 1/8] test --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index a716780..733b4fa 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ > 一站式業務管理平台，助你掌控銷售線、提升成交率。 ## 🚀 Tech Stack +test - **React 18** + **Vite 6** - Vanilla CSS（CSS Custom Properties 設計系統） From 228f84a04ed92b07b4a34e728f9590bd4fe59864 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Sun, 26 Apr 2026 21:23:11 +0800 Subject: [PATCH 2/8] test second --- src/main.jsx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/main.jsx b/src/main.jsx index 644bee6..073f9e9 100644 --- a/src/main.jsx +++ b/src/main.jsx @@ -8,3 +8,6 @@ ReactDOM.createRoot(document.getElementById('root')).render( , ); + + +//test \ No newline at end of file From 49ca715842a94dd477a5052807ab17bd818a2c46 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Sun, 26 Apr 2026 22:01:10 +0800 Subject: [PATCH 3/8] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=20Git=20Worktree?= =?UTF-8?q?=20=E5=9B=A2=E9=98=9F=E5=8D=8F=E4=BD=9C=E6=8C=87=E5=8D=97?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- GIT_WORKTREE_GUIDE.md | 444 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 444 insertions(+) create mode 100644 GIT_WORKTREE_GUIDE.md diff --git a/GIT_WORKTREE_GUIDE.md b/GIT_WORKTREE_GUIDE.md new file mode 100644 index 0000000..0d344c9 --- /dev/null +++ b/GIT_WORKTREE_GUIDE.md @@ -0,0 +1,444 @@ +# Git Worktree 团队协作指南 + +## 🎯 核心价值 + +Git Worktree 让你**同时在多个分支工作，无需频繁切换**，极大提升团队开发效率。特别适合 Vibe Coding（流畅编码体验）的开发模式。 + +--- + +## 📚 什么是 Git Worktree？ + +Git Worktree 是 Git 的一个强大功能，允许你在同一个仓库中维护**多个独立的工作目录**，每个目录可以关联到不同的分支。 + +### 关键对比 + +| 方面 | 传统切换分支 | Git Worktree | +|------|----------|------------| +| 切换分支耗时 | 重新加载所有文件 | 立即切换目录 | +| 同时修改多分支 | ❌ 需要stash/切换 | ✅ 并行开发 | +| 编译缓存 | 丢失（重编） | 保留（不同目录） | +| IDE 配置 | 共享（易冲突） | 独立（互不影响） | + +--- + +## 🚀 快速开始 + +### 基础命令 + +#### 1. 创建新工作树 +```bash +# 基于当前分支创建工作树 +git worktree add ../worktree-branch-name + +# 基于特定分支创建工作树 +git worktree add ../worktree-feature /path/to/branch-name + +# 创建并同时创建新分支 +git worktree add -b feature-new ../worktree-feature +``` + +#### 2. 列出所有工作树 +```bash +git worktree list +git worktree list --verbose # 显示详细信息 +``` + +#### 3. 删除工作树 +```bash +# 强制删除工作树 +git worktree remove ../worktree-feature + +# 或者先手动删除目录，再清理 +rm -rf ../worktree-feature +git worktree prune +``` + +#### 4. 修复损坏的工作树 +```bash +git worktree lock ../worktree-feature --reason "备份中" +git worktree unlock ../worktree-feature +``` + +--- + +## 💼 团队实战场景 + +### 场景 1: 并行开发多个功能分支 + +```bash +# 主工作树：处理 main 分支 +cd ~/project + +# 创建第一个功能分支工作树 +git worktree add ../wt-feature-login -b feature/login + +# 创建第二个功能分支工作树 +git worktree add ../wt-feature-payment -b feature/payment + +# 创建测试修复工作树 +git worktree add ../wt-bugfix-auth -b bugfix/auth-issue + +# 现在可以并行开发，互不干扰 +``` + +**文件结构：** +``` +project/ + ├── .git/ # 共享 git 仓库 + ├── src/ + ├── package.json + └── (主工作树内容) + +wt-feature-login/ + ├── src/ + ├── package.json + └── (feature/login 分支内容) + +wt-feature-payment/ + ├── src/ + ├── package.json + └── (feature/payment 分支内容) +``` + +### 场景 2: 紧急修复 + 功能开发 + +```bash +# 正在开发 feature/user-dashboard 分支 +# 突然需要修复线上 bug + +# ✅ 创建新工作树修复 bug（基于 main） +git worktree add ../wt-hotfix -b hotfix/critical-bug + +# 修复完成后直接提交、测试、部署 +# 原工作树继续开发，无需 stash/pop +``` + +### 场景 3: Code Review + 功能开发 + +```bash +# 需要检视同事的 PR（feature/checkout） +git worktree add ../wt-review feature/checkout + +# 一边测试同事代码，一边开发自己的功能 +# 完成后直接删除 review 工作树 +git worktree remove ../wt-review +``` + +--- + +## 🎨 最佳实践（Vibe Coding 友好） + +### ✅ DO（推荐做法） + +```bash +# 1. 统一的命名规范 +git worktree add ../wt-feature-- +git worktree add ../wt-feature-123-user-auth +git worktree add ../wt-bugfix-456-login-crash + +# 2. 创建包含所有 worktree 的快捷脚本 (创建 .worktree-setup.sh) +#!/bin/bash +# 快速创建常用工作树 +git worktree add -b develop ../wt-develop develop +git worktree add -b staging ../wt-staging staging +git worktree add -b feature-1 ../wt-feature-1 feature-1 + +# 3. 在 VS Code 中使用工作区功能 +# File > Add Folder to Workspace +# 添加 wt-feature-xxx 目录，同时编辑多个分支 + +# 4. 定期清理已删除的分支 +git worktree prune + +# 5. 在 IDE 中配置不同工作树的执行配置 +# 避免冲突（不同端口、不同调试器等） +``` + +### ❌ DON'T（避免做法） + +```bash +# ❌ 1. 不要在多个工作树中操作同一分支 +git worktree add ../wt1 feature/auth +git worktree add ../wt2 feature/auth # ❌ 冲突！ + +# ❌ 2. 不要忘记删除不用的工作树 +# 占用磁盘空间，容易混淆 + +# ❌ 3. 不要跨工作树共享 node_modules、build 目录 +# 创建 .gitignore 防止提交 +echo "node_modules/" >> ../.gitignore +echo "dist/" >> ../.gitignore +echo ".next/" >> ../.gitignore + +# ❌ 4. 不要在工作树中改变 git 配置 +# 所有工作树共享 .git/config +``` + +--- + +## 🛠️ 团队配置建议 + +### 1. 项目根目录结构规划 + +``` +project-repo/ +├── .git/ +├── .gitignore # 包含: node_modules, dist, .env 等 +├── .worktree-setup.sh # 工作树设置脚本 +├── src/ +└── README.md + +# 创建工作树目录（与仓库目录同级） +../wt-main/ +../wt-develop/ +../wt-feature-xxx/ +``` + +### 2. 团队规范文档 + +```markdown +## 工作树命名规范 +- 功能分支: wt-feature-{JIRA_ID}-{简短描述} +- 修复分支: wt-bugfix-{JIRA_ID}-{简短描述} +- 发布分支: wt-release-{版本号} +- 临时分支: wt-temp-{用途}-{创建日期} + +## 生命周期 +1. 创建: git worktree add +2. 开发: 在工作树中正常开发 +3. 提交: git commit, git push +4. 删除: git worktree remove +``` + +### 3. VS Code 工作区配置 (vscode-workspace) + +```json +{ + "folders": [ + { + "path": "../wt-main", + "name": "🔵 Main Branch" + }, + { + "path": "../wt-develop", + "name": "🟢 Develop Branch" + }, + { + "path": "../wt-feature-123", + "name": "🟡 Feature Auth" + } + ], + "settings": { + "files.exclude": { + "node_modules": true, + "dist": true, + ".next": true + } + } +} +``` + +--- + +## ⚡ 高级技巧 + +### 1. 自动化工作树管理脚本 + +```bash +#!/bin/bash +# worktree-manager.sh + +case "$1" in + create) + TYPE=$2 + ISSUE_ID=$3 + DESC=$4 + git worktree add -b "$TYPE/$ISSUE_ID-$DESC" "../wt-$TYPE-$ISSUE_ID" + echo "✅ 创建工作树: ../wt-$TYPE-$ISSUE_ID" + ;; + list) + git worktree list --porcelain + ;; + clean) + git worktree prune + echo "✅ 清理完成" + ;; + *) + echo "用法: $0 {create|list|clean}" + ;; +esac + +# 使用方式 +# ./worktree-manager.sh create feature 123 user-auth +# ./worktree-manager.sh list +# ./worktree-manager.sh clean +``` + +### 2. Git 别名快捷方式 + +```bash +# 在 ~/.gitconfig 中添加 +[alias] + wtadd = worktree add + wtlist = worktree list --porcelain + wtremove = worktree remove + wtprune = worktree prune + wtlock = worktree lock + wtunlock = worktree unlock + +# 使用 +git wtadd ../wt-feature-1 -b feature/auth +git wtlist +``` + +### 3. 与 CI/CD 集成 + +```yaml +# GitHub Actions 示例 +name: Multi-Branch Testing + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + branch: [main, develop, staging] + steps: + - uses: actions/checkout@v3 + with: + ref: ${{ matrix.branch }} + - name: Run tests + run: | + npm install + npm test +``` + +--- + +## 🐛 常见问题解决 + +### Q1: 工作树被锁定，无法删除 +```bash +git worktree unlock /path/to/worktree +git worktree remove /path/to/worktree +``` + +### Q2: 磁盘空间浪费，如何节省 +```bash +# 使用共享的 node_modules（不推荐） +# 或使用符号链接 +ln -s ../node_modules node_modules + +# 更好的方式：配置 npm 缓存 +npm install --cache-dir=../.npm-cache +``` + +### Q3: IDE 编译冲突（如 Java、C++ 项目） +```bash +# 为每个工作树使用不同的 build 目录 +# CMakeLists.txt 示例 +set(CMAKE_BINARY_DIR "${PROJECT_SOURCE_DIR}/../build-${GIT_BRANCH}") +``` + +### Q4: 多人团队，如何同步工作树状态 +```bash +# 创建 .git-worktrees.json 文件，共享配置 +{ + "active_worktrees": [ + { + "name": "wt-feature-123", + "branch": "feature/auth", + "owner": "alice", + "created_at": "2026-04-20" + } + ] +} + +# 定期同步 +git pull +git worktree prune +``` + +--- + +## 📊 性能对比 + +| 操作 | 传统切换 | Git Worktree | +|------|---------|-------------| +| 分支切换 | 2-5秒 | 0秒（目录切换） | +| 编译缓存命中 | 否（重编） | 是（命中率 80%+） | +| 磁盘占用（含依赖） | ~500MB | ~1GB（多工作树） | +| 同步时间 | N/A | <100ms | + +--- + +## 📋 Vibe Coding 工作流示例 + +### 典型的一天 + +```bash +# 🌅 早上 +cd ~/project +git worktree list # 查看现有工作树 + +# 🎯 处理新任务 +git worktree add -b feature/dashboard ../wt-dashboard +cd ../wt-dashboard +npm install # 仅需要一次 +npm run dev # 开发服务器运行 + +# 💬 收到 Code Review 反馈 +# 保持开发工作树继续运行 +cd ~/project +git worktree add feature/auth ../wt-review-auth +cd ../wt-review-auth # 检视同事代码 +# 无需关闭开发窗口，两个项目并行运行 + +# 🚨 线上紧急 Bug +git worktree add -b hotfix/payment ../wt-hotfix +cd ../wt-hotfix +npm run dev # 独立运行 +# 修复、测试、提交，然后删除 + +# 🌆 下午总结 +git worktree list +git worktree remove ../wt-review-auth +git worktree remove ../wt-hotfix +git worktree prune +``` + +--- + +## 🎓 学习资源 + +- **官方文档**: `man git-worktree` 或 `git worktree --help` +- **Git 官方**: https://git-scm.com/docs/git-worktree +- **案例集**: 在团队 Confluence 中创建工作树使用案例库 + +--- + +## 📞 技术支持 + +遇到问题？ + +1. **检查状态**: `git worktree list --verbose` +2. **清理环境**: `git worktree prune` +3. **查看日志**: `cd .git && grep -r "worktree" logs/` +4. **联系技术负责人**: 在团队 Slack 中 @tech-lead + +--- + +## 📝 更新日志 + +| 版本 | 日期 | 变更 | +|------|------|------| +| v1.0 | 2026-04-26 | 初始版本发布 | +| - | - | 包含基础用法、最佳实践、高级技巧 | + +--- + +**最后更新**: 2026 年 4 月 26 日 +**维护人**: 技术团队 +**欢迎反馈和改进意见！** From dc3e2b85f9d92cc0ffd28b55d07e7adbd25dcb46 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Sun, 26 Apr 2026 22:09:29 +0800 Subject: [PATCH 4/8] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=20Git=20Worktree?= =?UTF-8?q?=20=C3=97=20AI=20=E5=B9=B6=E8=A1=8C=E5=BC=80=E5=8F=91=E6=8C=87?= =?UTF-8?q?=E5=8D=97=EF=BC=8C=E5=A2=9E=E5=BC=BA=E5=9B=A2=E9=98=9F=E5=8D=8F?= =?UTF-8?q?=E4=BD=9C=E6=95=88=E7=8E=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- GIT_WORKTREE_GUIDE.md | 547 +++++++++++++++++------------------------- 1 file changed, 214 insertions(+), 333 deletions(-) diff --git a/GIT_WORKTREE_GUIDE.md b/GIT_WORKTREE_GUIDE.md index 0d344c9..932a18c 100644 --- a/GIT_WORKTREE_GUIDE.md +++ b/GIT_WORKTREE_GUIDE.md @@ -1,444 +1,325 @@ -# Git Worktree 团队协作指南 +# Git Worktree × AI 并行开发指南 -## 🎯 核心价值 +> **核心理念**：在 Vibe Coding 时代，AI 是你的结对编程伙伴。Worktree 让你同时开启多个 AI 工作流，互不干扰，效率倍增。 -Git Worktree 让你**同时在多个分支工作，无需频繁切换**，极大提升团队开发效率。特别适合 Vibe Coding（流畅编码体验）的开发模式。 +## 为什么 Vibe Coding 需要 Worktree ---- +传统工作流下，AI 辅助编码已经很强大。但当你需要同时处理多个任务时，频繁切换分支会打断 AI 的上下文，也打断你自己的心流。 + +**Worktree 的核心价值：每个工作树 = 一个独立的 AI 工作上下文** + +``` +主仓库窗口 AI 任务 1 窗口 AI 任务 2 窗口 +────────────── ────────────────── ────────────────── +main 分支 feature/login hotfix/payment +Copilot 聊天 Copilot 聊天 Copilot 聊天 +（看全局） （专注登录模块） （专注支付修复） +``` -## 📚 什么是 Git Worktree？ +典型收益： -Git Worktree 是 Git 的一个强大功能，允许你在同一个仓库中维护**多个独立的工作目录**，每个目录可以关联到不同的分支。 +- **AI 上下文更纯净**：每个工作树聚焦单一任务，AI 看到的代码噪音更少，回答更精准 +- **并行不阻塞**：等待 AI 生成代码时，切到另一个窗口继续推进其他任务 +- **零 stash 切换**：不再因为临时切换而打断 AI 对话和本地改动 +- **可重复的任务隔离**：每个 PR / issue 有自己的目录，环境变量、端口、调试配置独立 -### 关键对比 +适用场景： -| 方面 | 传统切换分支 | Git Worktree | -|------|----------|------------| -| 切换分支耗时 | 重新加载所有文件 | 立即切换目录 | -| 同时修改多分支 | ❌ 需要stash/切换 | ✅ 并行开发 | -| 编译缓存 | 丢失（重编） | 保留（不同目录） | -| IDE 配置 | 共享（易冲突） | 独立（互不影响） | +- 功能开发与紧急修复并行（各自跑 AI） +- AI 生成代码 review 时，不影响主开发窗口 +- 多个 issue 同时推进，按进度随时切换 --- -## 🚀 快速开始 +## 什么是 Git Worktree -### 基础命令 +Git Worktree 允许一个仓库在多个目录中同时检出不同分支。所有工作树共享同一份 Git 对象库，但每个工作树有自己的工作目录和 HEAD。 -#### 1. 创建新工作树 -```bash -# 基于当前分支创建工作树 -git worktree add ../worktree-branch-name +| 方面 | 传统切分支 | Git Worktree | +|---|---|---| +| 多任务并行 | 需要频繁切换 | 多目录同时运行 | +| stash 依赖 | 常见 | 基本不需要 | +| AI 上下文连贯性 | 切换后容易混乱 | 每个窗口独立保持 | +| IDE / 终端会话 | 经常被打断 | 长期保留 | +| 心智负担 | 高 | 低 | + +--- -# 基于特定分支创建工作树 -git worktree add ../worktree-feature /path/to/branch-name +## Vibe Coding 并行 AI 工作流 + +### 推荐工作模式 -# 创建并同时创建新分支 -git worktree add -b feature-new ../worktree-feature ``` +每个 Worktree 对应一个 AI 任务单元： -#### 2. 列出所有工作树 -```bash -git worktree list -git worktree list --verbose # 显示详细信息 +1. 为每个 issue / 任务创建独立工作树 +2. 在该目录下打开新的 IDE 窗口（或 Cursor / VS Code workspace） +3. 在该窗口中与 AI 对话，保持上下文专一 +4. 完成后 PR → merge → remove worktree ``` -#### 3. 删除工作树 -```bash -# 强制删除工作树 -git worktree remove ../worktree-feature +### AI 工具集成建议 -# 或者先手动删除目录，再清理 -rm -rf ../worktree-feature -git worktree prune -``` +**GitHub Copilot（VS Code）** +- 每个工作树单独用 `code ` 打开，Copilot Chat 上下文绑定在该窗口 +- 避免在同一窗口频繁切换文件夹，否则 Copilot 的代码感知会混乱 + +**Cursor** +- 用 `cursor ` 为每个任务开独立项目窗口 +- Cursor 的 Composer / Agent 模式在单一目录下效果最佳，scope 越小越准 + +**通用技巧** +- 在每个工作树根目录放一个 `TASK.md`，写清楚当前任务目标，作为 AI 对话的第一条 context +- 让 AI 知道它在哪个分支、解决什么问题，比直接扔代码效果好得多 + +### 并行任务示意 -#### 4. 修复损坏的工作树 ```bash -git worktree lock ../worktree-feature --reason "备份中" -git worktree unlock ../worktree-feature +# 终端 1：主功能开发（AI 正在生成代码，先去干别的） +cd ../wt-feature-123 && cursor . + +# 终端 2：同时处理热修复 +cd ../wt-hotfix-789 && cursor . + +# 终端 3：跑测试，不阻塞任何 AI 窗口 +cd ../wt-review-checkout && pnpm test ``` --- -## 💼 团队实战场景 +## 核心命令速查 -### 场景 1: 并行开发多个功能分支 +### 1) 创建工作树 ```bash -# 主工作树：处理 main 分支 -cd ~/project +# 在当前 HEAD 基础上创建工作树（分支与当前一致） +git worktree add ../wt-task-a -# 创建第一个功能分支工作树 -git worktree add ../wt-feature-login -b feature/login +# 基于已有分支创建工作树 +git worktree add ../wt-review feature/checkout -# 创建第二个功能分支工作树 -git worktree add ../wt-feature-payment -b feature/payment +# 创建新分支并创建工作树（推荐团队开发常用） +git worktree add -b feature/123-login ../wt-feature-123 main +``` -# 创建测试修复工作树 -git worktree add ../wt-bugfix-auth -b bugfix/auth-issue +命令格式说明： -# 现在可以并行开发，互不干扰 +```text +git worktree add [-b ] [] ``` -**文件结构：** -``` -project/ - ├── .git/ # 共享 git 仓库 - ├── src/ - ├── package.json - └── (主工作树内容) - -wt-feature-login/ - ├── src/ - ├── package.json - └── (feature/login 分支内容) - -wt-feature-payment/ - ├── src/ - ├── package.json - └── (feature/payment 分支内容) +### 2) 查看工作树 + +```bash +git worktree list +git worktree list --verbose ``` -### 场景 2: 紧急修复 + 功能开发 +### 3) 删除工作树 ```bash -# 正在开发 feature/user-dashboard 分支 -# 突然需要修复线上 bug +# 正常删除 +git worktree remove ../wt-feature-123 -# ✅ 创建新工作树修复 bug（基于 main） -git worktree add ../wt-hotfix -b hotfix/critical-bug +# 若存在未提交改动，使用 -f 强制删除 +git worktree remove -f ../wt-feature-123 -# 修复完成后直接提交、测试、部署 -# 原工作树继续开发，无需 stash/pop +# 清理已失效记录 +git worktree prune ``` -### 场景 3: Code Review + 功能开发 +### 4) 锁定与解锁 ```bash -# 需要检视同事的 PR（feature/checkout） -git worktree add ../wt-review feature/checkout - -# 一边测试同事代码，一边开发自己的功能 -# 完成后直接删除 review 工作树 -git worktree remove ../wt-review +git worktree lock ../wt-release --reason "release freeze" +git worktree unlock ../wt-release ``` --- -## 🎨 最佳实践（Vibe Coding 友好） +## 推荐目录规划 -### ✅ DO（推荐做法） +建议将工作树放在仓库同级目录，统一以 wt- 前缀命名。 -```bash -# 1. 统一的命名规范 -git worktree add ../wt-feature-- -git worktree add ../wt-feature-123-user-auth -git worktree add ../wt-bugfix-456-login-crash - -# 2. 创建包含所有 worktree 的快捷脚本 (创建 .worktree-setup.sh) -#!/bin/bash -# 快速创建常用工作树 -git worktree add -b develop ../wt-develop develop -git worktree add -b staging ../wt-staging staging -git worktree add -b feature-1 ../wt-feature-1 feature-1 - -# 3. 在 VS Code 中使用工作区功能 -# File > Add Folder to Workspace -# 添加 wt-feature-xxx 目录，同时编辑多个分支 - -# 4. 定期清理已删除的分支 -git worktree prune +```text +repo/ + .git/ + src/ + package.json -# 5. 在 IDE 中配置不同工作树的执行配置 -# 避免冲突（不同端口、不同调试器等） +../wt-feature-123-login/ +../wt-bugfix-456-crash/ +../wt-review-checkout/ ``` -### ❌ DON'T（避免做法） +命名建议： -```bash -# ❌ 1. 不要在多个工作树中操作同一分支 -git worktree add ../wt1 feature/auth -git worktree add ../wt2 feature/auth # ❌ 冲突！ +- 功能分支：wt-feature-- +- 缺陷修复：wt-bugfix-- +- 评审验证：wt-review- +- 紧急修复：wt-hotfix- -# ❌ 2. 不要忘记删除不用的工作树 -# 占用磁盘空间，容易混淆 +--- -# ❌ 3. 不要跨工作树共享 node_modules、build 目录 -# 创建 .gitignore 防止提交 -echo "node_modules/" >> ../.gitignore -echo "dist/" >> ../.gitignore -echo ".next/" >> ../.gitignore +## 团队标准流程（SOP） -# ❌ 4. 不要在工作树中改变 git 配置 -# 所有工作树共享 .git/config -``` +### 场景 1：AI 功能开发（Vibe Coding 标准流） ---- - -## 🛠️ 团队配置建议 +```bash +git fetch origin +git worktree add -b feature/123-login ../wt-feature-123 origin/main +cd ../wt-feature-123 +pnpm install -### 1. 项目根目录结构规划 +# 创建任务上下文文件，给 AI 看 +echo "## 任务：实现登录功能\n- 接口：POST /api/login\n- 相关文件：src/auth/" > TASK.md +# 用 Cursor 或 VS Code 打开，开始 AI 对话 +cursor . ``` -project-repo/ -├── .git/ -├── .gitignore # 包含: node_modules, dist, .env 等 -├── .worktree-setup.sh # 工作树设置脚本 -├── src/ -└── README.md - -# 创建工作树目录（与仓库目录同级） -../wt-main/ -../wt-develop/ -../wt-feature-xxx/ -``` -### 2. 团队规范文档 +### 场景 2：线上热修复（不中断 AI 开发窗口） + +```bash +git fetch origin +git worktree add -b hotfix/789-payment ../wt-hotfix-789 origin/main +cd ../wt-hotfix-789 +pnpm install +pnpm test +# 在新窗口打开，原有 AI 对话不受影响 +cursor . +``` -```markdown -## 工作树命名规范 -- 功能分支: wt-feature-{JIRA_ID}-{简短描述} -- 修复分支: wt-bugfix-{JIRA_ID}-{简短描述} -- 发布分支: wt-release-{版本号} -- 临时分支: wt-temp-{用途}-{创建日期} +### 场景 3：本地评审同事分支（AI 辅助 Review） -## 生命周期 -1. 创建: git worktree add -2. 开发: 在工作树中正常开发 -3. 提交: git commit, git push -4. 删除: git worktree remove +```bash +git fetch origin +git worktree add ../wt-review-checkout origin/feature/checkout +cd ../wt-review-checkout +pnpm install +pnpm test +# 让 AI 帮你 review：在 Copilot Chat 中问 "这个 PR 改了什么，有什么风险？" ``` -### 3. VS Code 工作区配置 (vscode-workspace) - -```json -{ - "folders": [ - { - "path": "../wt-main", - "name": "🔵 Main Branch" - }, - { - "path": "../wt-develop", - "name": "🟢 Develop Branch" - }, - { - "path": "../wt-feature-123", - "name": "🟡 Feature Auth" - } - ], - "settings": { - "files.exclude": { - "node_modules": true, - "dist": true, - ".next": true - } - } -} +### 场景结束清理 + +```bash +cd ../repo +git worktree remove ../wt-review-checkout +git worktree prune ``` --- -## ⚡ 高级技巧 +## VS Code / Cursor 集成建议 -### 1. 自动化工作树管理脚本 +1. **一任务一窗口**：每个工作树用独立 IDE 窗口打开（`code ` / `cursor `），AI 聊天历史互不干扰。 +2. **多根工作区**：如需总览，可用 VS Code 多根工作区把主仓库和常用工作树一起显示。 +3. **独立端口与环境变量**：每个工作树的 `.env.local` 配置不同端口，避免 dev server 冲突。 +4. **终端标题标明分支**：在 Shell 提示符中显示分支名，避免在错误目录执行 AI 生成的命令。 +5. **操作前确认位置**：大型 AI 改动前先执行 `git worktree list`，确认自己在目标工作树。 -```bash -#!/bin/bash -# worktree-manager.sh - -case "$1" in - create) - TYPE=$2 - ISSUE_ID=$3 - DESC=$4 - git worktree add -b "$TYPE/$ISSUE_ID-$DESC" "../wt-$TYPE-$ISSUE_ID" - echo "✅ 创建工作树: ../wt-$TYPE-$ISSUE_ID" - ;; - list) - git worktree list --porcelain - ;; - clean) - git worktree prune - echo "✅ 清理完成" - ;; - *) - echo "用法: $0 {create|list|clean}" - ;; -esac - -# 使用方式 -# ./worktree-manager.sh create feature 123 user-auth -# ./worktree-manager.sh list -# ./worktree-manager.sh clean -``` +--- -### 2. Git 别名快捷方式 +## Do / Don’t -```bash -# 在 ~/.gitconfig 中添加 -[alias] - wtadd = worktree add - wtlist = worktree list --porcelain - wtremove = worktree remove - wtprune = worktree prune - wtlock = worktree lock - wtunlock = worktree unlock - -# 使用 -git wtadd ../wt-feature-1 -b feature/auth -git wtlist -``` +### Do -### 3. 与 CI/CD 集成 - -```yaml -# GitHub Actions 示例 -name: Multi-Branch Testing - -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - branch: [main, develop, staging] - steps: - - uses: actions/checkout@v3 - with: - ref: ${{ matrix.branch }} - - name: Run tests - run: | - npm install - npm test -``` +- 每个任务一个独立工作树，对应一个 AI 对话窗口。 +- 在工作树根目录放 `TASK.md`，给 AI 提供清晰的任务上下文。 +- 分支名与 issue 号绑定，AI 生成提交信息时自动关联任务。 +- 任务结束后及时 remove + prune，保持目录整洁。 +- 在创建前先 `git fetch`，保证起点分支最新。 + +### Don’t + +- 不要在多个工作树同时检出同一分支（Git 会报错）。 +- 不要在同一 IDE 窗口来回切换工作树目录，会污染 AI 上下文。 +- 不要长期保留无人维护的临时工作树（AI 生成的代码积压更难清理）。 +- 不要在不确认目录时直接执行 AI 生成的提交/推送命令。 +- 不要把工作树路径写死到团队脚本中（改为参数化）。 --- -## 🐛 常见问题解决 +## 常见问题 -### Q1: 工作树被锁定，无法删除 -```bash -git worktree unlock /path/to/worktree -git worktree remove /path/to/worktree -``` +### Q1：提示分支已被其他工作树占用 -### Q2: 磁盘空间浪费，如何节省 -```bash -# 使用共享的 node_modules（不推荐） -# 或使用符号链接 -ln -s ../node_modules node_modules +原因：同一分支已在另一工作树检出。 -# 更好的方式：配置 npm 缓存 -npm install --cache-dir=../.npm-cache -``` +处理： -### Q3: IDE 编译冲突（如 Java、C++ 项目） ```bash -# 为每个工作树使用不同的 build 目录 -# CMakeLists.txt 示例 -set(CMAKE_BINARY_DIR "${PROJECT_SOURCE_DIR}/../build-${GIT_BRANCH}") +git worktree list +# 改用新分支，或先移除占用该分支的工作树 ``` -### Q4: 多人团队，如何同步工作树状态 +### Q2：工作树删除失败，提示有改动 + ```bash -# 创建 .git-worktrees.json 文件，共享配置 -{ - "active_worktrees": [ - { - "name": "wt-feature-123", - "branch": "feature/auth", - "owner": "alice", - "created_at": "2026-04-20" - } - ] -} - -# 定期同步 -git pull +git worktree remove -f ../wt-feature-123 git worktree prune ``` ---- +注意：-f 会丢弃该工作树未提交改动。 -## 📊 性能对比 +### Q3：目录已手动删除，列表仍显示 -| 操作 | 传统切换 | Git Worktree | -|------|---------|-------------| -| 分支切换 | 2-5秒 | 0秒（目录切换） | -| 编译缓存命中 | 否（重编） | 是（命中率 80%+） | -| 磁盘占用（含依赖） | ~500MB | ~1GB（多工作树） | -| 同步时间 | N/A | <100ms | - ---- +```bash +git worktree prune +``` -## 📋 Vibe Coding 工作流示例 +### Q4：如何降低依赖重复安装成本 -### 典型的一天 +建议优先使用包管理器缓存能力，而不是跨工作树硬链接依赖目录。 ```bash -# 🌅 早上 -cd ~/project -git worktree list # 查看现有工作树 - -# 🎯 处理新任务 -git worktree add -b feature/dashboard ../wt-dashboard -cd ../wt-dashboard -npm install # 仅需要一次 -npm run dev # 开发服务器运行 - -# 💬 收到 Code Review 反馈 -# 保持开发工作树继续运行 -cd ~/project -git worktree add feature/auth ../wt-review-auth -cd ../wt-review-auth # 检视同事代码 -# 无需关闭开发窗口，两个项目并行运行 - -# 🚨 线上紧急 Bug -git worktree add -b hotfix/payment ../wt-hotfix -cd ../wt-hotfix -npm run dev # 独立运行 -# 修复、测试、提交，然后删除 - -# 🌆 下午总结 -git worktree list -git worktree remove ../wt-review-auth -git worktree remove ../wt-hotfix -git worktree prune +pnpm config set store-dir ../.pnpm-store ``` --- -## 🎓 学习资源 +## 跨平台命令提示 -- **官方文档**: `man git-worktree` 或 `git worktree --help` -- **Git 官方**: https://git-scm.com/docs/git-worktree -- **案例集**: 在团队 Confluence 中创建工作树使用案例库 +### 删除目录 ---- +- macOS/Linux：rm -rf ../wt-feature-123 +- PowerShell：Remove-Item -Recurse -Force ..\wt-feature-123 -## 📞 技术支持 +优先使用 git worktree remove，而不是直接删目录。 -遇到问题？ +### 查看帮助 -1. **检查状态**: `git worktree list --verbose` -2. **清理环境**: `git worktree prune` -3. **查看日志**: `cd .git && grep -r "worktree" logs/` -4. **联系技术负责人**: 在团队 Slack 中 @tech-lead +- 通用：git worktree --help --- -## 📝 更新日志 +## 可复制的团队别名 + +在 Git 全局配置中加入： + +```ini +[alias] + wtls = worktree list --verbose + wtpr = worktree prune + wtadd = worktree add + wtrm = worktree remove +``` -| 版本 | 日期 | 变更 | -|------|------|------| -| v1.0 | 2026-04-26 | 初始版本发布 | -| - | - | 包含基础用法、最佳实践、高级技巧 | +使用示例： + +```bash +git wtls +git wtadd -b feature/321-search ../wt-feature-321 origin/main +git wtrm ../wt-feature-321 +git wtpr +``` --- -**最后更新**: 2026 年 4 月 26 日 -**维护人**: 技术团队 -**欢迎反馈和改进意见！** +## 维护信息 + +- 文档版本：v3.0 +- 更新日期：2026-04-26 +- 适用背景：Vibe Coding / AI 辅助开发团队 +- 维护建议：每次 AI 工具或团队流程变化后，同步更新本指南 From e97a22c3195352c1d7e4158d3ad53dce32f28d25 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Sun, 26 Apr 2026 22:14:21 +0800 Subject: [PATCH 5/8] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20Git=20Worktree?= =?UTF-8?q?=20=E5=9B=A2=E9=98=9F=E5=8D=8F=E4=BD=9C=E6=8C=87=E5=8D=97?= =?UTF-8?q?=EF=BC=8C=E4=BC=98=E5=8C=96=E5=86=85=E5=AE=B9=E7=BB=93=E6=9E=84?= =?UTF-8?q?=E4=B8=8E=E5=91=BD=E4=BB=A4=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot --- GIT_WORKTREE_GUIDE.md | 485 +++++++++++++----------------------------- 1 file changed, 147 insertions(+), 338 deletions(-) diff --git a/GIT_WORKTREE_GUIDE.md b/GIT_WORKTREE_GUIDE.md index 0d344c9..fb44f07 100644 --- a/GIT_WORKTREE_GUIDE.md +++ b/GIT_WORKTREE_GUIDE.md @@ -1,444 +1,253 @@ # Git Worktree 团队协作指南 -## 🎯 核心价值 +## 目标 -Git Worktree 让你**同时在多个分支工作，无需频繁切换**，极大提升团队开发效率。特别适合 Vibe Coding（流畅编码体验）的开发模式。 +Git Worktree 让团队可以在同一个仓库中并行处理多个分支，减少频繁切分支、stash/pop、重新编译带来的成本。 + +适用场景： + +- 功能开发与紧急修复并行 +- Code Review 与本地开发并行 +- 多任务切换频繁的日常研发 --- -## 📚 什么是 Git Worktree？ +## 什么是 Git Worktree -Git Worktree 是 Git 的一个强大功能，允许你在同一个仓库中维护**多个独立的工作目录**，每个目录可以关联到不同的分支。 +Git Worktree 允许一个仓库在多个目录中同时检出不同分支。所有工作树共享同一份 Git 对象库，但每个工作树有自己的工作目录内容。 -### 关键对比 +对比传统切分支： -| 方面 | 传统切换分支 | Git Worktree | -|------|----------|------------| -| 切换分支耗时 | 重新加载所有文件 | 立即切换目录 | -| 同时修改多分支 | ❌ 需要stash/切换 | ✅ 并行开发 | -| 编译缓存 | 丢失（重编） | 保留（不同目录） | -| IDE 配置 | 共享（易冲突） | 独立（互不影响） | +| 方面 | 传统切分支 | Git Worktree | +|---|---|---| +| 多任务并行 | 需要频繁切换 | 可多目录并行 | +| stash 依赖 | 常见 | 大幅减少 | +| IDE/终端会话 | 经常被打断 | 可长期保留 | +| 心智负担 | 高 | 低 | --- -## 🚀 快速开始 +## 核心命令速查 -### 基础命令 +### 1) 创建工作树 -#### 1. 创建新工作树 ```bash -# 基于当前分支创建工作树 -git worktree add ../worktree-branch-name +# 在当前 HEAD 基础上创建工作树（分支与当前一致） +git worktree add ../wt-task-a + +# 基于已有分支创建工作树 +git worktree add ../wt-review feature/checkout -# 基于特定分支创建工作树 -git worktree add ../worktree-feature /path/to/branch-name +# 创建新分支并创建工作树（推荐团队开发常用） +git worktree add -b feature/123-login ../wt-feature-123 main +``` + +命令格式说明： -# 创建并同时创建新分支 -git worktree add -b feature-new ../worktree-feature +```text +git worktree add [-b ] [] ``` -#### 2. 列出所有工作树 +### 2) 查看工作树 + ```bash git worktree list -git worktree list --verbose # 显示详细信息 +git worktree list --verbose ``` -#### 3. 删除工作树 +### 3) 删除工作树 + ```bash -# 强制删除工作树 -git worktree remove ../worktree-feature +# 正常删除 +git worktree remove ../wt-feature-123 -# 或者先手动删除目录，再清理 -rm -rf ../worktree-feature +# 若存在未提交改动，使用 -f 强制删除 +git worktree remove -f ../wt-feature-123 + +# 清理已失效记录 git worktree prune ``` -#### 4. 修复损坏的工作树 +### 4) 锁定与解锁 + ```bash -git worktree lock ../worktree-feature --reason "备份中" -git worktree unlock ../worktree-feature +git worktree lock ../wt-release --reason "release freeze" +git worktree unlock ../wt-release ``` --- -## 💼 团队实战场景 +## 推荐目录规划 -### 场景 1: 并行开发多个功能分支 +建议将工作树放在仓库同级目录，统一以 wt- 前缀命名。 -```bash -# 主工作树：处理 main 分支 -cd ~/project +```text +repo/ + .git/ + src/ + package.json -# 创建第一个功能分支工作树 -git worktree add ../wt-feature-login -b feature/login +../wt-feature-123-login/ +../wt-bugfix-456-crash/ +../wt-review-checkout/ +``` -# 创建第二个功能分支工作树 -git worktree add ../wt-feature-payment -b feature/payment +命名建议： -# 创建测试修复工作树 -git worktree add ../wt-bugfix-auth -b bugfix/auth-issue +- 功能分支：wt-feature-- +- 缺陷修复：wt-bugfix-- +- 评审验证：wt-review- +- 紧急修复：wt-hotfix- -# 现在可以并行开发，互不干扰 -``` +--- -**文件结构：** -``` -project/ - ├── .git/ # 共享 git 仓库 - ├── src/ - ├── package.json - └── (主工作树内容) - -wt-feature-login/ - ├── src/ - ├── package.json - └── (feature/login 分支内容) - -wt-feature-payment/ - ├── src/ - ├── package.json - └── (feature/payment 分支内容) -``` +## 团队标准流程（SOP） -### 场景 2: 紧急修复 + 功能开发 +### 场景 1：功能开发 ```bash -# 正在开发 feature/user-dashboard 分支 -# 突然需要修复线上 bug - -# ✅ 创建新工作树修复 bug（基于 main） -git worktree add ../wt-hotfix -b hotfix/critical-bug - -# 修复完成后直接提交、测试、部署 -# 原工作树继续开发，无需 stash/pop +git fetch origin +git worktree add -b feature/123-login ../wt-feature-123 origin/main +cd ../wt-feature-123 +pnpm install +pnpm dev ``` -### 场景 3: Code Review + 功能开发 +### 场景 2：线上热修复（不中断当前开发） ```bash -# 需要检视同事的 PR（feature/checkout） -git worktree add ../wt-review feature/checkout - -# 一边测试同事代码，一边开发自己的功能 -# 完成后直接删除 review 工作树 -git worktree remove ../wt-review +git fetch origin +git worktree add -b hotfix/789-payment ../wt-hotfix-789 origin/main +cd ../wt-hotfix-789 +pnpm install +pnpm test ``` ---- - -## 🎨 最佳实践（Vibe Coding 友好） - -### ✅ DO（推荐做法） +### 场景 3：本地评审同事分支 ```bash -# 1. 统一的命名规范 -git worktree add ../wt-feature-- -git worktree add ../wt-feature-123-user-auth -git worktree add ../wt-bugfix-456-login-crash - -# 2. 创建包含所有 worktree 的快捷脚本 (创建 .worktree-setup.sh) -#!/bin/bash -# 快速创建常用工作树 -git worktree add -b develop ../wt-develop develop -git worktree add -b staging ../wt-staging staging -git worktree add -b feature-1 ../wt-feature-1 feature-1 - -# 3. 在 VS Code 中使用工作区功能 -# File > Add Folder to Workspace -# 添加 wt-feature-xxx 目录，同时编辑多个分支 - -# 4. 定期清理已删除的分支 -git worktree prune - -# 5. 在 IDE 中配置不同工作树的执行配置 -# 避免冲突（不同端口、不同调试器等） +git fetch origin +git worktree add ../wt-review-checkout origin/feature/checkout +cd ../wt-review-checkout +pnpm install +pnpm test ``` -### ❌ DON'T（避免做法） +### 场景结束清理 ```bash -# ❌ 1. 不要在多个工作树中操作同一分支 -git worktree add ../wt1 feature/auth -git worktree add ../wt2 feature/auth # ❌ 冲突！ +cd ../repo +git worktree remove ../wt-review-checkout +git worktree prune +``` -# ❌ 2. 不要忘记删除不用的工作树 -# 占用磁盘空间，容易混淆 +--- -# ❌ 3. 不要跨工作树共享 node_modules、build 目录 -# 创建 .gitignore 防止提交 -echo "node_modules/" >> ../.gitignore -echo "dist/" >> ../.gitignore -echo ".next/" >> ../.gitignore +## VS Code 协作建议 -# ❌ 4. 不要在工作树中改变 git 配置 -# 所有工作树共享 .git/config -``` +1. 使用多根工作区把主仓库和常用工作树一起打开。 +2. 给每个工作树单独分配端口、调试配置和环境变量。 +3. 在终端标题中标明分支名，避免在错误目录执行命令。 +4. 大型改动前先执行 git worktree list，确认自己在目标工作树。 --- -## 🛠️ 团队配置建议 +## Do / Don’t -### 1. 项目根目录结构规划 +### Do -``` -project-repo/ -├── .git/ -├── .gitignore # 包含: node_modules, dist, .env 等 -├── .worktree-setup.sh # 工作树设置脚本 -├── src/ -└── README.md - -# 创建工作树目录（与仓库目录同级） -../wt-main/ -../wt-develop/ -../wt-feature-xxx/ -``` +- 每个任务一个独立工作树。 +- 分支名与任务号绑定，便于追踪。 +- 任务结束后及时 remove + prune。 +- 在创建前先 git fetch，保证起点分支最新。 -### 2. 团队规范文档 +### Don’t -```markdown -## 工作树命名规范 -- 功能分支: wt-feature-{JIRA_ID}-{简短描述} -- 修复分支: wt-bugfix-{JIRA_ID}-{简短描述} -- 发布分支: wt-release-{版本号} -- 临时分支: wt-temp-{用途}-{创建日期} +- 不要在多个工作树同时检出同一分支。 +- 不要长期保留无人维护的临时工作树。 +- 不要在不确认目录时直接提交或推送。 +- 不要把工作树路径写死到团队脚本中（改为参数化）。 -## 生命周期 -1. 创建: git worktree add -2. 开发: 在工作树中正常开发 -3. 提交: git commit, git push -4. 删除: git worktree remove -``` +--- -### 3. VS Code 工作区配置 (vscode-workspace) - -```json -{ - "folders": [ - { - "path": "../wt-main", - "name": "🔵 Main Branch" - }, - { - "path": "../wt-develop", - "name": "🟢 Develop Branch" - }, - { - "path": "../wt-feature-123", - "name": "🟡 Feature Auth" - } - ], - "settings": { - "files.exclude": { - "node_modules": true, - "dist": true, - ".next": true - } - } -} -``` +## 常见问题 ---- +### Q1：提示分支已被其他工作树占用 -## ⚡ 高级技巧 +原因：同一分支已在另一工作树检出。 -### 1. 自动化工作树管理脚本 +处理： ```bash -#!/bin/bash -# worktree-manager.sh - -case "$1" in - create) - TYPE=$2 - ISSUE_ID=$3 - DESC=$4 - git worktree add -b "$TYPE/$ISSUE_ID-$DESC" "../wt-$TYPE-$ISSUE_ID" - echo "✅ 创建工作树: ../wt-$TYPE-$ISSUE_ID" - ;; - list) - git worktree list --porcelain - ;; - clean) - git worktree prune - echo "✅ 清理完成" - ;; - *) - echo "用法: $0 {create|list|clean}" - ;; -esac - -# 使用方式 -# ./worktree-manager.sh create feature 123 user-auth -# ./worktree-manager.sh list -# ./worktree-manager.sh clean +git worktree list +# 改用新分支，或先移除占用该分支的工作树 ``` -### 2. Git 别名快捷方式 +### Q2：工作树删除失败，提示有改动 ```bash -# 在 ~/.gitconfig 中添加 -[alias] - wtadd = worktree add - wtlist = worktree list --porcelain - wtremove = worktree remove - wtprune = worktree prune - wtlock = worktree lock - wtunlock = worktree unlock - -# 使用 -git wtadd ../wt-feature-1 -b feature/auth -git wtlist -``` - -### 3. 与 CI/CD 集成 - -```yaml -# GitHub Actions 示例 -name: Multi-Branch Testing - -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - branch: [main, develop, staging] - steps: - - uses: actions/checkout@v3 - with: - ref: ${{ matrix.branch }} - - name: Run tests - run: | - npm install - npm test +git worktree remove -f ../wt-feature-123 +git worktree prune ``` ---- +注意：-f 会丢弃该工作树未提交改动。 -## 🐛 常见问题解决 +### Q3：目录已手动删除，列表仍显示 -### Q1: 工作树被锁定，无法删除 ```bash -git worktree unlock /path/to/worktree -git worktree remove /path/to/worktree +git worktree prune ``` -### Q2: 磁盘空间浪费，如何节省 -```bash -# 使用共享的 node_modules（不推荐） -# 或使用符号链接 -ln -s ../node_modules node_modules +### Q4：如何降低依赖重复安装成本 -# 更好的方式：配置 npm 缓存 -npm install --cache-dir=../.npm-cache -``` +建议优先使用包管理器缓存能力，而不是跨工作树硬链接依赖目录。 -### Q3: IDE 编译冲突（如 Java、C++ 项目） ```bash -# 为每个工作树使用不同的 build 目录 -# CMakeLists.txt 示例 -set(CMAKE_BINARY_DIR "${PROJECT_SOURCE_DIR}/../build-${GIT_BRANCH}") -``` - -### Q4: 多人团队，如何同步工作树状态 -```bash -# 创建 .git-worktrees.json 文件，共享配置 -{ - "active_worktrees": [ - { - "name": "wt-feature-123", - "branch": "feature/auth", - "owner": "alice", - "created_at": "2026-04-20" - } - ] -} - -# 定期同步 -git pull -git worktree prune +pnpm config set store-dir ../.pnpm-store ``` --- -## 📊 性能对比 +## 跨平台命令提示 -| 操作 | 传统切换 | Git Worktree | -|------|---------|-------------| -| 分支切换 | 2-5秒 | 0秒（目录切换） | -| 编译缓存命中 | 否（重编） | 是（命中率 80%+） | -| 磁盘占用（含依赖） | ~500MB | ~1GB（多工作树） | -| 同步时间 | N/A | <100ms | +### 删除目录 ---- +- macOS/Linux：rm -rf ../wt-feature-123 +- PowerShell：Remove-Item -Recurse -Force ..\wt-feature-123 -## 📋 Vibe Coding 工作流示例 +优先使用 git worktree remove，而不是直接删目录。 -### 典型的一天 +### 查看帮助 -```bash -# 🌅 早上 -cd ~/project -git worktree list # 查看现有工作树 - -# 🎯 处理新任务 -git worktree add -b feature/dashboard ../wt-dashboard -cd ../wt-dashboard -npm install # 仅需要一次 -npm run dev # 开发服务器运行 - -# 💬 收到 Code Review 反馈 -# 保持开发工作树继续运行 -cd ~/project -git worktree add feature/auth ../wt-review-auth -cd ../wt-review-auth # 检视同事代码 -# 无需关闭开发窗口，两个项目并行运行 - -# 🚨 线上紧急 Bug -git worktree add -b hotfix/payment ../wt-hotfix -cd ../wt-hotfix -npm run dev # 独立运行 -# 修复、测试、提交，然后删除 - -# 🌆 下午总结 -git worktree list -git worktree remove ../wt-review-auth -git worktree remove ../wt-hotfix -git worktree prune -``` +- 通用：git worktree --help --- -## 🎓 学习资源 +## 可复制的团队别名 -- **官方文档**: `man git-worktree` 或 `git worktree --help` -- **Git 官方**: https://git-scm.com/docs/git-worktree -- **案例集**: 在团队 Confluence 中创建工作树使用案例库 - ---- +在 Git 全局配置中加入： -## 📞 技术支持 +```ini +[alias] + wtls = worktree list --verbose + wtpr = worktree prune + wtadd = worktree add + wtrm = worktree remove +``` -遇到问题？ +使用示例： -1. **检查状态**: `git worktree list --verbose` -2. **清理环境**: `git worktree prune` -3. **查看日志**: `cd .git && grep -r "worktree" logs/` -4. **联系技术负责人**: 在团队 Slack 中 @tech-lead +```bash +git wtls +git wtadd -b feature/321-search ../wt-feature-321 origin/main +git wtrm ../wt-feature-321 +git wtpr +``` --- -## 📝 更新日志 - -| 版本 | 日期 | 变更 | -|------|------|------| -| v1.0 | 2026-04-26 | 初始版本发布 | -| - | - | 包含基础用法、最佳实践、高级技巧 | - ---- +## 维护信息 -**最后更新**: 2026 年 4 月 26 日 -**维护人**: 技术团队 -**欢迎反馈和改进意见！** +- 文档版本：v2.0 +- 更新日期：2026-04-26 +- 维护建议：每次团队流程变化后，同步更新本指南 From 5ec805a47227319dd9185f3986f2efa3ea31e7f7 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Sun, 26 Apr 2026 22:54:55 +0800 Subject: [PATCH 6/8] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20Git=20Worktree?= =?UTF-8?q?=20=E5=9B=A2=E9=98=9F=E5=8D=8F=E4=BD=9C=E6=8C=87=E5=8D=97?= =?UTF-8?q?=EF=BC=8C=E8=81=9A=E7=84=A6=20Vibe=20Coding=20=E5=9C=BA?= =?UTF-8?q?=E6=99=AF=E4=B8=8E=20AI=20=E6=8F=90=E7=A4=BA=E8=AF=8D=E6=A8=A1?= =?UTF-8?q?=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot --- GIT_WORKTREE_GUIDE.md | 672 ++++++++++++++++++++++-------------------- 1 file changed, 350 insertions(+), 322 deletions(-) diff --git a/GIT_WORKTREE_GUIDE.md b/GIT_WORKTREE_GUIDE.md index 45d6689..827d153 100644 --- a/GIT_WORKTREE_GUIDE.md +++ b/GIT_WORKTREE_GUIDE.md @@ -1,417 +1,406 @@ -# Git Worktree 团队协作指南 +# Vibe Coding 下的 Git Worktree 实战 -## 🎯 核心价值 - -Git Worktree 让你**同时在多个分支工作，无需频繁切换**，极大提升团队开发效率。特别适合 Vibe Coding（流畅编码体验）的开发模式。 +> 在 AI 辅助开发背景下，如何用 Git Worktree 真正提升团队交付效率 --- -## 什么是 Git Worktree +## 先说痛点 + +你有没有遇到过这种情况： + +正在用 AI 高速推进一个功能，代码写到一半，忽然来了一个 Hotfix 需求或者 Code Review 请求。 -Git Worktree 是 Git 的一个强大功能，允许你在同一个仓库中维护**多个独立的工作目录**，每个目录可以关联到不同的分支。 +然后你不得不： -### 关键对比 +```bash +git stash save "WIP: new dashboard" +git checkout main +git checkout -b hotfix/login-bug +# ... 修复 ... +git push origin hotfix/login-bug +git checkout feature/new-dashboard +git stash pop +# 哎呀，stash pop 有冲突... +``` -| 方面 | 传统切换分支 | Git Worktree | -|------|----------|------------| -| 切换分支耗时 | 重新加载所有文件 | 立即切换目录 | -| 同时修改多分支 | ❌ 需要stash/切换 | ✅ 并行开发 | -| 编译缓存 | 丢失（重编） | 保留（不同目录） | -| IDE 配置 | 共享（易冲突） | 独立（互不影响） | +每次切换，AI 对话的上下文要重新建立，dev server 要重启，构建缓存失效。原本高速运转的开发节奏，就这样被打断了。 + +这就是 Vibe Coding 场景下，传统分支管理方式的核心问题：**AI 让你更频繁地需要切换任务，但切换本身的成本并没有降低。** --- -## 🚀 快速开始 +## 什么是 Git Worktree -### 基础命令 +Git Worktree 允许你在同一个仓库上创建多个独立工作目录，每个目录对应一个分支。 + +可以把它理解成： + +- 同一套 `.git` 仓库，同一段提交历史 +- 但可以同时拥有多个独立的"工作现场" -#### 1. 创建新工作树 ```bash -# 基于当前分支创建工作树 -git worktree add ../worktree-branch-name +cd ~/project -# 基于特定分支创建工作树 -git worktree add ../worktree-feature /path/to/branch-name +# 为新功能创建独立工作树 +git worktree add -b feature/123-login ../wt-feature-123-login main -# 创建并同时创建新分支 -git worktree add -b feature-new ../worktree-feature +# 为紧急修复创建另一个工作树 +git worktree add -b hotfix/login-bug ../wt-hotfix-login-bug main ``` -#### 2. 列出所有工作树 -```bash -git worktree list -git worktree list --verbose # 显示详细信息 -``` +结果： -#### 3. 删除工作树 -```bash -# 强制删除工作树 -git worktree remove ../worktree-feature +```text +project/ ← .git 在这里，所有工作树共享 + ├── .git/ + └── src/ + +wt-feature-123-login/ ← 对应 feature/123-login 分支 + └── src/ -# 或者先手动删除目录，再清理 -rm -rf ../worktree-feature -git worktree prune +wt-hotfix-login-bug/ ← 对应 hotfix/login-bug 分支 + └── src/ ``` -#### 4. 修复损坏的工作树 +现在你可以同时在三个目录里工作，互不干扰，每个目录都有独立的终端、运行状态和 AI 对话上下文。 + +还是刚才那个场景，换成 Worktree 方式： + ```bash -git worktree lock ../worktree-feature --reason "备份中" -git worktree unlock ../worktree-feature +# 不需要 stash，不需要切分支 +# 直接创建一个新的工作树处理 hotfix +git worktree add -b hotfix/login-bug ../wt-hotfix-login-bug main +cd ../wt-hotfix-login-bug + +# 修复、测试、提交 +git commit -am "Fix: login timeout bug" +git push origin hotfix/login-bug + +# 删除 worktree，回到原来的目录 +git worktree remove ../wt-hotfix-login-bug +cd ~/project +# feature/new-dashboard 分支完全没动，所有改动都在，AI 对话也还在 ``` --- -## 💼 团队实战场景 +## 为什么 Vibe Coding 更需要它 -### 场景 1: 并行开发多个功能分支 +Vibe Coding 的本质是：**开发者和 AI 高频协作，让"实现"这一步变得更快、更连续。** -```bash -# 主工作树：处理 main 分支 -cd ~/project +但 AI 带来的副作用也很明显：你会更频繁地同时推进多件事，并且更依赖 IDE 内的聊天上下文和运行状态。 -# 创建第一个功能分支工作树 -git worktree add ../wt-feature-login -b feature/login +对比一下： -# 创建第二个功能分支工作树 -git worktree add ../wt-feature-payment -b feature/payment +| 维度 | 传统切分支 | Git Worktree | Worktree + AI | +|------|-----------|--------------|---------------| +| 紧急 Hotfix 处理 | stash → 切换 → 修复 → 切回 → pop | 新开目录，互不干扰 | 新开目录 + 独立 AI 对话，上下文不串 | +| Code Review + 开发并行 | 容易互相覆盖 | 隔离目录 | 隔离目录 + AI 分别辅助 | +| dev server | 切换后要重启 | 可同时运行多个 | 可同时运行，任务上下文稳定 | +| 构建缓存 | 切换后容易失效 | 各目录独立保留 | 稳定 | +| AI 对话上下文 | 容易串台 | 可按目录隔离 | 每个任务有独立干净的上下文 | +| 心智负担 | 高 | 中 | 最低 | -# 创建测试修复工作树 -git worktree add ../wt-bugfix-auth -b bugfix/auth-issue +核心逻辑只有一句： -# 现在可以并行开发，互不干扰 -``` +**AI 加速了任务产生的速度，Worktree 负责让这些任务互不干扰地并行推进。** -**文件结构：** -``` -project/ - ├── .git/ # 共享 git 仓库 - ├── src/ - ├── package.json - └── (主工作树内容) - -wt-feature-login/ - ├── src/ - ├── package.json - └── (feature/login 分支内容) - -wt-feature-payment/ - ├── src/ - ├── package.json - └── (feature/payment 分支内容) -``` +--- + +## 常用命令速查 -### 场景 2: 紧急修复 + 功能开发 +### 创建工作树 ```bash -# 正在开发 feature/user-dashboard 分支 -# 突然需要修复线上 bug +# 基于 main 创建新分支 + 新工作树 +git worktree add -b feature/123-login ../wt-feature-123-login main -# ✅ 创建新工作树修复 bug（基于 main） -git worktree add ../wt-hotfix -b hotfix/critical-bug +# 基于已有远程分支创建工作树（用于 review） +git worktree add ../wt-review-payment feature/payment -# 修复完成后直接提交、测试、部署 -# 原工作树继续开发，无需 stash/pop +# 基于 main 快速开 hotfix 工作树 +git worktree add -b hotfix/login-bug ../wt-hotfix-login-bug main ``` -### 场景 3: Code Review + 功能开发 +### 查看 / 清理 ```bash -# 需要检视同事的 PR（feature/checkout） -git worktree add ../wt-review feature/checkout +git worktree list # 查看所有工作树 +git worktree list --porcelain # 查看详细状态 -# 一边测试同事代码，一边开发自己的功能 -# 完成后直接删除 review 工作树 -git worktree remove ../wt-review +git worktree remove ../wt-review-payment # 删除工作树 +git worktree prune # 清理无效引用 ``` +### 一个重要限制 + +**同一个分支不能同时挂载到两个 worktree。** + +这不是缺陷，反而是一个保护机制——它强制你用"一个任务一个分支"的方式工作。 + --- -## 🎨 最佳实践（Vibe Coding 友好） +## 实战场景 -### ✅ DO（推荐做法） +### 场景一：Hotfix 不打断功能开发 + +**背景**：你正在 `feature/new-dashboard` 分支上用 AI 开发新功能，代码写到一半。产品找过来："线上登录功能挂了，马上修复！" + +**传统做法的问题**： ```bash -# 1. 统一的命名规范 -git worktree add ../wt-feature-- -git worktree add ../wt-feature-123-user-auth -git worktree add ../wt-bugfix-456-login-crash - -# 2. 创建包含所有 worktree 的快捷脚本 (创建 .worktree-setup.sh) -#!/bin/bash -# 快速创建常用工作树 -git worktree add -b develop ../wt-develop develop -git worktree add -b staging ../wt-staging staging -git worktree add -b feature-1 ../wt-feature-1 feature-1 - -# 3. 在 VS Code 中使用工作区功能 -# File > Add Folder to Workspace -# 添加 wt-feature-xxx 目录，同时编辑多个分支 - -# 4. 定期清理已删除的分支 -git worktree prune - -# 5. 在 IDE 中配置不同工作树的执行配置 -# 避免冲突（不同端口、不同调试器等） +git stash save "WIP: new dashboard" +git checkout main +git checkout -b hotfix/login-bug +# 修复完... +git checkout feature/new-dashboard +git stash pop +# 常常这一步就出冲突了 ``` -### ❌ DON'T（避免做法） +**Worktree 做法**： ```bash -# ❌ 1. 不要在多个工作树中操作同一分支 -git worktree add ../wt1 feature/auth -git worktree add ../wt2 feature/auth # ❌ 冲突！ +# 主工作目录完全不动，直接开一个新的 worktree +git worktree add -b hotfix/login-bug ../wt-hotfix-login-bug main +cd ../wt-hotfix-login-bug -# ❌ 2. 不要忘记删除不用的工作树 -# 占用磁盘空间，容易混淆 +# 在新窗口里打开这个目录，让 AI 帮你定位和修复 +# 修复完成后提交 +git commit -am "Fix: login timeout bug" +git push origin hotfix/login-bug -# ❌ 3. 不要跨工作树共享 node_modules、build 目录 -# 创建 .gitignore 防止提交 -echo "node_modules/" >> ../.gitignore -echo "dist/" >> ../.gitignore -echo ".next/" >> ../.gitignore +# 清理 +cd .. +git worktree remove wt-hotfix-login-bug -# ❌ 4. 不要在工作树中改变 git 配置 -# 所有工作树共享 .git/config +# 回到原来的目录，一切都还在原地 +cd ~/project +git status # 还是 feature/new-dashboard，所有改动都在 ``` +**AI 在这里的角色**：在 hotfix 的窗口里，你可以告诉 AI："我现在在一个专门用于修复登录超时的 worktree，帮我定位根因并给出最小修复方案，不要动其他逻辑。"这样 AI 的注意力不会被 dashboard 相关的文件和历史对话干扰。 + --- -## 🛠️ 团队配置建议 +### 场景二：Code Review 与开发并行 -### 1. 项目根目录结构规划 +**背景**：你需要 review 同事的支付分支 PR，但自己的功能开发也不能停。 -``` -project-repo/ -├── .git/ -├── .gitignore # 包含: node_modules, dist, .env 等 -├── .worktree-setup.sh # 工作树设置脚本 -├── src/ -└── README.md - -# 创建工作树目录（与仓库目录同级） -../wt-main/ -../wt-develop/ -../wt-feature-xxx/ +```bash +# 主工作树继续开发功能 +# 另开一个 worktree 专门用于 review +git worktree add ../wt-review-payment feature/payment + +cd ../wt-review-payment +npm install +npm run dev # 独立启动，不干扰你的功能开发端口 + +# review 完成后 +git worktree remove ../wt-review-payment ``` -### 2. 团队规范文档 +在 review 的窗口里，你可以让 AI："请先总结这个分支改了什么，然后找出潜在 bug 和回归风险，关注行为变化，不要做风格建议。" -```markdown -## 工作树命名规范 -- 功能分支: wt-feature-{JIRA_ID}-{简短描述} -- 修复分支: wt-bugfix-{JIRA_ID}-{简短描述} -- 发布分支: wt-release-{版本号} -- 临时分支: wt-temp-{用途}-{创建日期} +这比在同一个目录里切换分支 review 更干净，因为 dev server 是独立的，AI 的文件引用范围也是隔离的。 -## 生命周期 -1. 创建: git worktree add -2. 开发: 在工作树中正常开发 -3. 提交: git commit, git push -4. 删除: git worktree remove -``` +--- -### 3. VS Code 工作区配置 (vscode-workspace) +### 场景三：多版本并行维护 -```json -{ - "folders": [ - { - "path": "../wt-main", - "name": "🔵 Main Branch" - }, - { - "path": "../wt-develop", - "name": "🟢 Develop Branch" - }, - { - "path": "../wt-feature-123", - "name": "🟡 Feature Auth" - } - ], - "settings": { - "files.exclude": { - "node_modules": true, - "dist": true, - ".next": true - } - } -} +**背景**：项目有 v1.0 和 v2.0 两个版本同时维护，需要给两个版本都加一个功能。 + +```bash +# 为两个版本各建一个工作树 +git worktree add ../wt-v1.0 release/v1.0 +git worktree add ../wt-v2.0 release/v2.0 + +# 各自配置独立环境 +echo "API_URL=https://api-v1.example.com" > ../wt-v1.0/.env.local +echo "API_URL=https://api-v2.example.com" > ../wt-v2.0/.env.local + +# 分别启动（不同端口） +# Terminal 1: cd ../wt-v1.0 && npm run dev # 端口 3000 +# Terminal 2: cd ../wt-v2.0 && npm run dev # 端口 3001 + +# 分别在各自窗口提交 +cd ../wt-v1.0 && git commit -am "Add user profile (v1.0)" +cd ../wt-v2.0 && git commit -am "Add user profile (v2.0)" ``` +在每个版本的窗口里，AI 的文件上下文、.env 配置和 dev server 都是独立的，不会互相干扰。 + --- -## ⚡ 高级技巧 +### 场景四：AI 驱动的方案 A/B 实验 -### 1. 自动化工作树管理脚本 +**背景**：有一个性能优化方向，不确定哪种方案更好，想让 AI 分别实现两套然后对比。 ```bash -#!/bin/bash -# worktree-manager.sh - -case "$1" in - create) - TYPE=$2 - ISSUE_ID=$3 - DESC=$4 - git worktree add -b "$TYPE/$ISSUE_ID-$DESC" "../wt-$TYPE-$ISSUE_ID" - echo "✅ 创建工作树: ../wt-$TYPE-$ISSUE_ID" - ;; - list) - git worktree list --porcelain - ;; - clean) - git worktree prune - echo "✅ 清理完成" - ;; - *) - echo "用法: $0 {create|list|clean}" - ;; -esac - -# 使用方式 -# ./worktree-manager.sh create feature 123 user-auth -# ./worktree-manager.sh list -# ./worktree-manager.sh clean +# 开两个实验性 worktree +git worktree add -b spike/search-v1 ../wt-spike-search-v1 main +git worktree add -b spike/search-v2 ../wt-spike-search-v2 main + +# 在 wt-spike-search-v1 窗口里让 AI 实现方案 A +# 在 wt-spike-search-v2 窗口里让 AI 实现方案 B + +# 分别跑性能测试 +cd ../wt-spike-search-v1 && npm run benchmark # 150ms +cd ../wt-spike-search-v2 && npm run benchmark # 120ms + +# 选方案 B，废弃方案 A +cd ~/project +git merge spike/search-v2 +git worktree remove ../wt-spike-search-v1 +git worktree remove ../wt-spike-search-v2 ``` -### 2. Git 别名快捷方式 +两个 worktree 同时存在，AI 在各自窗口独立工作，最后直接对比结果。失败的方案删目录即可，主仓库完全不受影响。 -```bash -# 在 ~/.gitconfig 中添加 -[alias] - wtadd = worktree add - wtlist = worktree list --porcelain - wtremove = worktree remove - wtprune = worktree prune - wtlock = worktree lock - wtunlock = worktree unlock - -# 使用 -git wtadd ../wt-feature-1 -b feature/auth -git wtlist +--- + +## AI 提示词模板 + +下面这些提示词可以直接在 VS Code Copilot、Cursor 或其他 AI 工具中使用。核心思路是：**告诉 AI 当前 worktree 的角色和边界，让它不要越界。** + +### 功能开发 + +```text +你现在在一个 git worktree 中工作，这个目录只负责当前功能，不处理其他任务。 + +目标：实现 <功能名称>。 +上下文：先阅读相关代码、接口和已有组件，再给出最小改动方案并直接修改代码。 + +要求： +1. 只修改和当前功能直接相关的文件。 +2. 优先复用现有实现，不重复造轮子。 +3. 不要顺手重构无关代码。 +4. 修改后说明最小验证步骤。 +5. 最后给出风险点和测试建议。 ``` -### 3. 与 CI/CD 集成 - -```yaml -# GitHub Actions 示例 -name: Multi-Branch Testing - -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - branch: [main, develop, staging] - steps: - - uses: actions/checkout@v3 - with: - ref: ${{ matrix.branch }} - - name: Run tests - run: | - npm install - npm test +### Code Review / 分支验证 + +```text +你现在在一个 review 用的 git worktree 中工作，目标是评估这个分支的变更质量，而不是继续开发新功能。 + +请按下面顺序处理： +1. 先总结这个分支改了什么。 +2. 找出潜在 bug、回归风险和边界情况。 +3. 指出是否缺少测试或验证步骤。 +4. 如果需要修改，只做最小修复并解释原因。 + +要求：关注行为变化，不要只做代码风格建议。 ``` ---- +### Hotfix -## 🐛 常见问题解决 +```text +你现在在一个 hotfix 用的 git worktree 中工作。 -### Q1: 工作树被锁定，无法删除 -```bash -git worktree unlock /path/to/worktree -git worktree remove /path/to/worktree +目标：定位并修复 <问题描述>，优先保证快速、可验证、低风险上线。 + +请按下面顺序处理： +1. 根据现有代码推断最可能的根因。 +2. 给出最小修复方案。 +3. 说明这次修复不会扩大影响面的理由。 +4. 修改后列出必须执行的验证步骤。 + +要求：不要引入大范围重构，不要顺手优化无关逻辑。 ``` -### Q2: 磁盘空间浪费，如何节省 -```bash -# 使用共享的 node_modules（不推荐） -# 或使用符号链接 -ln -s ../node_modules node_modules +### 实验性方案 / Spike + +```text +你现在在一个实验性 worktree 中工作，目标是验证 <方案描述> 是否值得推进。 + +请先做以下事情： +1. 总结当前实现的问题。 +2. 给出最小可验证的实现切口。 +3. 说明收益、风险和回滚成本。 +4. 只实现最小原型，不要一次性铺开。 -# 更好的方式：配置 npm 缓存 -npm install --cache-dir=../.npm-cache +这是实验分支，失败了直接删目录，不影响主干。 ``` -### Q3: IDE 编译冲突（如 Java、C++ 项目） +--- + +## 在 VS Code 和 Cursor 中怎么用 + +这部分只简单带一下，重点是用法，不是工具介绍。 + +### VS Code + +最推荐的方式是**一个 worktree 开一个独立窗口**： + ```bash -# 为每个工作树使用不同的 build 目录 -# CMakeLists.txt 示例 -set(CMAKE_BINARY_DIR "${PROJECT_SOURCE_DIR}/../build-${GIT_BRANCH}") +cd ../wt-feature-123-login +code . # 独立窗口，独立终端，独立 Copilot 对话 ``` -### Q4: 多人团队，如何同步工作树状态 -```bash -# 创建 .git-worktrees.json 文件，共享配置 +如果需要同时观察多个分支，可以用 `File → Add Folder to Workspace` 把多个 worktree 加进同一个 Multi-Root Workspace： + +```json { - "active_worktrees": [ - { - "name": "wt-feature-123", - "branch": "feature/auth", - "owner": "alice", - "created_at": "2026-04-20" - } + "folders": [ + { "path": "../project-repo", "name": "Main" }, + { "path": "../wt-feature-123-login", "name": "Feature 123" }, + { "path": "../wt-review-payment", "name": "Review Payment" } ] } - -# 定期同步 -git pull -git worktree prune ``` ---- +注意：同一个 workspace 里的多个 worktree 共享同一个 Copilot 会话，AI 上下文不是完全隔离的。**需要 AI 专注于单一任务时，还是推荐独立窗口。** + +### Cursor + +Cursor 更推荐**一个 worktree 对应一个独立项目窗口**。 + +这样每个窗口的 Composer 历史、文件引用范围、`@codebase` 的索引范围都是独立的，AI 给出的建议不会混入其他任务的上下文。 -## 📊 性能对比 +一句话总结： -| 操作 | 传统切换 | Git Worktree | -|------|---------|-------------| -| 分支切换 | 2-5秒 | 0秒（目录切换） | -| 编译缓存命中 | 否（重编） | 是（命中率 80%+） | -| 磁盘占用（含依赖） | ~500MB | ~1GB（多工作树） | -| 同步时间 | N/A | <100ms | +**VS Code / Cursor 只是入口，关键是"一个任务一个目录，一个目录一个 AI 上下文"。** --- -## 📋 Vibe Coding 工作流示例 +## 团队落地建议 -### 典型的一天 +### 目录结构 -```bash -# 🌅 早上 -cd ~/project -git worktree list # 查看现有工作树 +```text +project-repo/ ← 主仓库，只做 merge 和主干同步 +wt-feature-123-login/ ← 功能开发 +wt-review-pr-208/ ← Code Review +wt-hotfix-login/ ← 紧急修复 +wt-spike-refactor/ ← 实验性探索 +``` -# 🎯 处理新任务 -git worktree add -b feature/dashboard ../wt-dashboard -cd ../wt-dashboard -npm install # 仅需要一次 -npm run dev # 开发服务器运行 +### 命名规范 -# 💬 收到 Code Review 反馈 -# 保持开发工作树继续运行 -cd ~/project -git worktree add feature/auth ../wt-review-auth -cd ../wt-review-auth # 检视同事代码 -# 无需关闭开发窗口，两个项目并行运行 - -# 🚨 线上紧急 Bug -git worktree add -b hotfix/payment ../wt-hotfix -cd ../wt-hotfix -npm run dev # 独立运行 -# 修复、测试、提交，然后删除 - -# 🌆 下午总结 -git worktree list -git worktree remove ../wt-review-auth -git worktree remove ../wt-hotfix -git worktree prune +```text +wt-feature-- 功能开发 +wt-bugfix-- bug 修复 +wt-hotfix- 线上紧急修复 +wt-review- 代码审查 +wt-spike- 实验性探索 ``` -### Q4：如何降低依赖重复安装成本 +### 生命周期 + +1. 在主工作树同步最新主干 +2. 为任务创建 worktree（带上 `-b` 显式创建新分支） +3. 在新窗口中打开该目录 +4. 只在这个窗口里和 AI 讨论当前任务 +5. 提交、验证、合并 +6. 删除 worktree，执行 `git worktree prune` -建议优先使用包管理器缓存能力，而不是跨工作树硬链接依赖目录。 +### 几条注意事项 + +- 不要在多个 worktree 里操作同一个分支（Git 不允许，也没有必要） +- 不要长期积压无人认领的 worktree，占空间也容易混淆 +- 多个 worktree 启动 dev server 时记得配不同端口，避免冲突 +- 使用 pnpm 的团队可以配置共享 store，降低重复安装成本： ```bash pnpm config set store-dir ../.pnpm-store @@ -419,34 +408,73 @@ pnpm config set store-dir ../.pnpm-store --- -## 🎓 学习资源 +## 常见问题 + +### Q1：删除 worktree 时提示被锁定 + +```bash +git worktree unlock ../wt-review-payment +git worktree remove ../wt-review-payment +``` + +### Q2：worktree 里 git fetch 没有更新 -- **官方文档**: `man git-worktree` 或 `git worktree --help` -- **Git 官方**: https://git-scm.com/docs/git-worktree -- **案例集**: 在团队 Confluence 中创建工作树使用案例库 +fetch 需要在主仓库执行，结果会共享给所有 worktree： + +```bash +cd ~/project +git fetch --all # 所有 worktree 都能看到最新远程状态 +``` + +### Q3：删除时提示有未提交的更改 + +```bash +# 强制删除（未提交内容会丢失，谨慎操作） +git worktree remove ../wt-review-payment --force +``` + +### Q4：什么时候不需要开新 worktree + +几分钟内能完成、不需要独立运行环境、不需要独立 AI 上下文的改动，直接在当前目录处理就好。 + +开新 worktree 的判断标准： + +- 需要切换到另一个分支 +- 需要保留当前开发现场 +- 需要独立的 AI 上下文 +- 需要并行运行服务或测试 --- -## 📞 技术支持 +## 总结 + +Git Worktree 不是一个"高级 Git 技巧"，而是 AI 协作开发时代很实用的基础设施。 + +它真正解决的不是"切分支更快"，而是： -遇到问题？ +- 让多个并行任务各自拥有稳定的工作现场 +- 让 AI 的上下文不在不同任务之间串台 +- 让 Hotfix、Review、功能开发、实验探索互不干扰地推进 -1. **检查状态**: `git worktree list --verbose` -2. **清理环境**: `git worktree prune` -3. **查看日志**: `cd .git && grep -r "worktree" logs/` -4. **联系技术负责人**: 在团队 Slack 中 @tech-lead +如果团队已经在用 AI 写代码，那么下一步值得标准化的不只是提示词，而是： + +**任务怎么切，目录怎么开，窗口怎么隔离，AI 怎么约束。** --- -## 📝 更新日志 +## 参考资源 -| 版本 | 日期 | 变更 | -|------|------|------| -| v1.0 | 2026-04-26 | 初始版本发布 | -| - | - | 包含基础用法、最佳实践、高级技巧 | +- Git 官方文档：https://git-scm.com/docs/git-worktree +- 命令帮助：`git worktree --help` --- -**最后更新**: 2026 年 4 月 26 日 -**维护人**: 技术团队 -**欢迎反馈和改进意见！** +## 更新日志 + +| 版本 | 日期 | 变更 | +|------|------|------| +| v3.0 | 2026-04-26 | 以 Vibe Coding 为主线重写，融合实战场景与 AI 提示词模板 | +| v2.0 | 2026-04-26 | 重构为内部分享稿，补充 AI + Worktree 协作原则 | +| v1.0 | 2026-04-26 | 初始版本 | + +最后更新：2026 年 4 月 26 日 From cc35d2b09b79b1177f31eec673b8713211dd57c7 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Tue, 28 Apr 2026 23:34:49 +0800 Subject: [PATCH 7/8] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20Git=20Worktree?= =?UTF-8?q?=20=E6=8C=87=E5=8D=97=EF=BC=8C=E4=BC=98=E5=8C=96=E5=86=85?= =?UTF-8?q?=E5=AE=B9=E7=BB=93=E6=9E=84=E4=B8=8E=E7=A4=BA=E4=BE=8B=EF=BC=8C?= =?UTF-8?q?=E5=A2=9E=E5=BC=BA=E5=AE=9E=E7=94=A8=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot --- GIT_WORKTREE_GUIDE.md | 240 +++--------------------------------------- 1 file changed, 15 insertions(+), 225 deletions(-) diff --git a/GIT_WORKTREE_GUIDE.md b/GIT_WORKTREE_GUIDE.md index 827d153..ff98650 100644 --- a/GIT_WORKTREE_GUIDE.md +++ b/GIT_WORKTREE_GUIDE.md @@ -1,26 +1,23 @@ -# Vibe Coding 下的 Git Worktree 实战 +# Vibe Coding 下的 Git Worktree > 在 AI 辅助开发背景下，如何用 Git Worktree 真正提升团队交付效率 --- -## 先说痛点 +## 痛点 -你有没有遇到过这种情况： - -正在用 AI 高速推进一个功能，代码写到一半，忽然来了一个 Hotfix 需求或者 Code Review 请求。 +用 AI 高速推进一个功能时，代码写到一半，忽然来了一个 Hotfix 需求。 然后你不得不： ```bash git stash save "WIP: new dashboard" -git checkout main +git checkout develop git checkout -b hotfix/login-bug # ... 修复 ... git push origin hotfix/login-bug git checkout feature/new-dashboard git stash pop -# 哎呀，stash pop 有冲突... ``` 每次切换，AI 对话的上下文要重新建立，dev server 要重启，构建缓存失效。原本高速运转的开发节奏，就这样被打断了。 @@ -64,23 +61,7 @@ wt-hotfix-login-bug/ ← 对应 hotfix/login-bug 分支 现在你可以同时在三个目录里工作，互不干扰，每个目录都有独立的终端、运行状态和 AI 对话上下文。 -还是刚才那个场景，换成 Worktree 方式： - -```bash -# 不需要 stash，不需要切分支 -# 直接创建一个新的工作树处理 hotfix -git worktree add -b hotfix/login-bug ../wt-hotfix-login-bug main -cd ../wt-hotfix-login-bug - -# 修复、测试、提交 -git commit -am "Fix: login timeout bug" -git push origin hotfix/login-bug - -# 删除 worktree，回到原来的目录 -git worktree remove ../wt-hotfix-login-bug -cd ~/project -# feature/new-dashboard 分支完全没动，所有改动都在，AI 对话也还在 -``` +同样的 Hotfix 场景，后面会在“实战场景”里给出完整操作示例。 --- @@ -107,7 +88,7 @@ Vibe Coding 的本质是：**开发者和 AI 高频协作，让"实现"这一步 --- -## 常用命令速查 +## Worktree 常用操作 ### 创建工作树 @@ -144,19 +125,9 @@ git worktree prune # 清理无效引用 ### 场景一：Hotfix 不打断功能开发 -**背景**：你正在 `feature/new-dashboard` 分支上用 AI 开发新功能，代码写到一半。产品找过来："线上登录功能挂了，马上修复！" - -**传统做法的问题**： +**背景**：你正在 `feature/new-dashboard` 分支上开发，突然来了线上登录故障。 -```bash -git stash save "WIP: new dashboard" -git checkout main -git checkout -b hotfix/login-bug -# 修复完... -git checkout feature/new-dashboard -git stash pop -# 常常这一步就出冲突了 -``` +传统分支切换的痛点在前文已经说明，这里直接看 Worktree 处理方式。 **Worktree 做法**： @@ -179,7 +150,7 @@ cd ~/project git status # 还是 feature/new-dashboard，所有改动都在 ``` -**AI 在这里的角色**：在 hotfix 的窗口里，你可以告诉 AI："我现在在一个专门用于修复登录超时的 worktree，帮我定位根因并给出最小修复方案，不要动其他逻辑。"这样 AI 的注意力不会被 dashboard 相关的文件和历史对话干扰。 +**AI 在这里的角色**：在 hotfix 窗口里明确边界，例如“只做登录超时最小修复，不改其他逻辑”，可以显著降低误改范围。 --- @@ -200,9 +171,7 @@ npm run dev # 独立启动，不干扰你的功能开发端口 git worktree remove ../wt-review-payment ``` -在 review 的窗口里，你可以让 AI："请先总结这个分支改了什么，然后找出潜在 bug 和回归风险，关注行为变化，不要做风格建议。" - -这比在同一个目录里切换分支 review 更干净，因为 dev server 是独立的，AI 的文件引用范围也是隔离的。 +在 review 窗口里，可以让 AI 先总结变更，再聚焦 bug、回归风险和验证缺口；由于目录与运行环境独立，review 过程更干净。 --- @@ -228,7 +197,7 @@ cd ../wt-v1.0 && git commit -am "Add user profile (v1.0)" cd ../wt-v2.0 && git commit -am "Add user profile (v2.0)" ``` -在每个版本的窗口里，AI 的文件上下文、.env 配置和 dev server 都是独立的，不会互相干扰。 +每个版本目录的 AI 上下文、环境变量和 dev server 都互不干扰。 --- @@ -255,136 +224,14 @@ git worktree remove ../wt-spike-search-v1 git worktree remove ../wt-spike-search-v2 ``` -两个 worktree 同时存在，AI 在各自窗口独立工作，最后直接对比结果。失败的方案删目录即可，主仓库完全不受影响。 - ---- - -## AI 提示词模板 - -下面这些提示词可以直接在 VS Code Copilot、Cursor 或其他 AI 工具中使用。核心思路是：**告诉 AI 当前 worktree 的角色和边界，让它不要越界。** - -### 功能开发 - -```text -你现在在一个 git worktree 中工作，这个目录只负责当前功能，不处理其他任务。 - -目标：实现 <功能名称>。 -上下文：先阅读相关代码、接口和已有组件，再给出最小改动方案并直接修改代码。 - -要求： -1. 只修改和当前功能直接相关的文件。 -2. 优先复用现有实现，不重复造轮子。 -3. 不要顺手重构无关代码。 -4. 修改后说明最小验证步骤。 -5. 最后给出风险点和测试建议。 -``` - -### Code Review / 分支验证 - -```text -你现在在一个 review 用的 git worktree 中工作，目标是评估这个分支的变更质量，而不是继续开发新功能。 - -请按下面顺序处理： -1. 先总结这个分支改了什么。 -2. 找出潜在 bug、回归风险和边界情况。 -3. 指出是否缺少测试或验证步骤。 -4. 如果需要修改，只做最小修复并解释原因。 - -要求：关注行为变化，不要只做代码风格建议。 -``` - -### Hotfix - -```text -你现在在一个 hotfix 用的 git worktree 中工作。 - -目标：定位并修复 <问题描述>，优先保证快速、可验证、低风险上线。 - -请按下面顺序处理： -1. 根据现有代码推断最可能的根因。 -2. 给出最小修复方案。 -3. 说明这次修复不会扩大影响面的理由。 -4. 修改后列出必须执行的验证步骤。 - -要求：不要引入大范围重构，不要顺手优化无关逻辑。 -``` - -### 实验性方案 / Spike - -```text -你现在在一个实验性 worktree 中工作，目标是验证 <方案描述> 是否值得推进。 - -请先做以下事情： -1. 总结当前实现的问题。 -2. 给出最小可验证的实现切口。 -3. 说明收益、风险和回滚成本。 -4. 只实现最小原型，不要一次性铺开。 - -这是实验分支，失败了直接删目录，不影响主干。 -``` - ---- - -## 在 VS Code 和 Cursor 中怎么用 - -这部分只简单带一下，重点是用法，不是工具介绍。 - -### VS Code - -最推荐的方式是**一个 worktree 开一个独立窗口**： - -```bash -cd ../wt-feature-123-login -code . # 独立窗口，独立终端，独立 Copilot 对话 -``` - -如果需要同时观察多个分支，可以用 `File → Add Folder to Workspace` 把多个 worktree 加进同一个 Multi-Root Workspace： - -```json -{ - "folders": [ - { "path": "../project-repo", "name": "Main" }, - { "path": "../wt-feature-123-login", "name": "Feature 123" }, - { "path": "../wt-review-payment", "name": "Review Payment" } - ] -} -``` - -注意：同一个 workspace 里的多个 worktree 共享同一个 Copilot 会话，AI 上下文不是完全隔离的。**需要 AI 专注于单一任务时，还是推荐独立窗口。** - -### Cursor - -Cursor 更推荐**一个 worktree 对应一个独立项目窗口**。 - -这样每个窗口的 Composer 历史、文件引用范围、`@codebase` 的索引范围都是独立的，AI 给出的建议不会混入其他任务的上下文。 - -一句话总结： - -**VS Code / Cursor 只是入口，关键是"一个任务一个目录，一个目录一个 AI 上下文"。** +两个 worktree 可并行实验并直接对比结果；失败方案删目录即可，主仓库不受影响。 --- -## 团队落地建议 -### 目录结构 -```text -project-repo/ ← 主仓库，只做 merge 和主干同步 -wt-feature-123-login/ ← 功能开发 -wt-review-pr-208/ ← Code Review -wt-hotfix-login/ ← 紧急修复 -wt-spike-refactor/ ← 实验性探索 -``` -### 命名规范 - -```text -wt-feature-- 功能开发 -wt-bugfix-- bug 修复 -wt-hotfix- 线上紧急修复 -wt-review- 代码审查 -wt-spike- 实验性探索 -``` +## 团队落地 ### 生命周期 @@ -408,47 +255,9 @@ pnpm config set store-dir ../.pnpm-store --- -## 常见问题 - -### Q1：删除 worktree 时提示被锁定 - -```bash -git worktree unlock ../wt-review-payment -git worktree remove ../wt-review-payment -``` - -### Q2：worktree 里 git fetch 没有更新 - -fetch 需要在主仓库执行，结果会共享给所有 worktree： - -```bash -cd ~/project -git fetch --all # 所有 worktree 都能看到最新远程状态 -``` - -### Q3：删除时提示有未提交的更改 - -```bash -# 强制删除（未提交内容会丢失，谨慎操作） -git worktree remove ../wt-review-payment --force -``` - -### Q4：什么时候不需要开新 worktree - -几分钟内能完成、不需要独立运行环境、不需要独立 AI 上下文的改动，直接在当前目录处理就好。 - -开新 worktree 的判断标准： - -- 需要切换到另一个分支 -- 需要保留当前开发现场 -- 需要独立的 AI 上下文 -- 需要并行运行服务或测试 - ---- - ## 总结 -Git Worktree 不是一个"高级 Git 技巧"，而是 AI 协作开发时代很实用的基础设施。 +Git Worktree 不是“高级 Git 技巧”，而是 AI 协作开发时代的实用基础设施。 它真正解决的不是"切分支更快"，而是： @@ -458,23 +267,4 @@ Git Worktree 不是一个"高级 Git 技巧"，而是 AI 协作开发时代很 如果团队已经在用 AI 写代码，那么下一步值得标准化的不只是提示词，而是： -**任务怎么切，目录怎么开，窗口怎么隔离，AI 怎么约束。** - ---- - -## 参考资源 - -- Git 官方文档：https://git-scm.com/docs/git-worktree -- 命令帮助：`git worktree --help` - ---- - -## 更新日志 - -| 版本 | 日期 | 变更 | -|------|------|------| -| v3.0 | 2026-04-26 | 以 Vibe Coding 为主线重写，融合实战场景与 AI 提示词模板 | -| v2.0 | 2026-04-26 | 重构为内部分享稿，补充 AI + Worktree 协作原则 | -| v1.0 | 2026-04-26 | 初始版本 | - -最后更新：2026 年 4 月 26 日 +**任务怎么切，目录怎么开，窗口怎么隔离，AI 怎么约束。** \ No newline at end of file From 1a9ae6e7b7f7497aa4d22a9ac212e045fe056c53 Mon Sep 17 00:00:00 2001 From: "h.zhang_PC" Date: Wed, 29 Apr 2026 21:57:24 +0800 Subject: [PATCH 8/8] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20Git=20Worktree?= =?UTF-8?q?=20=E6=8C=87=E5=8D=97=EF=BC=8C=E4=BC=98=E5=8C=96=E5=86=85?= =?UTF-8?q?=E5=AE=B9=E4=B8=8E=E7=A4=BA=E4=BE=8B=EF=BC=8C=E5=A2=9E=E5=BC=BA?= =?UTF-8?q?=E5=9B=A2=E9=98=9F=E4=BA=A4=E4=BB=98=E6=95=88=E7=8E=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot --- GIT_WORKTREE_GUIDE.md | 74 ++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 39 deletions(-) diff --git a/GIT_WORKTREE_GUIDE.md b/GIT_WORKTREE_GUIDE.md index ff98650..32aebd6 100644 --- a/GIT_WORKTREE_GUIDE.md +++ b/GIT_WORKTREE_GUIDE.md @@ -1,17 +1,17 @@ # Vibe Coding 下的 Git Worktree -> 在 AI 辅助开发背景下，如何用 Git Worktree 真正提升团队交付效率 +> 在 AI 辅助开发背景下，如何用 Git Worktree 提升效率 --- ## 痛点 -用 AI 高速推进一个功能时，代码写到一半，忽然来了一个 Hotfix 需求。 +用 AI 推进一个功能时，代码写到一半，忽然来了一个 Hotfix 需求。 -然后你不得不： +然后你通常会使用git-stash暂时存储更改: ```bash -git stash save "WIP: new dashboard" +git stash git checkout develop git checkout -b hotfix/login-bug # ... 修复 ... @@ -20,10 +20,12 @@ git checkout feature/new-dashboard git stash pop ``` -每次切换，AI 对话的上下文要重新建立，dev server 要重启，构建缓存失效。原本高速运转的开发节奏，就这样被打断了。 +每次切换，原本的开发节奏，就这样被打断了。 这就是 Vibe Coding 场景下，传统分支管理方式的核心问题：**AI 让你更频繁地需要切换任务，但切换本身的成本并没有降低。** +如果你的工作区已经非常混乱（到处都是新增、移动和删除的文件，以及其他零碎的文件），你不想冒险破坏任何现有内容时怎么做? + --- ## 什么是 Git Worktree @@ -119,6 +121,11 @@ git worktree prune # 清理无效引用 这不是缺陷，反而是一个保护机制——它强制你用"一个任务一个分支"的方式工作。 +--- + +## 在 IDE 插件里git worktree的使用 + + --- ## 实战场景 @@ -160,12 +167,12 @@ git status # 还是 feature/new-dashboard，所有改动都在 ```bash # 主工作树继续开发功能 -# 另开一个 worktree 专门用于 review + +# 另开一个 worktree 专门用于 review 远程分支"feature/payment" git worktree add ../wt-review-payment feature/payment -cd ../wt-review-payment -npm install -npm run dev # 独立启动，不干扰你的功能开发端口 +# 也可以只review某个历史提交的代码 +git worktree add --detach ../wt-review-payment abcdef1 # review 完成后 git worktree remove ../wt-review-payment @@ -201,35 +208,34 @@ cd ../wt-v2.0 && git commit -am "Add user profile (v2.0)" --- -### 场景四：AI 驱动的方案 A/B 实验 +### 场景四：AI 驱动的方案实验 -**背景**：有一个性能优化方向，不确定哪种方案更好，想让 AI 分别实现两套然后对比。 +**背景**：有一个前端美化需求，不确定哪种方案更好，想让多种大模型分别实现然后对比。 ```bash -# 开两个实验性 worktree -git worktree add -b spike/search-v1 ../wt-spike-search-v1 main -git worktree add -b spike/search-v2 ../wt-spike-search-v2 main +# 开N个实验性 worktree +git worktree add -b feat/beauty-v1 ../wt-beauty-v1 main +git worktree add -b feat/beauty-v2 ../wt-beauty-v2 main +git worktree add -b feat/beauty-v3 ../wt-beauty-v3 main -# 在 wt-spike-search-v1 窗口里让 AI 实现方案 A -# 在 wt-spike-search-v2 窗口里让 AI 实现方案 B +# 在 wt-spike-search-v1 窗口里让 GPT 实现方案 A +# 在 wt-spike-search-v2 窗口里让 Gemini 实现方案 B +# 在 wt-spike-search-v3 窗口里让 Claude 实现方案 C -# 分别跑性能测试 -cd ../wt-spike-search-v1 && npm run benchmark # 150ms -cd ../wt-spike-search-v2 && npm run benchmark # 120ms +# 分别跑前端页面查看效果 -# 选方案 B，废弃方案 A +# 选方案 A，废弃方案 B和C cd ~/project -git merge spike/search-v2 -git worktree remove ../wt-spike-search-v1 -git worktree remove ../wt-spike-search-v2 +git merge feat/beauty-v1 +git worktree remove ../wt-beauty-v2 +git worktree remove ../wt-beauty-v3 ``` -两个 worktree 可并行实验并直接对比结果；失败方案删目录即可，主仓库不受影响。 - ---- - +N个 worktree 可并行实验并直接对比结果；失败方案删目录即可，主仓库不受影响。 +同理, 也可以用于多个方案的性能优化等需求 +--- ## 团队落地 @@ -246,25 +252,15 @@ git worktree remove ../wt-spike-search-v2 - 不要在多个 worktree 里操作同一个分支（Git 不允许，也没有必要） - 不要长期积压无人认领的 worktree，占空间也容易混淆 -- 多个 worktree 启动 dev server 时记得配不同端口，避免冲突 - 使用 pnpm 的团队可以配置共享 store，降低重复安装成本： -```bash -pnpm config set store-dir ../.pnpm-store -``` --- ## 总结 -Git Worktree 不是“高级 Git 技巧”，而是 AI 协作开发时代的实用基础设施。 - -它真正解决的不是"切分支更快"，而是： +Git Worktree 真正解决的不是"切分支更快"，而是： - 让多个并行任务各自拥有稳定的工作现场 -- 让 AI 的上下文不在不同任务之间串台 - 让 Hotfix、Review、功能开发、实验探索互不干扰地推进 - -如果团队已经在用 AI 写代码，那么下一步值得标准化的不只是提示词，而是： - -**任务怎么切，目录怎么开，窗口怎么隔离，AI 怎么约束。** \ No newline at end of file +- 探索同一任务的多个可能性