home / skills / theonelee / theone_claude_skill / git_worktree_skill

git_worktree_skill skill

safe

This skill enables parallel development by managing isolated git worktrees for different branches, preventing conflicts and speeding multi-task work.

npx playbooks add skill theonelee/theone_claude_skill --skill git_worktree_skill

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: git_worktree_skill
description: 使用 git worktree 管理并行开发工作区的技能。它允许 agent 在独立的工作目录中处理不同的分支，避免在主工作区产生冲突，并支持高效的多任务并行。
---

# Git Worktree Skill

该技能旨在帮助 agent 合理利用 `git worktree` 创建独立的工作区，从而支持多个 agent 或多个任务并行开发，避免代码冲突和工作区混乱。

## 核心任务

1. **评估需求**：当需要并行处理多个任务（如一个 agent 在做重构，另一个在修 bug）时，自动评估是否需要创建新工作区。
2. **工作区创建**：
    - 检查目标分支是否已存在。
    - 使用 `git worktree add <path> <branch>` 创建新工作区。建议路径格式为 `../worktrees/<branch_name>` 或在项目根目录外的专用目录。
3. **环境准备**：在新工作区中执行必要的初始化命令（如 `npm install`、`go mod download` 或 `uv sync`），确保开发环境独立且可用。
4. **状态同步**：在任务完成后，确保代码已提交并推送到远端。
5. **清理资源**：任务彻底结束并确认代码合入后，使用 `git worktree remove <path>` 清理工作区及其相关文件，保持系统整洁。

## 操作流程示例

### 1. 创建并切入新工作区

用户要求： "为一个新的 feature `feat-login` 创建一个独立的工作区进行开发。"

执行逻辑：
1. 运行 `git worktree add ../robotaxi-feat-login -b feat-login`。
2. 进入新路径：`cd ../robotaxi-feat-login`。
3. 执行初始化：`uv sync` (如果是 Python 项目) 或 `go mod tidy` (如果是 Go 项目)。

### 2. 列出当前所有工作区

运行 `git worktree list` 查看所有活跃的工作区及其对应分支。

### 3. 清理已完成的工作区

运行 `git worktree remove ../robotaxi-feat-login`。如果存在未提交的更改，需先处理或使用 `--force`（慎用）。

## 注意事项

- **分支冲突**：Git 不允许在两个不同的工作区同时 checkout 同一个分支。
- **路径管理**：确保工作区路径在项目根目录之外，以避免被误包含在 Git 管理中或引起依赖扫描问题。
- **资源消耗**：大量的工作区可能会占用较多磁盘空间，尤其是包含 `node_modules` 或庞大依赖的项目，及时清理非常重要。
- **DB/缓存隔离**：如果项目依赖本地数据库或缓存，需注意并行工作区可能共享这些资源，必要时需配置独立的环境变量。

Overview

This skill helps agents manage parallel development using git worktree. It creates independent working directories for different branches, isolates changes, and reduces conflicts in the main workspace. The skill also handles environment initialization, status sync, and safe cleanup of temporary worktrees.

How this skill works

The skill inspects the current repository state, checks whether a target branch exists, and runs git worktree commands to add or remove worktrees. It can initialize project-specific dependencies inside the new worktree (for example npm install, go mod download, or project-specific sync commands). After work completes it ensures commits and pushes are performed, then removes the worktree to free resources.

When to use it

When multiple agents or developers must work on different branches concurrently
When you want to isolate a risky refactor or experimental feature from the main workspace
When CI/manual tasks require an ephemeral workspace for testing or builds
When you need to avoid switching branches in the primary working directory
When creating a temporary environment for debugging without affecting the main repo

Best practices

Create worktrees outside the project root (example: ../worktrees/<branch>) to avoid accidental inclusion in repo scanning
Always verify branch existence and use -b to create a branch when needed
Run dependency install or environment setup inside the new worktree to avoid sharing node_modules or caches
Commit and push changes from the worktree before removal; handle uncommitted changes explicitly to avoid data loss
Regularly remove finished worktrees to reclaim disk space, and avoid leaving many large dependency directories active

Example use cases

Open a worktree feat-login for a new feature, run project init commands, implement and test changes independently
Give a bugfix task its own worktree so a CI job can run without disturbing ongoing feature work
Spin up an ephemeral worktree to reproduce an issue against a different branch and validate a patch
Support multiple agents: assign each agent a dedicated worktree when running parallel static analysis or refactors

FAQ

Can two worktrees use the same branch?

No. Git prevents checking out the same branch in multiple worktrees. Create a new branch copy or use a temporary branch for parallel work.

What if there are uncommitted changes when removing a worktree?

Handle changes by committing/pushing or stashing first. git worktree remove will fail on dirty changes unless forced; use --force with caution to avoid data loss.