Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-agentskillos-36k/skillsmp/git-worktrees/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill git-worktrees. Copyright stays with the author.

Git Worktrees for Issue-Driven Development

Manage git worktrees for parallel feature development in the Langstar project. Create worktrees with correct target branches based on issue hierarchy, handle cleanup after PR merge, and maintain worktree hygiene.

Overview

Git worktrees enable working on multiple branches simultaneously without switching context. In Langstar's issue-driven workflow, worktrees support parallel development while respecting the hierarchical PR flow where child issues branch from parent issue branches.

Key Benefits:

Work on multiple issues simultaneously without branch switching
Maintain correct branch hierarchy for sub-issues
Isolated working directories prevent context confusion
Clean separation between main worktree and feature branches

Project Branching Conventions

Understanding Langstar's branching structure is critical for correct worktree usage.

Branch Naming Convention

Format variations:

With milestone & parent: m<milestone_id>-p<parent_id>-i<issue_num>-<issue_slug>
With parent only: p<parent_id>-i<issue_num>-<issue_slug>
With milestone only: m<milestone_id>-i<issue_num>-<issue_slug>
Standalone: i<issue_num>-<issue_slug>

Examples:

m8-p123-i234-add-authentication
p129-i132-gh-sub-issue
i7-add-authentication

Issue Hierarchy and PR Flow

Key Rule: Each PR closes exactly one issue. When issues have parent-child relationships, PRs follow the hierarchy:

Issue #333 (parent)
  ↑ PR from: user/333-kingdom
  ↑ Based on: user/666-phylum

Issue #666 (child of #333)
  ↑ PR from: user/666-phylum
  ↑ Based on: user/999-class

Issue #999 (child of #666)
  ↑ PR from: user/999-class
  ↑ Based on: main (or release/v0.2.0)

Implications for Worktrees:

Sub-issues must branch from parent issue's feature branch
Top-level issues branch from main or release branch
Target branch selection depends on issue hierarchy

Worktree Location Convention

Standard location: wip/ directory (gitignored)

Naming pattern: wip/<branch-name>/

Example mappings:

Branch: i130-add-authentication → Worktree: wip/i130-add-authentication/
Branch: m8-p123-i234-add-auth → Worktree: wip/m8-p123-i234-add-auth/

The wip/ directory is already configured in .gitignore, keeping worktrees out of version control.

Core Commands

Create Worktree

Command: git worktree add -b <branch-name> <path> <target-branch>

Creates a new worktree with a new branch based on the specified target branch.

Template:

git worktree add -b <branch-name> wip/<branch-name> <target-branch>

Examples:

# Standalone issue
git worktree add -b i130-add-auth wip/i130-add-auth main

# Issue with milestone and parent
git worktree add -b m8-p123-i234-add-auth wip/m8-p123-i234-add-auth main

Example 1: Top-level issue branching from release branch

# Issue #130: Add authentication (top-level)
# Target: release/v0.2.0
git worktree add -b codekiln/130-add-authentication wip/codekiln-130-add-authentication release/v0.2.0

Example 2: Sub-issue branching from parent's feature branch

# Issue #135: Implement JWT (child of #130)
# Target: codekiln/130-add-authentication (parent branch)
git worktree add -b codekiln/135-implement-jwt wip/codekiln-135-implement-jwt codekiln/130-add-authentication

What it does:

Creates new directory at specified path
Creates new branch from target branch
Checks out the new branch in the worktree
Links worktree to main repository

List Worktrees

Command: git worktree list

Displays all worktrees with path, commit hash, branch name, and status.

Usage:

git worktree list           # Basic list
git worktree list -v        # Verbose with lock status
git worktree list --porcelain  # Script-friendly format

Remove Worktree

Command: git worktree remove <path>

Removes a worktree after PR merge. Must be run from outside the worktree being removed.

Usage:

git worktree remove wip/codekiln-130-auth              # Standard
git worktree remove --force wip/codekiln-130-auth     # Force (with changes)
git worktree remove --force --force wip/locked        # Remove locked

Prune Stale Worktrees

Command: git worktree prune

Cleans up administrative files for manually deleted worktrees.

Usage:

git worktree prune --dry-run    # Preview
git worktree prune --verbose    # Prune with output

Workflows

Workflow 1: Create Worktree for Top-Level Issue

Scenario: Working on issue that branches directly from main or release branch.

Steps:

# Step 1: Identify target branch
# For features: main
# For releases: release/vX.Y.Z
TARGET_BRANCH="release/v0.2.0"

# Step 2: Determine branch name from issue
# Issue #130: "Add user authentication" (standalone, no milestone/parent)
BRANCH_NAME="i130-add-authentication"
WORKTREE_PATH="wip/i130-add-authentication"

# Step 3: Create worktree
git worktree add -b $BRANCH_NAME $WORKTREE_PATH $TARGET_BRANCH

# Step 4: Navigate to worktree
cd $WORKTREE_PATH

# Step 5: Verify setup
git status
git log -1

Result: New worktree ready for development on issue #130.

Workflow 2: Create Worktree for Sub-Issue

Scenario: Working on sub-issue that must branch from parent issue's feature branch.

Steps:

# Step 1: Query parent issue
# Issue #135 is child of #130
gh sub-issue list 135 --relation parent

# Output shows: #130 - Add user authentication

# Step 2: Identify parent branch
PARENT_BRANCH="codekiln/130-add-authentication"

# Step 3: Verify parent branch exists locally
git branch --list $PARENT_BRANCH

# If not exists, fetch it
if [ -z "$(git branch --list $PARENT_BRANCH)" ]; then
  git fetch origin $PARENT_BRANCH:$PARENT_BRANCH
fi

# Step 4: Create worktree from parent branch
BRANCH_NAME="codekiln/135-implement-jwt"
WORKTREE_PATH="wip/codekiln-135-implement-jwt"

git worktree add -b $BRANCH_NAME $WORKTREE_PATH $PARENT_BRANCH

# Step 5: Link issues (if not already linked)
gh sub-issue add 130 135

# Step 6: Navigate and verify
cd $WORKTREE_PATH
git log -1

Result: Worktree for sub-issue #135 correctly branching from parent #130's branch.

Workflow 3: Cleanup After PR Merge

Scenario: PR has been merged, need to clean up worktree.

Steps:

# Step 1: Ensure you're in main worktree
cd /workspace

# Step 2: Pull latest changes from remote
git checkout release/v0.2.0
git pull origin release/v0.2.0

# Step 3: Remove merged worktree
git worktree remove wip/codekiln-130-add-authentication

# Step 4: Delete local branch (optional)
git branch -d codekiln/130-add-authentication

# If branch not fully merged to current HEAD, force delete
# git branch -D codekiln/130-add-authentication

# Step 5: Prune stale references
git worktree prune

Result: Clean workspace with merged work removed.

Workflow 4: Handle Stale Worktrees

Scenario: Worktree directories deleted manually or PR merged remotely.

Steps:

# Step 1: List all worktrees
git worktree list

# Identify stale worktrees (directories no longer exist)

# Step 2: Preview pruning
git worktree prune --dry-run --verbose

# Step 3: Prune stale references
git worktree prune --verbose

# Step 4: Remove any remaining worktree directories manually
# (if needed)
rm -rf wip/old-worktree-name

# Step 5: Verify cleanup
git worktree list

Result: All stale worktree references cleaned up.

Integration with Other Skills

With `gh-sub-issue` Skill

Use gh-sub-issue to determine correct target branches for sub-issues.

Query parent to find target branch:

gh sub-issue list 135 --relation parent
# Output: #130 - Add user authentication
# Branch from: codekiln/130-add-authentication

Create worktree and link:

git worktree add -b codekiln/135-jwt wip/codekiln-135-jwt codekiln/130-add-authentication
gh sub-issue add 130 135  # Link if not already linked

With `github-issue-breakdown` Skill

After breaking down epic into sub-issues, create worktrees from parent branch:

# Epic #100 broken down into #101, #102, #103
git worktree add -b codekiln/100-auth wip/codekiln-100-auth main
git worktree add -b codekiln/101-research wip/codekiln-101-research codekiln/100-auth
git worktree add -b codekiln/102-implement wip/codekiln-102-implement codekiln/100-auth

With Project GitHub Workflow

PR creation from worktrees:

cd wip/codekiln-130-add-authentication
git push -u origin codekiln/130-add-authentication
gh pr create --title "✨ feat: add authentication" --body "Fixes #130"

Best Practices

Location and Naming

✅ Always use wip/ directory

Already gitignored
Consistent location for all worktrees
Easy to find and manage

✅ Use consistent naming

Worktree path matches branch name
Example: i130-add-auth → wip/i130-add-auth

❌ Avoid

Random locations (../temp, ~/worktrees/random)
Vague names (wip/test, wip/tmp)

Target Branch Selection

✅ Top-level issues:

Branch from main for regular features
Branch from release/vX.Y.Z for release-specific work

✅ Sub-issues:

Use gh sub-issue list <issue> --relation parent to find parent
Branch from parent issue's feature branch
Example: codekiln/135-jwt branches from codekiln/130-auth

❌ Avoid

Guessing parent branch names
Branching sub-issues from main (breaks PR hierarchy)
Creating worktrees without verifying target branch exists

Cleanup Hygiene

✅ Remove worktrees after PR merge

cd /workspace
git worktree remove wip/codekiln-130-add-authentication

✅ Run git worktree prune periodically

git worktree prune --verbose

✅ Delete branches after merge (optional)

git branch -d codekiln/130-add-authentication

❌ Avoid

Leaving stale worktrees around indefinitely
Accumulating dozens of old worktrees
Manually deleting worktree directories without git worktree remove

Development Workflow

✅ Switch to main worktree before cleanup

cd /workspace  # Main worktree
git worktree remove wip/old-feature

✅ Verify target branch before creating worktree

git branch --list codekiln/130-add-authentication
# If empty, fetch it first

✅ Use descriptive paths matching issue numbers

Makes it obvious which worktree corresponds to which issue

❌ Avoid

Removing worktrees while inside them (causes errors)
Creating worktrees from non-existent target branches
Mixing conventions (some in wip/, some elsewhere)

Troubleshooting

"fatal: invalid reference" - Target branch missing. Fetch it: git fetch origin <branch>:<branch>

"fatal: '' already exists" - Remove existing: git worktree remove <path> or rm -rf <path>

"fatal: '' is not a working tree" - Run git worktree prune then rm -rf <path>

"fatal: cannot remove a locked working tree" - Unlock: git worktree unlock <path> or force: git worktree remove --force --force <path>

Directory deleted manually - Clean up: git worktree prune --verbose

Wrong base branch - Remove and recreate with correct target from gh sub-issue list <issue> --relation parent

Environment Requirements

Prerequisites: Git 2.5+, wip/ in .gitignore, gh CLI (for issue queries)

Verification: git --version and git check-ignore wip/ (should output: wip/)

Command Reference

Command	Purpose
`git worktree add -b <branch> <path> <target>`	Create worktree
`git worktree list [-v]`	List all worktrees
`git worktree remove [--force] <path>`	Remove worktree
`git worktree prune [--dry-run]`	Clean stale references
`git worktree lock/unlock <path>`	Prevent/allow removal

Complete Workflow

# Find parent (for sub-issues)
gh sub-issue list 135 --relation parent

# Create worktree
git worktree add -b codekiln/135-jwt wip/codekiln-135-jwt codekiln/130-auth

# Work and push
cd wip/codekiln-135-jwt
git push -u origin codekiln/135-jwt
gh pr create --title "✨ feat: JWT" --body "Fixes #135"

# After merge
cd /workspace
git worktree remove wip/codekiln-135-jwt
git branch -d codekiln/135-jwt
git worktree prune

git-worktrees

About

Git Worktrees for Issue-Driven Development

Overview

Project Branching Conventions

Branch Naming Convention

Issue Hierarchy and PR Flow

Worktree Location Convention

Core Commands

Create Worktree

List Worktrees

Remove Worktree

Prune Stale Worktrees

Workflows

Workflow 1: Create Worktree for Top-Level Issue

Workflow 2: Create Worktree for Sub-Issue

Workflow 3: Cleanup After PR Merge

Workflow 4: Handle Stale Worktrees

Integration with Other Skills

With `gh-sub-issue` Skill

With `github-issue-breakdown` Skill

With Project GitHub Workflow

Best Practices

Location and Naming

Target Branch Selection

Cleanup Hygiene

Development Workflow

Troubleshooting

Environment Requirements

Command Reference

Complete Workflow

See Also

Use it

Manifest

Reviews

About

Git Worktrees for Issue-Driven Development

Overview

Project Branching Conventions

Branch Naming Convention

Issue Hierarchy and PR Flow

Worktree Location Convention

Core Commands

Create Worktree

List Worktrees

Remove Worktree

Prune Stale Worktrees

Workflows

Workflow 1: Create Worktree for Top-Level Issue

Workflow 2: Create Worktree for Sub-Issue

Workflow 3: Cleanup After PR Merge

Workflow 4: Handle Stale Worktrees

Integration with Other Skills

With gh-sub-issue Skill

With github-issue-breakdown Skill

With Project GitHub Workflow

Best Practices

Location and Naming

Target Branch Selection

Cleanup Hygiene

Development Workflow

Troubleshooting

Environment Requirements

Command Reference

Complete Workflow

See Also

Use it

Manifest

Reviews

With `gh-sub-issue` Skill

With `github-issue-breakdown` Skill