Git worktree

Skill ChristopherA/claude_code_tools/skills/git-worktree

Session continuity skills for Claude Code - maintain context across coding sessions

Install

npx -y skills add ChristopherA/claude_code_tools --skill git-worktree

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Interactive skill for git worktree operations. Safely converts standard repos to worktree form, creates/lists/removes worktrees, and troubleshoots issues. Uses WORKTREES/GITHUB/{owner}/{repo}/ workspace structure for organization. Preserves inception commits (Open Integrity pattern) during conversion. WHEN: User says "clone worktree", "create worktree from", "get worktree from", "convert to worktree", "create worktree for", "list worktrees", "remove worktree", "troubleshoot worktrees", "validate worktree", OR mentions working with multiple branches simultaneously. WHEN NOT: Standard git operations (commit, push, pull), single-branch workflows, or when user explicitly wants standard repo structure.

SKILL.md

12.8 KB, as published. Nobody here has run it

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, [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

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

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

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

Git worktree

One thing to look at

What its author says it does

SKILL.md

Git Worktree Skill

Contents

Commands

Clone as Worktree

Flow

Script

Convert to Worktree Form

Flow

Script

Options

Create Worktree

Flow

Script

Branch Type Recognition

List Worktrees

Flow

Script

Output Formats

Remove Worktree

Flow

Script

Options

Troubleshoot

Flow

Script

Common Issues

Directory Structure

Why This Structure

Branch to Directory Mapping

Scripts Reference

Environment Variables

Limitations

Not Supported (v1.0)

References

Keep looking