# Christophera Claude Code Tools Git Worktree

> Git Worktree Skill

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

---


# Git Worktree Skill

## Contents

1. [Commands](#commands)
2. [Clone as Worktree](#clone-as-worktree)
3. [Convert to Worktree Form](#convert-to-worktree-form)
4. [Create Worktree](#create-worktree)
5. [List Worktrees](#list-worktrees)
6. [Remove Worktree](#remove-worktree)
7. [Troubleshoot](#troubleshoot)
8. [Directory Structure](#directory-structure)
9. [Scripts Reference](#scripts-reference)

---

## Commands

| Trigger | Action |
|---------|--------|
| "clone worktree from {url}" | Clone GitHub repo directly into worktree form |
| "get worktree from {repo}" | Same as clone (natural language variant) |
| "create worktree from {url}" | Same as clone |
| "convert to worktree" | Convert current repo to worktree form |
| "create worktree for {branch}" | Add worktree for branch |
| "list worktrees" | Show all worktrees with status |
| "remove worktree {name}" | Safely remove worktree |
| "troubleshoot worktrees" | Diagnose and fix issues |
| "validate worktree" | Check configuration |

**Recognition patterns**:
- GitHub URLs: `https://github.com/owner/repo`, `git@github.com: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

```bash
"${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

```bash
"${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

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

### Branch Type Recognition

| Prefix | Type | Description |
|--------|------|-------------|
| `feature/` | Feature | New feature development |
| `bugfix/`, `fix/` | Bugfix | Bug fixes |
| `hotfix/` | Hotfix | Emergency fixes |
| `docs/` | Documentation | Documentation changes |
| `refactor/` | Refactor | Code improvements |
| `release/` | Release | Release preparation |
| `experiment/` | Experiment | Exploration/POC |

---

## 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

```bash
"${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

```bash
"${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

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

### Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| core.bare not true | Manual config change | `git config core.bare true` |
| core.worktree set | Clone artifact | `git config --unset core.worktree` |
| Stale entries | Deleted worktree dirs | `git worktree prune` |
| Broken links | Moved directories | Recreate worktree |

---

## 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

| Branch | Directory |
|--------|-----------|
| `main` | `main/` |
| `develop` | `develop/` |
| `feature/foo-bar` | `feature-foo-bar/` |
| `bugfix/issue-123` | `bugfix-issue-123/` |

Rule: Replace `/` with `-` in directory names.

---

## Scripts Reference

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

| Script | Purpose | Exit Codes |
|--------|---------|------------|
| `clone-as-worktree.sh` | Clone GitHub URL into worktree form | 0=success, 1=args, 2=failed |
| `convert-to-worktree.sh` | Convert local repo to worktree form | 0=success, 1=precond, 2=failed |
| `create-worktree.sh` | Add worktree for branch | 0=success, 1=precond, 2=failed |
| `detect-inception.sh` | Find signed inception commit | 0=found/none, 1=error |
| `detect-repo-type.sh` | Detect STANDARD/WORKTREE/BARE | 0=detected, 1=not repo |
| `extract-owner.sh` | Parse owner/repo from remote | 0=found, 1=no remote |
| `list-worktrees.sh` | Show all worktrees | 0=success, 1=not worktree |
| `remove-worktree.sh` | Safely remove worktree | 0=success, 1=changes, 2=failed |
| `troubleshoot.sh` | Diagnose and fix issues | 0=clean, 1=issues, 2=fatal |
| `validate-setup.sh` | Verify configuration | 0=valid, 1=issues |

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `WORKTREE_ROOT` | `~/Documents/Workspace/claudecode/WORKTREES` | Root for all worktree repos |
| `GITHUB_HOST` | `GITHUB` | Subdirectory for GitHub repos |
| `DRY_RUN` | `0` | Set to 1 for preview mode |

---

## 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*

---
> Source: [christophera/claude_code_tools](https://github.com/christophera/claude_code_tools) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-19 -->