AgentSkillsCN

worktree

为当前仓库创建或清理 Git 工作树。当用户希望在不进行暂存或切换分支的情况下，平行地在独立分支上开展工作时，此工具包将为您提供高效便捷的解决方案。

SKILL.md
--- frontmatter
name: worktree
description: Create or clean up git worktrees for the current repo. Use when the user wants to work on a separate branch in parallel without stashing or switching branches.
argument-hint: [create|cleanup] [branch-name]
allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion

Git Worktree Management

Manage git worktrees for the current repository. Worktrees live in .worktrees/ at the repo root and are automatically gitignored.

Arguments: $ARGUMENTS

  • •create <branch-name> — Create a new worktree for the given branch
  • •cleanup — Remove one or all worktrees
  • •If only a branch name is provided (no subcommand), treat it as create <branch-name>
  • •If no arguments are provided, ask the user what they want to do

Create Worktree

Step 1: Determine Repository Root

bash
git rev-parse --show-toplevel

Store this as REPO_ROOT. All paths below are relative to this.

Step 2: Determine Branch Name

Extract the branch name from $ARGUMENTS (strip the create prefix if present).

If no branch name was provided, use AskUserQuestion to ask for one.

Step 3: Create the Worktree

Create the .worktrees directory if it doesn't exist and add the worktree:

bash
mkdir -p "$REPO_ROOT/.worktrees"
git worktree add "$REPO_ROOT/.worktrees/<branch-name>" -b <branch-name>

If the branch already exists (the -b flag fails), retry without it:

bash
git worktree add "$REPO_ROOT/.worktrees/<branch-name>" <branch-name>

If the worktree already exists for that branch, inform the user and provide the path.

Step 4: Ensure .worktrees is Gitignored

Check if .worktrees is already covered by .gitignore:

bash
git check-ignore -q "$REPO_ROOT/.worktrees" 2>/dev/null

If the exit code is non-zero (not ignored), append .worktrees/ to $REPO_ROOT/.gitignore. If .gitignore doesn't exist, create it.

Step 5: Copy Environment Files

Find and copy all env files from the repo root into the new worktree:

bash
find "$REPO_ROOT" -maxdepth 1 -name '.env*' -type f

Copy each file found to the worktree root:

bash
cp "$REPO_ROOT/.env*" "$REPO_ROOT/.worktrees/<branch-name>/"

Also check for env files in common subdirectories that might have their own .env files (e.g., packages/, apps/, services/). Use glob patterns to find them:

bash
find "$REPO_ROOT" -maxdepth 3 -name '.env*' -type f -not -path '*/.worktrees/*' -not -path '*/node_modules/*' -not -path '*/.git/*'

For any env files found in subdirectories, recreate the directory structure in the worktree and copy them:

bash
# For each env file at a relative path like packages/api/.env.local:
mkdir -p "$REPO_ROOT/.worktrees/<branch-name>/packages/api"
cp "$REPO_ROOT/packages/api/.env.local" "$REPO_ROOT/.worktrees/<branch-name>/packages/api/.env.local"

Step 6: Check Project Documentation for Additional Setup

Read the following files if they exist at the repo root to understand if there are additional files or setup steps needed for the worktree:

  • •README.md
  • •CLAUDE.md
  • •AGENTS.md
  • •.claude/settings.local.json

Look for mentions of:

  • •Local configuration files that are not checked into git (e.g., local.settings.json, config.local.yaml)
  • •Required setup steps (e.g., npm install, pip install, dependency installation)
  • •Secret files or credential files that need to exist locally
  • •Database configuration or other environment-specific setup

If you find additional files that should be copied, copy them. If you find setup steps that should be run, inform the user but do not run them automatically — list them as post-setup steps.

Step 7: Output Summary

code
## Worktree Created

**Branch**: <branch-name>
**Path**: $REPO_ROOT/.worktrees/<branch-name>

### Files Copied
- .env
- .env.local
- [any other files copied]

### Post-Setup Steps
- [any steps the user should run, e.g., `cd .worktrees/<branch-name> && npm install`]
- [or "None required" if nothing else is needed]

Cleanup Worktrees

Step 1: Determine Repository Root

bash
git rev-parse --show-toplevel

Step 2: List Existing Worktrees

bash
git worktree list

Filter to show only worktrees that live under .worktrees/.

If there are no worktrees in .worktrees/, inform the user and stop.

Step 3: Ask What to Clean Up

Use AskUserQuestion to present the list of worktrees and ask the user which to remove:

  • •List each worktree with its branch name
  • •Include an "All" option to remove all worktrees
  • •Include a "Cancel" option

Step 4: Remove Selected Worktrees

For each worktree to remove:

bash
git worktree remove "$REPO_ROOT/.worktrees/<branch-name>" --force

If removal fails (uncommitted changes), inform the user and ask whether to force-remove or skip.

Step 5: Prune Stale Worktree References

bash
git worktree prune

Step 6: Clean Up Empty Directory

If .worktrees/ is now empty, remove it:

bash
rmdir "$REPO_ROOT/.worktrees" 2>/dev/null

Step 7: Output Summary

code
## Worktrees Cleaned Up

**Removed**:
- <branch-name-1>
- <branch-name-2>

**Remaining**: [count] worktrees (or "None")