git-worktree-workflow

name

git-worktree-workflow

description

Manage isolated development sessions using git worktrees. Use when the user wants to work on a feature branch with isolated Cursor/IDE sessions, create a worktree for a ticket (e.g., "create worktree for PROJ-1234"), switch between features without stashing, preserve session history per feature, or manage multiple branches simultaneously. Triggers on "create worktree", "new worktree", "worktree for ticket", "isolated session", "feature branch session".

Git Worktree Workflow

Manage multiple feature branches with isolated IDE sessions using git worktrees. Each worktree gets its own Cursor window with preserved session history.

Why Worktrees

Instead of switching branches in one directory, worktrees let you have multiple branches checked out simultaneously in separate folders:

• No stashing or context switching
• Session history preserved per feature
• Return to old sessions days/weeks later
• Each window shows only that feature's changes

Configuration

Config file: config.json (in this skill folder)

{
  "repos": {
    "<repo-name>": {
      "main": "~/path/to/repo",
      "suffix": "RepoSuffix",
      "copy_dirs": [".cursor/rules", ".cursor/skills"]
    }
  },
  "worktrees_base": "~/path/to/worktrees",
  "username": "<your-username>",
  "default_branch": "dev"
}

Field	Description
repos.<name>.main	Path to main repo checkout
repos.<name>.suffix	Suffix for worktree folder names
repos.<name>.copy_dirs	Directories to copy to new worktrees
worktrees_base	Base folder for all worktrees
username	Git branch prefix
default_branch	Base branch for new worktrees

Creating a Worktree

New branch

cd <repo-main-path>
git fetch origin
git worktree add <worktrees_base>/<TICKET>-<Suffix> -b <username>/<TICKET> origin/<default_branch>

From existing branch

git worktree add <worktrees_base>/<TICKET>-<Suffix> <existing-branch>

Copy Cursor config

cp -r .cursor/rules <worktrees_base>/<TICKET>-<Suffix>/.cursor/
cp -r .cursor/skills <worktrees_base>/<TICKET>-<Suffix>/.cursor/

Open in Cursor

cursor <worktrees_base>/<TICKET>-<Suffix>

Managing Worktrees

# List all worktrees
git worktree list

# Remove a worktree
git worktree remove <worktree-path>

# Prune stale worktree references
git worktree prune

Directory Structure

<worktrees_base>/               # All worktrees (any repo)
├── PROJ-1234-RepoA/            # RepoA worktree
├── PROJ-5678-RepoA/            # Another RepoA worktree
└── OTHER-123-RepoB/            # RepoB worktree

Naming Conventions

Item	Pattern	Example
Folder	<TICKET>-<Suffix>	PROJ-1234-RepoName
Branch	<username>/<TICKET>	john/PROJ-1234

Disk Space

Worktrees share .git objects with main repo (lightweight).

State	Size
Source only	~300-500MB
After build	~1.5-2GB

Clean build artifacts

rm -rf <worktree-path>/node_modules
rm -rf <worktree-path>/**/bin
rm -rf <worktree-path>/**/obj

AI Agent Instructions

When user asks to create a worktree for a ticket:

1. Read config.json from this skill folder for user settings
2. If config.json doesn't exist, help the user create it (see "First-Time Setup" below)
3. Identify which repo based on ticket prefix or current workspace
4. Check if branch already exists: git branch -a | grep <TICKET>
5. CRITICAL: All git and copy commands MUST use required_permissions: ["all"] because:
   • Worktrees are created outside the workspace directory
   • Git config files need to be modified
   • The sandbox will block these operations otherwise
6. Create worktree using the appropriate command:
   • New branch: git fetch origin && git worktree add <path> -b <branch> origin/<default_branch>
   • Existing branch: git worktree add <path> <existing-branch>
7. Copy directories listed in copy_dirs (also requires ["all"] permissions)
8. Output the path for user to open

First-Time Setup (config.json missing)

If config.json doesn't exist in this skill folder, help the user create it:

1. Detect current workspace info:

   # Get repo name from git remote
   git remote get-url origin | sed 's/.*\/\([^\/]*\)\.git/\1/' | sed 's/.*\/\([^\/]*\)$/\1/'
   
   # Get current workspace path
   pwd
   
   # Get git username
   git config user.name | tr ' ' '-' | tr '[:upper:]' '[:lower:]'
   
   # Get default branch
   git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
   

2. Ask user to confirm/adjust these values:

   • Worktrees base directory (suggest: ~/worktrees or ~/Stuff/worktrees)
   • Username for branch prefix (from git config or ask)
   • Default branch (detected or ask)

3. Generate and save config.json:

   {
     "repos": {
       "<detected-repo-name>": {
         "main": "<current-workspace-path>",
         "suffix": "<RepoName-capitalized>",
         "copy_dirs": [".cursor/rules", ".cursor/skills"]
       }
     },
     "worktrees_base": "<user-chosen-path>",
     "username": "<detected-or-provided>",
     "default_branch": "<detected-or-provided>"
   }
   

4. Save to skill folder (requires ["all"] permissions):

   # Skill folder location (check both global and local)
   # Global: ~/.cursor/skills/git-worktree-workflow/config.json
   # Local: .cursor/skills/git-worktree-workflow/config.json
   

5. Then proceed with the original worktree creation request

Permission Requirements

# All worktree operations need full permissions
Shell(
    command="git worktree add ...",
    required_permissions=["all"]
)

# Copying to worktree also needs full permissions
Shell(
    command="cp -r .cursor/rules <worktree-path>/.cursor/",
    required_permissions=["all"]
)

Example Response

Worktree created for PROJ-1234

| Property | Value |
|----------|-------|
| Path | <worktrees_base>/PROJ-1234-<Suffix> |
| Branch | <username>/PROJ-1234 |

To open: cursor <full-path>

Troubleshooting

"fatal: branch already exists"

• Branch exists, use git worktree add <path> <existing-branch> instead

"fatal: '' is already checked out"

• Branch checked out elsewhere. Remove existing worktree or use different branch.