name: UsingGitWorktrees description: Creates isolated git worktrees in XDG data directory for parallel development. USE WHEN starting feature work that needs isolation from current workspace OR before executing implementation plans OR working on multiple branches simultaneously OR need clean test environment. Creates worktrees in ~/.local/share/worktrees///.

UsingGitWorktrees

Create isolated git workspaces for parallel development using XDG data directory layout.

Overview

Git worktrees create isolated working directories that share the same repository, allowing:

Work on multiple branches simultaneously
Isolated test environments
Clean baseline for new features
No stashing or switching required

Core principle: All worktrees live in ~/.local/share/worktrees/ following XDG conventions, consistent with lazyworktree.

Announce at start: “I’m using the UsingGitWorktrees skill to set up an isolated workspace.”

XDG Data Layout

All worktrees are organized under ~/.local/share/worktrees/:

~/.local/share/worktrees/
├── vdemeester/
│   ├── home/
│   │   ├── main/
│   │   └── feature-new-host/
│   └── tektoncd-plumbing/
│       ├── main/
│       └── feature-terraform-branch-protection/
└── tektoncd/
    └── pipeline/
        ├── main/
        └── feature-new-resolver/

Structure: ~/.local/share/worktrees/<org>/<repo>/<branch>/

Benefits

XDG compliant: Follows standard data directory conventions
Centralized: All worktrees in one global location
No .gitignore needed: Worktrees aren’t inside any repo
Consistent with lazyworktree: Same layout as lazyworktree’s default
Organization aware: Grouped by org/owner and repo
Clean source directories: Your ~/src/ stays clean

vs. Other Layouts (NOT used)

Aspect	XDG Data Layout	Nested Layout	Sibling Layout
Location	`~/.local/share/worktrees/`	Inside repo (`.worktrees/`)	Project parent folder
Requires .gitignore	No	Yes	No
Centralized	Yes	No	No
lazyworktree compatible	Yes (default)	No	Partial

Determining Org and Repo

Extract organization and repository name from git remote:

# Get remote URL
REMOTE_URL=$(git remote get-url origin)

# Parse org/repo from various URL formats
# SSH: git@github.com:tektoncd/pipeline.git
# HTTPS: https://github.com/tektoncd/pipeline.git
# HTTPS with auth: https://user@github.com/tektoncd/pipeline.git

if [[ "$REMOTE_URL" =~ git@[^:]+:([^/]+)/([^/.]+) ]]; then
    ORG="${BASH_REMATCH[1]}"
    REPO="${BASH_REMATCH[2]}"
elif [[ "$REMOTE_URL" =~ https://[^/]+/([^/]+)/([^/.]+) ]]; then
    ORG="${BASH_REMATCH[1]}"
    REPO="${BASH_REMATCH[2]}"
fi

# Remove .git suffix if present
REPO="${REPO%.git}"

Worktree Creation

Step 1: Determine Paths

# Base directory for all worktrees
WORKTREE_BASE="$HOME/.local/share/worktrees"

# Get org and repo from remote
REMOTE_URL=$(git remote get-url origin)
# ... parse ORG and REPO as above ...

# Sanitize branch name for filesystem
BRANCH_NAME="feature/user-authentication"
BRANCH_PATH=$(echo "$BRANCH_NAME" | tr '/' '-')  # feature-user-authentication

# Full worktree path
WORKTREE_PATH="$WORKTREE_BASE/$ORG/$REPO/$BRANCH_PATH"

Step 2: Create Worktree

# Create directory structure
mkdir -p "$WORKTREE_BASE/$ORG/$REPO"

# Create worktree and branch in one command
git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"

# Navigate to new worktree
cd "$WORKTREE_PATH"

Alternative - checkout existing branch:

# If branch already exists
git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

Step 3: Auto-Detect and Run Project Setup

Detect project type and install dependencies:

# Node.js / JavaScript
if [ -f package.json ]; then
    npm install
fi

# Rust
if [ -f Cargo.toml ]; then
    cargo build
fi

# Python
if [ -f pyproject.toml ]; then
    uv sync  # Prefer uv over pip
elif [ -f requirements.txt ]; then
    uv pip install -r requirements.txt
fi

# Go
if [ -f go.mod ]; then
    go mod download
fi

# NixOS (from home repository pattern)
if [ -f flake.nix ]; then
    nix develop --command bash -c "echo 'Development environment ready'"
fi

Step 4: Verify Clean Baseline

Run tests to ensure worktree starts in working state:

# Node.js
npm test

# Rust
cargo test

# Python
pytest

# Go
go test ./...

# NixOS
nix build
# OR
make build

If tests fail:

Report failures clearly
Ask whether to proceed or investigate
Document known issues

If tests pass:

Report success
Show test count and duration
Confirm ready for work

Step 5: Report Worktree Ready

Worktree created successfully

Location: ~/.local/share/worktrees/myorg/myrepo/feature-user-authentication
Branch: feature/user-authentication
Tests: ✓ 47 passing (2.3s)

Ready to implement user authentication feature

Managing Worktrees

List All Worktrees

git worktree list

Output:

/home/user/src/myorg/myrepo                                           abc1234 [main]
/home/user/.local/share/worktrees/myorg/myrepo/feature-auth           def5678 [feature/auth]
/home/user/.local/share/worktrees/myorg/myrepo/bugfix-db              ghi9012 [bugfix/database]

Navigate to Worktree

# Direct path
cd ~/.local/share/worktrees/myorg/myrepo/feature-auth

# Or use lazyworktree for interactive selection
lazyworktree

Remove Worktree

# Remove worktree (keeps branch)
git worktree remove ~/.local/share/worktrees/myorg/myrepo/feature-auth

# Force remove (even with uncommitted changes)
git worktree remove --force ~/.local/share/worktrees/myorg/myrepo/feature-auth

Prune Deleted Worktrees

# Clean up references to manually deleted worktrees
git worktree prune

Quick Reference

Situation	Action
Create new worktree	`git worktree add ~/.local/share/worktrees/<org>/<repo>/<branch> -b <branch>`
Navigate to worktree	`cd ~/.local/share/worktrees/<org>/<repo>/<branch>` or use `lazyworktree`
List worktrees	`git worktree list`
Remove worktree	`git worktree remove <path>`
Cleanup references	`git worktree prune`
Check current branch	`git branch --show-current`

Common Patterns for Your Home Repository

Based on your NixOS home repository structure:

Building a NixOS Configuration

# From your main home repo at ~/src/home
git worktree add ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade -b feature/sakhalin-upgrade

cd ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade

# Build without affecting main worktree
make host/sakhalin/build

# If successful, deploy
make host/sakhalin/switch

Working on Multiple Hosts

# Multiple worktrees for different hosts
git worktree add ~/.local/share/worktrees/vdemeester/home/rhea-jellyfin -b feature/rhea-jellyfin
git worktree add ~/.local/share/worktrees/vdemeester/home/aion-audio -b feature/aion-audio

# Work on both simultaneously
cd ~/.local/share/worktrees/vdemeester/home/rhea-jellyfin
make host/rhea/build

cd ~/.local/share/worktrees/vdemeester/home/aion-audio
make host/aion/build

Working on Tekton Pipeline

# Create worktree for pipeline feature
cd ~/src/tektoncd/pipeline/main
git worktree add ~/.local/share/worktrees/tektoncd/pipeline/feature-new-resolver -b feature/new-resolver

cd ~/.local/share/worktrees/tektoncd/pipeline/feature-new-resolver
go test ./...

Integration with lazyworktree

The XDG data layout is consistent with lazyworktree’s default behavior:

# Use lazyworktree to navigate between worktrees
lazyworktree

# Use aliases defined in your config
wh   # Jump to home worktrees
wtp  # Jump to tekton pipeline worktrees

lazyworktree provides:

Interactive worktree selection
PR/issue integration
Quick branch creation
Worktree management UI

Common Mistakes

❌ Creating Worktrees in Random Locations

Problem: Worktrees scattered across filesystem Fix: Always use ~/.local/share/worktrees/<org>/<repo>/

❌ Forgetting Org/Repo Structure

Problem: Flat structure makes it hard to find worktrees Fix: Always include org and repo in path

❌ Proceeding with Failing Tests

Problem: Can’t distinguish new bugs from pre-existing issues Fix: Report failures, get explicit permission to proceed

❌ Forgetting to Remove Old Worktrees

Problem: Disk space waste, confusion about active work Fix: Regularly run git worktree list and remove completed work

❌ Committing from Wrong Worktree

Problem: Changes go to wrong branch Fix: Always verify current branch before committing: git branch --show-current

Integration with Other Skills

Before UsingGitWorktrees:

Use Brainstorming to clarify what feature needs isolation
Ensure design is validated before creating worktree

After UsingGitWorktrees:

Use WritingPlans to create implementation plan
Use TestDrivenDevelopment for implementation in worktree
Use Git skill for branching and commit workflows

Cleanup after work:

# From main repo, merge work back
git merge feature/user-authentication

# Remove worktree
git worktree remove ~/.local/share/worktrees/myorg/myrepo/feature-user-authentication

# Delete branch if done
git branch -d feature/user-authentication

Examples

Example 1: Creating a worktree for a new feature

User: "Set up worktree for new authentication feature"

→ Invoke UsingGitWorktrees skill
→ Announce: "I'm using the UsingGitWorktrees skill to set up an isolated workspace"
→ Parse remote: git@github.com:myorg/myrepo.git → org=myorg, repo=myrepo
→ Create: git worktree add ~/.local/share/worktrees/myorg/myrepo/feature-auth -b feature/auth
→ Setup: npm install
→ Test: npm test → 47 passing
→ Report: "Worktree ready at ~/.local/share/worktrees/myorg/myrepo/feature-auth"

Example 2: Working on home repository

User: "Create worktree for sakhalin upgrade"

→ Invoke UsingGitWorktrees skill
→ Parse remote: git@github.com:vdemeester/home.git → org=vdemeester, repo=home
→ Create: git worktree add ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade -b feature/sakhalin-upgrade
→ Setup: nix develop
→ Build: make dry-build → success
→ Report: "Worktree ready at ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade"

Example 3: Parallel host configurations

User: "I need to work on both rhea and aion configurations simultaneously"

→ Invoke UsingGitWorktrees skill
→ Create: ~/.local/share/worktrees/vdemeester/home/rhea-jellyfin
→ Create: ~/.local/share/worktrees/vdemeester/home/aion-audio
→ Both worktrees have clean baselines
→ Can build and test both in parallel
→ Use lazyworktree to switch between them

Example 4: Cleanup after merge

User: "Clean up the authentication worktree now that it's merged"

→ Verify feature branch merged: git branch --merged
→ Remove: git worktree remove ~/.local/share/worktrees/myorg/myrepo/feature-auth
→ Delete branch: git branch -d feature/auth
→ Confirm: git worktree list shows worktree removed

Red Flags

Never:

Create worktrees outside ~/.local/share/worktrees/
Skip org/repo structure in path
Proceed with failing tests without explicit permission
Leave old worktrees around indefinitely
Commit to wrong branch (verify with git branch --show-current)

Always:

Use XDG data directory: ~/.local/share/worktrees/<org>/<repo>/<branch>
Parse org/repo from git remote
Auto-detect and run project setup
Verify clean test baseline
Report clear status when worktree is ready
Clean up worktrees when work is merged
Use lazyworktree for navigation when available