# Worktree

> Create and manage git worktrees for parallel development. Use when you need to work on multiple branches simultaneously without stashing or switching contexts. Use when this capability is needed.

- Skill: `tomevault-io/worktree-10` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/worktree-10`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/worktree-10/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/worktree-10

---


# Git Worktree Workflow

Create a git worktree to enable parallel development on multiple branches.

## Arguments

- First argument: New branch name (required)
- Second argument: Base branch to create from (optional, auto-detects default branch)

## Worktree Directory Convention

Worktrees are created in `../worktrees/<repo-name>-<branch-name>` relative to the main repository.

This naming convention:
- Keeps all worktrees in a shared `worktrees` directory above the repo
- Includes repo name to avoid conflicts when working on multiple projects
- Includes branch name for easy identification

Example: If working in `/home/user/projects/my-app` on branch `feature-auth`, the worktree path would be `/home/user/projects/worktrees/my-app-feature-auth`

## Instructions

1. **Get repository info**
   ```bash
   # Get repo root and name
   repo_root=$(git rev-parse --show-toplevel)
   repo_name=$(basename "$repo_root")
   ```

2. **Check repository status**
   ```bash
   git status
   git worktree list
   ```

3. **Determine base branch**
   - Use the second argument if provided
   - Otherwise, detect default branch:
     ```bash
     # Try remote HEAD first
     git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
     # Fallback to checking main/master
     git show-ref --verify --quiet refs/remotes/origin/main && echo "main"
     git show-ref --verify --quiet refs/remotes/origin/master && echo "master"
     ```

4. **Create the worktree**
   ```bash
   # Define paths
   branch_name="<first-argument>"
   # Convert slashes in branch name to dashes for directory name
   # e.g., "feature/user-auth" -> "feature-user-auth"
   dir_safe_branch="${branch_name//\//-}"
   worktrees_dir="$(dirname "$repo_root")/worktrees"
   worktree_path="$worktrees_dir/${repo_name}-${dir_safe_branch}"

   # Create worktrees directory if needed
   mkdir -p "$worktrees_dir"

   # Fetch latest from base branch
   git fetch origin <base-branch>

   # Create worktree with new branch from base
   git worktree add "$worktree_path" -b "$branch_name" origin/<base-branch>
   ```

5. **Verify creation**
   ```bash
   git worktree list
   ```

6. **Report to user**
   - Confirm the new worktree path
   - Show which branch it's based on
   - Remind user how to navigate: `cd <worktree_path>`

## Temporary Branch Handling

When a branch has a temporary name (pattern: `wt-*` or similar timestamp-based names), you should:

1. **Detect temporary branch**
   ```bash
   branch=$(git branch --show-current)
   if [[ "$branch" == wt-* ]]; then
       # This is a temporary branch
   fi
   ```

2. **Ask about the task context**
   - What feature or fix is being worked on?
   - Is there an issue ID (e.g., ISSUE-123)?

3. **Suggest and rename the branch**
   ```bash
   # Rename to a meaningful name based on the task
   git branch -m <old-name> <new-name>
   ```

   **Naming conventions:**
   - `feature/<description>` - New features
   - `fix/<description>` - Bug fixes
   - `refactor/<description>` - Code refactoring
   - `docs/<description>` - Documentation changes
   - `ISSUE-123-<description>` - When linked to an issue tracker

4. **Example interaction:**
   ```
   User: Let's add user authentication

   Claude: I notice the current branch has a temporary name 'wt-1706789012'.
   Based on your task, I'll rename it to something more descriptive.

   [Runs: git branch -m wt-1706789012 feature/user-auth]

   Branch renamed to 'feature/user-auth'. Now let's implement the authentication...
   ```

## Cleanup Instructions

When the user wants to remove a worktree:

```bash
# Get current repo info
repo_root=$(git rev-parse --show-toplevel)
repo_name=$(basename "$repo_root")
branch_name="<branch-name>"
# Convert slashes in branch name to dashes for directory name
dir_safe_branch="${branch_name//\//-}"
worktrees_dir="$(dirname "$repo_root")/worktrees"

# Remove a specific worktree
git worktree remove "$worktrees_dir/${repo_name}-${dir_safe_branch}"

# Or manually delete and prune
rm -rf "$worktrees_dir/${repo_name}-${dir_safe_branch}"
git worktree prune

# List remaining worktrees
git worktree list
```

## Examples

```bash
# Create a feature branch worktree from auto-detected default branch
/worktree feature/user-auth

# Create a feature branch worktree from main
/worktree feature/user-auth main

# Create a hotfix worktree from production branch
/worktree hotfix/login-bug production
```

## Integration with claude-wt

This skill works with the `claude-wt` bash script:

1. `claude-wt` creates a worktree with a temporary branch name (e.g., `wt-1706789012`)
2. The worktree is created at `../worktrees/<repo-name>-<branch-name>`
3. Claude Code starts in the worktree directory
4. When the user describes their task, rename the branch appropriately
5. Continue with the implementation

## Red Flags

**Never:**
- Proceed with a temporary branch name (`wt-*`) without asking about renaming
- Create worktrees in directories that don't follow the convention

**Always:**
- Use the path convention: `../worktrees/<repo-name>-<branch-name>`
- Detect and offer to rename temporary branches
- Auto-detect the default branch if not specified
- Verify worktree creation with `git worktree list`

---
> Source: [forrestchang/worktree-workflow](https://github.com/forrestchang/worktree-workflow) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-20 -->