submodule-worktree

Submodule & Repo Worktree Management

Worktrees let you check out multiple branches simultaneously — each worktree is a separate directory backed by the same .git store. This skill handles worktrees for both the top-level repo and any submodules within it.

Layout

workspace/
├── worktrees/                         # All worktrees (gitignored)
│   ├── _root/                         # Top-level repo worktrees
│   │   └── feature-something/         # branch: feature/something
│   ├── my-submodule/                  # Submodule worktrees (by basename)
│   │   └── feature-branch/            # branch: feature/branch
│   └── another-submodule/
│       └── fix-bug/

Script

All operations use the portable script shipped with this skill:

WORKTREE_SH="$HOME/.cursor/skills/submodule-worktree/scripts/worktree.sh"

Run it from anywhere inside the workspace.

First-time setup

The script auto-detects the git root and submodules. You only need to ensure:

1. worktrees/ is in the workspace .gitignore
2. Submodules are initialized (git submodule update --init)

echo 'worktrees/' >> .gitignore
git submodule update --init --recursive

Create a worktree

# Top-level repo worktree
$WORKTREE_SH add _root feature/my-branch

# Submodule worktree (use submodule basename, not full path)
$WORKTREE_SH add mdxjs-rs feature/vite-plugin

# Explicitly create a new branch
$WORKTREE_SH add mdxjs-rs feature/new-thing --new

# Base a new branch off a specific ref
$WORKTREE_SH add mdxjs-rs feature/speed-up --base main

# Combine flags
$WORKTREE_SH add mdxjs-rs hotfix/urgent --new --base v2.1.0

List active worktrees

# All targets with worktrees
$WORKTREE_SH list

# Specific target
$WORKTREE_SH list mdxjs-rs
$WORKTREE_SH list _root

Remove a worktree

$WORKTREE_SH remove mdxjs-rs feature/vite-plugin
$WORKTREE_SH remove _root feature/my-branch

Status overview

$WORKTREE_SH status