Git Worktree Skill

Contents

1. Commands
2. Clone as Worktree
3. Convert to Worktree Form
4. Create Worktree
5. List Worktrees
6. Remove Worktree
7. Troubleshoot
8. Directory Structure
9. Scripts Reference

Commands

Recognition patterns:

• GitHub URLs: https://github.com/owner/repo, [email protected]:owner/repo.git
• Shorthand: owner/repo, blockchaincommons/research
• Natural variants: "clone", "get", "create from", "set up worktree"

Clone as Worktree

Clone a GitHub repository directly into worktree form.

Flow

User: "clone worktree from https://github.com/BlockchainCommons/research"

Step 1: Parse GitHub URL
  → Owner: BlockchainCommons
  → Repo: research

Step 2: Check target location
  → Target: ~/Documents/Workspace/claudecode/WORKTREES/GITHUB/BlockchainCommons/research/
  → If exists: Report and stop

Step 3: Preview and confirm
  "This will create:
    ~/Documents/Workspace/claudecode/WORKTREES/GITHUB/BlockchainCommons/research/
    ├── research.git/   (bare repository)
    └── main/           (main branch worktree)

   Proceed? [Y/n]"

Step 4: Execute clone
  → Clone as bare repository
  → Configure (core.bare=true, unset core.worktree)
  → Create main worktree

Step 5: Report success
  "✅ Cloned into worktree form

   Location: ~/Documents/Workspace/claudecode/WORKTREES/GITHUB/BlockchainCommons/research/
   ├── research.git/   (bare repository)
   └── main/           (worktree) ← start here

   cd ~/Documents/Workspace/claudecode/WORKTREES/GITHUB/BlockchainCommons/research/main"

Script

"${SKILL_BASE:-$HOME/.claude/skills/git-worktree}/scripts/clone-as-worktree.sh" "<url>" [branch]

Convert to Worktree Form

Convert an existing local repository to worktree form.

Flow

User: "convert to worktree"

Step 1: Detect repository type
  scripts/detect-repo-type.sh
  → STANDARD: Continue
  → WORKTREE: "Already in worktree form"
  → BARE: "Already a bare repository"

Step 2: Check preconditions
  → Uncommitted changes? Offer stash/commit/cancel
  → Submodules? Warn and block (v1.0)
  → Already in WORKTREES? Warn about nesting

Step 3: Extract owner from remote
  scripts/extract-owner.sh
  → GitHub remote found: Extract owner
  → No remote: "Add remote first: git remote add origin <url>"

Step 4: Detect inception commit (optional)
  scripts/detect-inception.sh
  → Signed inception: Note for preservation
  → No inception: Continue normally

Step 5: Preview and confirm
  "This will create:
    ~/Documents/Workspace/claudecode/WORKTREES/GITHUB/{owner}/{repo}/
    ├── {repo}.git/   (bare repository)
    └── main/         (main branch worktree)

   ⚠️  2 uncommitted changes detected
   Options: [A] Stash and convert  [B] Commit first  [C] Cancel"

Step 6: Execute conversion
  scripts/convert-to-worktree.sh [--stash]
  → Create directory structure
  → Clone local repo as bare
  → Configure bare repository
  → Create main worktree
  → Apply stashed changes if applicable

Step 7: Validate and report
  scripts/validate-setup.sh
  "✅ Converted to worktree form

   Location: ~/Documents/Workspace/claudecode/WORKTREES/GITHUB/{owner}/{repo}/
   ├── {repo}.git/   (bare repository)
   └── main/         (worktree) ← start here

   ✓ Branches: 3 preserved
   ✓ History: 47 commits intact
   ✓ Inception: Signed commit preserved ✓

   Original repository unchanged. Remove after verification:
     rm -rf /original/path"

Script

"${SKILL_BASE:-$HOME/.claude/skills/git-worktree}/scripts/convert-to-worktree.sh" [path] [--stash] [--force]

Options

• --stash: Auto-stash uncommitted changes (includes untracked with -u)
• --force: Skip confirmation prompt

Create Worktree

Add a worktree for a new or existing branch.

Flow

User: "create worktree for feature/new-api"

Step 1: Verify worktree-form repository
  → Standard repo: "Convert first with 'convert to worktree'"
  → Worktree/bare: Continue

Step 2: Parse branch name
  → Branch type: feature (new feature development)
  → Directory: feature-new-api/
  → Path: ~/WORKTREES/GITHUB/{owner}/{repo}/feature-new-api/

Step 3: Check for conflicts
  → Branch has worktree? Report existing location
  → Directory exists? Offer rename/remove

Step 4: Determine branch source
  → Branch exists: Checkout existing
  → Branch on remote: Track remote
  → New branch: Create from HEAD (or --from base)

Step 5: Create worktree
  scripts/create-worktree.sh feature/new-api [--from main]

Step 6: Report success
  "✅ Worktree created

   ✓ Branch type: feature
   ✓ Created branch: feature/new-api from main
   ✓ Created worktree: feature-new-api/

   cd ../feature-new-api"

Script

"${SKILL_BASE:-$HOME/.claude/skills/git-worktree}/scripts/create-worktree.sh" <branch> [--from <base>] [--force]

Branch Type Recognition

List Worktrees

Show all worktrees with status.

Flow

User: "list worktrees"

Step 1: Verify worktree-form repository
  → Standard repo: "Convert first with 'convert to worktree'"

Step 2: Display worktrees
  scripts/list-worktrees.sh

  "📁 research (BlockchainCommons)

   Bare repo: ~/WORKTREES/GITHUB/BlockchainCommons/research/research.git

   Worktrees:
   → main              main/           (current)
     develop           develop/
     feature/auth      feature-auth/

   3 worktree(s) total"

Script

"${SKILL_BASE:-$HOME/.claude/skills/git-worktree}/scripts/list-worktrees.sh" [path] [--json|--porcelain]

Output Formats

• Human-readable (default): Formatted display with current marker
• --json: JSON output for scripting
• --porcelain: Machine-readable, one worktree per line

Remove Worktree

Safely remove a worktree.

Flow

User: "remove worktree feature-auth"

Step 1: Find worktree
  → By path: /path/to/feature-auth
  → By directory name: feature-auth
  → By branch: feature/auth → feature-auth/

Step 2: Check preconditions
  → Current directory? "Change to different worktree first"
  → Uncommitted changes? Warn and offer --force

Step 3: Remove worktree
  scripts/remove-worktree.sh feature-auth [--force] [--delete-branch]

Step 4: Report success
  "✅ Worktree removed

   ✓ Removed worktree: feature-auth/

   Remaining worktrees:
   → main     main/    (current)
     develop  develop/"

Script

"${SKILL_BASE:-$HOME/.claude/skills/git-worktree}/scripts/remove-worktree.sh" <worktree|branch> [--force] [--delete-branch]

Options

• --force: Remove even with uncommitted changes (changes lost!)
• --delete-branch: Also delete the branch after removing worktree

Troubleshoot

Diagnose and fix common worktree issues.

Flow

User: "troubleshoot worktrees"

Step 1: Locate bare repository
  scripts/detect-repo-type.sh
  → Find bare repo from current location

Step 2: Check core.bare
  → Should be 'true'
  → If wrong: Offer fix

Step 3: Check core.worktree
  → Should be unset (causes warnings if set)
  → If set: Offer fix

Step 4: Check stale entries
  → List prunable worktrees
  → Offer prune

Step 5: Check directory integrity
  → Missing worktree directories
  → Broken .git file links

Report:
  "RESULT: 2 issue(s) found

   ISSUE: core.worktree is set
   ISSUE: 1 stale worktree entry

   Run with --fix to repair:
     troubleshoot.sh --fix"

Script

"${SKILL_BASE:-$HOME/.claude/skills/git-worktree}/scripts/troubleshoot.sh" [path] [--fix] [--verbose]

Common Issues

Directory Structure

The skill uses a workspace-level WORKTREES pattern:

~/Documents/Workspace/claudecode/WORKTREES/
└── GITHUB/
    ├── ChristopherA/                    # GitHub user
    │   ├── repo-name/
    │   │   ├── repo-name.git/           # Bare repository
    │   │   ├── main/                    # Main branch worktree
    │   │   └── feature-auth/            # Feature branch worktree
    │   │
    │   └── another-repo/
    │       ├── another-repo.git/
    │       └── main/
    │
    └── BlockchainCommons/               # GitHub organization
        └── research/
            ├── research.git/
            ├── main/
            └── develop/

Why This Structure

• Mirrors GitHub URLs: github.com/{owner}/{repo} → WORKTREES/GITHUB/{owner}/{repo}
• Prevents name collisions: Different owners can have repos with same name
• Claude CLI compatible: Under ~/Documents/Workspace/claudecode/ for access
• Centralized: All worktree repos in one location

Branch to Directory Mapping

Rule: Replace / with - in directory names.

Scripts Reference

All scripts in ${SKILL_BASE:-$HOME/.claude/skills/git-worktree}/scripts/:

Environment Variables

Limitations

Not Supported (v1.0)

• Submodules: Repos with submodules cannot be converted
• GitHub Gists: Gists don't support branches/worktrees
• Non-GitHub remotes: Only GitHub URLs are parsed (GitLab, Bitbucket need manual owner)
• No remote repos: Requires GitHub remote for owner detection; add remote first with git remote add origin <url>

References

For advanced troubleshooting, load references/troubleshooting.md.

Git Worktree Skill v1.0.0 - December 2025