git-worktrees

Git Worktrees

Agent Skills™ 的一部分，由 googleadsagent.ai™ 提供

描述

Git Worktrees 可在不同目录中同时维护多个已检出的分支，从而实现并行开发。Agent 无需暂存更改并切换分支，而是为每项任务创建隔离的 worktree，以提供干净的测试基线并消除切换上下文的开销。每个 worktree 都是绑定到自身分支的完全独立工作区。

这项技能对于由子 Agent 驱动的开发至关重要，因为多个 Agent 会同时处理不同任务。若没有 worktree，Agent 就会覆盖彼此尚未提交的更改。有了 worktree，每个 Agent 都能在自己的目录和分支中工作，协调者则会将已完成的工作合并回主线。

Worktree 还能为测试提供干净的基线。当你需要在干净检出状态下验证测试是否通过——不受构建产物、本地配置或未提交更改的影响——全新的 worktree 就能满足这一需求。Worktree 的生命周期由明确的操作管理：任务开始时创建，完成时验证，合并后清理。

使用场景

• 需要并行开发多个任务，且互不干扰
• 子 Agent 需要隔离的文件系统来同时开展工作
• 需要干净检出状态，以便在没有本地产物的情况下运行测试
• 功能分支开发期间必须处理紧急修复
• 最佳方案选优实现需要独立工作区
• 希望并排比较不同分支的行为

工作原理

graph TD
    A[Main Repo] --> B["git worktree add ../task-1 -b feature/task-1"]
    A --> C["git worktree add ../task-2 -b feature/task-2"]
    A --> D["git worktree add ../hotfix -b hotfix/urgent"]
    B --> E[Agent 1 works in ../task-1]
    C --> F[Agent 2 works in ../task-2]
    D --> G[Agent 3 works in ../hotfix]
    E --> H[PR + Merge]
    F --> H
    G --> H
    H --> I["git worktree remove ../task-1"]
    H --> J["git worktree remove ../task-2"]
    H --> K["git worktree remove ../hotfix"]

每个 worktree 都是磁盘上的实际目录，拥有自己的检出分支。一个 worktree 中的更改不会影响其他 worktree。.git 元数据是共享的，因此可从任意 worktree 正常执行分支操作（push、fetch、log）。

实现

# Create a worktree for a new feature
git worktree add ../feature-auth -b feature/user-auth
cd ../feature-auth
npm install  # Dependencies may differ per branch

# List active worktrees
git worktree list
# /home/user/project        abc1234 [main]
# /home/user/feature-auth   def5678 [feature/user-auth]

# Run tests in a clean worktree
git worktree add ../clean-test --detach HEAD
cd ../clean-test
npm ci && npm test
cd ../project
git worktree remove ../clean-test

# Prune stale worktrees (after branch deletion)
git worktree prune

class WorktreeManager:
    def __init__(self, repo_root):
        self.repo_root = repo_root
        self.worktree_base = Path(repo_root).parent

    def create(self, task_name, base_branch="main"):
        branch = f"feature/{task_name}"
        path = self.worktree_base / task_name
        subprocess.run(
            ["git", "worktree", "add", str(path), "-b", branch, base_branch],
            cwd=self.repo_root, check=True
        )
        return WorktreeContext(path, branch)

    def remove(self, task_name):
        path = self.worktree_base / task_name
        subprocess.run(
            ["git", "worktree", "remove", str(path)],
            cwd=self.repo_root, check=True
        )

    def list_active(self):
        result = subprocess.run(
            ["git", "worktree", "list", "--porcelain"],
            cwd=self.repo_root, capture_output=True, text=True
        )
        return self.parse_worktree_list(result.stdout)

最佳实践

• 始终从主仓库创建 worktree，不要从其他 worktree 创建
• 在每个新 worktree 中运行 npm ci 或等效命令——各 worktree 不共享 node_modules
• 合并后及时移除 worktree，避免占用过多磁盘空间
• 定期使用 git worktree prune 清理过时引用
• 为 worktree 目录取描述性名称，以匹配其分支用途
• 切勿在两个 worktree 中同时检出同一分支

平台兼容性

平台	支持情况	备注
Cursor	完全支持	best-of-n-runner 原生使用 worktree
VS Code	完全支持	支持多根工作区
Windsurf	完全支持	基于 Shell 管理 worktree
Claude Code	完全支持	可直接访问 git
Cline	完全支持	通过终端执行 git 命令
aider	完全支持	可在任意 worktree 目录中运行

相关技能

• Subagent-Driven Development - 并行任务分派，依靠 worktree 隔离各 Agent 的文件系统
• Executing Plans - 执行计划并支持回滚，使用 worktree 建立干净的验证基线
• Code Review - 合并前应用于每个 worktree 分支的质量门禁

关键词

git-worktrees parallel-development isolated-workspace clean-baseline concurrent-branches subagent-isolation best-of-n branch-management

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License