Git Worktrees for AI Development

my-project/                    ← 主工作树  (分支: main)
my-project-feat-auth/          ← 链接工作树 (分支: feat/auth)
my-project-feat-api/           ← 链接工作树 (分支: feat/api)
my-project-hotfix-login/       ← 链接工作树 (分支: hotfix/login)

# 确认工作树是干净的
git status

# 如果有未提交的修改，提交它们
git add . && git commit -m "checkpoint: work in progress"

# 在 ../myapp-feat-auth 路径下创建新分支 feat/auth 的工作树
# 将 "myapp" 替换为你的项目名，"feat/auth" 替换为你的分支名
git worktree add -b feat/auth ../myapp-feat-auth main

# 验证是否创建成功
git worktree list

/home/user/myapp            abc1234 [main]
/home/user/myapp-feat-auth  abc1234 [feat/auth]

cd ../myapp-feat-auth

# 复制被git忽略的环境文件
# .env、.env.local等文件不会被git跟踪 --
# 它们不会自动出现在新的工作树中
cp ../myapp/.env .env
cp ../myapp/.env.local .env.local 2>/dev/null || true

# Node.js项目：安装依赖
# 每个工作树都是独立的工作目录 --
# 父目录的node_modules不会自动继承
npm install

# Python项目：创建并激活虚拟环境
# python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

# 在新工作树内部
git branch
# 应显示：* feat/auth

# 做一个测试修改
echo "// test" >> test-isolation.js
git status
# 仅显示当前工作树的修改

# 切换到主目录并验证未受影响
cd ../myapp
git status
# 状态干净 -- test-isolation.js的修改在此不可见
ls test-isolation.js 2>/dev/null || echo "此处没有 -- 隔离性已确认"

myapp/                       ← 主窗口：协调与审查
myapp-feat-authentication/   ← 代理1：实现OAuth2流程
myapp-feat-api-endpoints/    ← 代理2：构建REST端点
myapp-bugfix-login-crash/    ← 代理3：修复生产环境登录崩溃

#!/usr/bin/env bash
# create-worktree.sh
# 为一个AI代理任务创建独立的工作树
# 用法：./create-worktree.sh
[base-branch]
# 示例：./create-worktree.sh feat/auth-redesign main

set -euo pipefail

BRANCH="${1:?Usage: $0
[base-branch]}"
BASE="${2:-main}"
REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$REPO_ROOT")"

# 将分支名中的斜杠替换为连字符用于目录命名
# feat/auth-redesign 变为 feat-auth-redesign
WORKTREE_PATH="${REPO_ROOT}/../${REPO_NAME}-${BRANCH//\//-}"

echo "为分支创建工作树: $BRANCH"
echo "基准分支: $BASE"
echo "工作树路径: $WORKTREE_PATH"

# 获取最新代码使新分支从当前远程状态开始
git fetch origin 2>/dev/null || echo "(无远程仓库--跳过获取)"

# 从基准分支创建新分支的工作树
# 如果 -b 失败则回退到检出现有分支
git worktree add -b "$BRANCH" "$WORKTREE_PATH" "$BASE" 2>/dev/null || \
  git worktree add "$WORKTREE_PATH" "$BRANCH"

# 复制未跟踪的环境文件到工作树
# 这些文件被.gitignore忽略，因此不会自动继承
for f in .env .env.local .env.development .env.test; do
  if [ -f "$REPO_ROOT/$f" ]; then
    cp "$REPO_ROOT/$f" "$WORKTREE_PATH/$f"
    echo "已复制 $f"
  fi
done

# Node.js: 在新工作目录中安装依赖
if [ -f "$WORKTREE_PATH/package.json" ]; then
  echo "安装Node依赖..."
  (cd "$WORKTREE_PATH" && npm install --silent 2>/dev/null || \
   echo "(跳过npm install--在工作树中手动运行)")
fi

# Python: 提醒开发者设置环境
if [ -f "$WORKTREE_PATH/requirements.txt" ] || [ -f "$WORKTREE_PATH/pyproject.toml" ]; then
  echo "检测到Python项目。"
  echo "在新工作树中运行："
  echo "  python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt"
fi

echo ""
echo "工作树已准备就绪。在IDE中打开它并启动你的代理："
echo "  cd $WORKTREE_PATH"

# AGENTS.md
# AI编码代理的项目上下文
# 提交到仓库根目录
# 每个打开此项目的代理都会首先读取此文件

## 项目概览
Node.js/TypeScript REST API搭配React前端
技术栈：Node 20，Express 5，Prisma ORM，PostgreSQL，React 18，Vite

## 构建与测试命令
npm run dev          # 在3000端口启动开发服务器
npm run build        # 构建生产版本到dist/
npm run test         # 运行所有测试（Vitest）
npm run test:watch   # 监听模式
npm run lint         # ESLint和Prettier检查
npm run db:migrate   # 运行待处理的Prisma迁移
npm run db:seed      # 种子开发数据

## 架构
- API路由：        src/routes/        每个资源一个文件
- 业务逻辑：       src/services/      从不在路由处理程序中
- 数据库访问：     src/repositories/  从不直接在服务中调用Prisma
- 共享类型：       src/types/index.ts

## 规范
- 所有导出函数需要JSDoc注释
- 提交代码中禁止使用console.log -- 使用src/utils/logger.ts
- 错误处理：从服务中抛出类型化错误，在路由处理程序中捕获
- 分支命名：feat/, fix/, refactor/

## 禁止修改区域 -- 除非明确指示否则不要修改
- src/auth/              （安全团队所有，独立审核流程）
- prisma/migrations/     （仅通过npm run db:migrate修改）
- .env文件             （永不提交，从不配置/外读取）

## 当前工作树任务
任务：                 [开始代理前填写]
分支：                [填写]
验收标准：            [填写]

# 创建工作树并在其中启动Claude Code会话
claude --worktree feat/auth-redesign

# 简写形式
claude -w feat/auth-redesign

# 使用tmux窗格实现分屏可见性
claude -w feat/auth-redesign --tmux

# .worktreeinclude -- 放在仓库根目录
# 创建新工作树时要复制的文件
.env
.env.local
.env.development

#!/usr/bin/env bash
# parallel-setup.sh
# 用一条命令为 N 个并行 AI 代理创建 N 个工作树
# 用法: ./parallel-setup.sh
...
# 示例: ./parallel-setup.sh feat/auth feat/api feat/dashboard

set -euo pipefail

if [ $# -eq 0 ]; then
  echo "用法: $0
..."
  echo "示例: $0 feat/auth feat/api feat/dashboard"
  exit 1
fi

REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$REPO_ROOT")"
MAIN_BRANCH="main"

echo "正在设置 ${#@} 个并行工作树..."
git fetch origin 2>/dev/null || echo "(没有远程仓库 -- 跳过获取)"

for BRANCH in "$@"; do
  SAFE="${BRANCH//\//-}"
  WT_PATH="${REPO_ROOT}/../${REPO_NAME}-${SAFE}"

  if [ -d "$WT_PATH" ]; then
    echo "已存在: $WT_PATH (跳过)"
    continue
  fi

  # 从 main 分支创建新分支的工作树
  git worktree add -b "$BRANCH" "$WT_PATH" "$MAIN_BRANCH" 2>/dev/null || \
    git worktree add "$WT_PATH" "$BRANCH"

  # 复制环境文件
  for f in .env .env.local; do
    [ -f "$REPO_ROOT/$f" ] && cp "$REPO_ROOT/$f" "$WT_PATH/$f"
  done

  echo "已创建: $WT_PATH  (分支: $BRANCH)"
done

echo ""
echo "所有工作树:"
git worktree list
echo ""
echo "在每个路径的独立终端或 IDE 窗口中打开，并启动你的代理。"
echo "记得在每个工作树的 AGENTS.md 中填写任务部分。"

#!/usr/bin/env bash
# sync-worktree.sh
# 将当前工作树分支变基到最新的主分支
# 在检查点运行以防止分支偏离
# 用法（在工作树内部）：./sync-worktree.sh [主分支名称]
# 示例：./sync-worktree.sh main

set -euo pipefail

MAIN_BRANCH="${1:-main}"
CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"

if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
  echo "已经在 $MAIN_BRANCH 分支 -- 无需同步。"
  exit 0
fi

echo "正在将 '$CURRENT_BRANCH' 同步到 '$MAIN_BRANCH'..."

# 如果存在未提交的工作，拒绝执行 -- 变基需要干净的状态
if ! git diff --quiet || ! git diff --cached --quiet; then
  echo "错误：检测到未提交的更改。"
  echo "请先提交您的进度："
  echo "  git add . && git commit -m 'checkpoint: agent progress'"
  exit 1
fi

# 获取最新的远程状态
git fetch origin

# 将此分支变基到最新的主分支
# --autostash 可自动处理轻微的工作树差异
git rebase "origin/$MAIN_BRANCH" --autostash

echo ""
echo "完成。'$CURRENT_BRANCH' 已与 origin/$MAIN_BRANCH 同步。"
echo ""
echo "准备推送时："
echo "  git push --force-with-lease"
echo ""
echo "注意：--force-with-lease 比 --force 更安全。"
echo "如果其他人已推送至该分支，它会拒绝推送。"

# 在工作树内部，代理完成任务后

# 1. 提交代理的工作
git add .
git commit -m "feat: implement OAuth2 + PKCE auth flow"

# 2. 打开 PR 前与主分支同步
./sync-worktree.sh

# 3. 运行测试以验证同步未导致问题
npm run test

# 4. 推送分支
git push --force-with-lease origin feat/auth-redesign

# 5. 通过 GitHub CLI 或网页界面打开 PR
gh pr create \
  --title "feat: OAuth2 + PKCE authentication" \
  --body "Implements OAuth2 per docs/auth-spec.md. All tests pass."

# 6. PR 合并后清理
cd ../myapp
./cleanup-worktree.sh feat/auth-redesign

# 从主分支创建新分支的工作树
git worktree add -b feat/payments ../myapp-payments main

# 将现有分支检出到新工作树
git worktree add ../myapp-feat-auth feat/auth

# 分离的 HEAD -- 用于在特定提交上重现 bug
git worktree add --detach ../myapp-debug abc1234

# 直接跟踪远程分支
git worktree add ../myapp-hotfix origin/hotfix/login-crash

# 显示所有工作树的路径、提交哈希和分支名称
git worktree list

# 用于脚本的机器可读输出
git worktree list --porcelain

# 锁定工作树以防止被删除
# 在代理程序运行时使用，防止意外清理
git worktree lock ../myapp-feat-auth --reason "agent-running"

# 解除锁定
git worktree unlock ../myapp-feat-auth

# 移动工作树目录（关闭所有打开的编辑器后再执行）
git worktree move ../myapp-feat-auth ../worktrees/auth-redesign

# 清洁地删除工作树——Git 中的分支会被保留
git worktree remove ../myapp-feat-auth

# 即使存在未提交的更改也强制删除
# 仅在确定工作内容可以丢弃时使用
git worktree remove --force ../myapp-feat-auth

# 手动删除工作树后清理元数据
git worktree prune

# 预览将被清理的内容而不会实际执行清理
git worktree prune --dry-run

# 在移动 .git 目录后修复工作树引用
git worktree repair

fatal: 'feat/auth' is already checked out

fatal: <path> already exists

error: '...' is a main worktree

error: worktree has modified files

--force

rm -rf