Create and manage Git worktrees for parallel development workflows. Use when multiple self-contained issues should NOT be fixed in a single branch, when human-Copilot iteration requires isolated environments with separate chat history and commits, or when parallel work items need independent build/test results. Triggers on requests involving branch isolation, work item separation, parallel development, or avoiding messy branch switching.
This skill provides helper scripts and workflows for creating and managing Git worktrees, enabling parallel development across multiple branches without cloning the repository multiple times.
Primary triggers — Create a new worktree when:
Multiple self-contained issues exist — Different problems should NOT be fixed together in a single branch. Each issue deserves its own branch with isolated commits, separate PR, and independent review.
Human-Copilot iteration is needed — Step-by-step collaboration requires an isolated environment where:
Parallel work avoids branch-switching chaos — Instead of constantly switching branches (which mixes up build artifacts, test results, and Copilot context), worktrees let you:
Anti-patterns — Do NOT use worktrees when:
This skill provides focused scripts for each worktree operation.
Create or reuse a worktree for an existing local or remote branch.
Location: ./scripts/New-WorktreeFromBranch.ps1
./scripts/New-WorktreeFromBranch.ps1 -Branch <branch-name> [-NoFetch]
| Parameter | Required | Default | Description |
|---|---|---|---|
-Branch | Yes | - | Branch name (local or origin/<name> form) |
-NoFetch | No | $false | Skip remote fetch if branch missing locally |
Examples:
# From a local or remote branch
./scripts/New-WorktreeFromBranch.ps1 -Branch feature/login
# From origin remote (normalizes automatically)
./scripts/New-WorktreeFromBranch.ps1 -Branch origin/bugfix/nullref
Start a new work item branch with consistent naming and create a worktree for it.
Location: ./scripts/New-WorktreeFromIssue.ps1
./scripts/New-WorktreeFromIssue.ps1 -Number <workitem-number> [-Title <description>] [-Base <ref>]
| Parameter | Required | Default | Description |
|---|---|---|---|
-Number | Yes | - | Azure DevOps work item number for branch naming |
-Title | No | - | Descriptive title (slugified into branch name) |
-Base | No | origin/main | Base ref to branch from |
Examples:
# Work item branch with title
./scripts/New-WorktreeFromIssue.ps1 -Number 1234 -Title "Crash on launch"
# Creates: workitem/1234-crash-on-launch
# Work item branch from different base
./scripts/New-WorktreeFromIssue.ps1 -Number 42 -Base origin/develop
# Simple work item branch (no title slug)
./scripts/New-WorktreeFromIssue.ps1 -Number 999
# Creates: workitem/999
Remove a worktree and optionally its associated branch.
Location: ./scripts/Delete-Worktree.ps1
./scripts/Delete-Worktree.ps1 -Pattern <pattern> [-Force] [-KeepBranch]
| Parameter | Required | Default | Description |
|---|---|---|---|
-Pattern | Yes | - | Partial branch name or path to match |
-Force | No | $false | Force removal even with uncommitted changes |
-KeepBranch | No | $false | Don't delete the local branch |
Examples:
# Delete worktree by branch pattern
./scripts/Delete-Worktree.ps1 -Pattern feature/perf-tweak
# Force delete with uncommitted changes
./scripts/Delete-Worktree.ps1 -Pattern workitem/1234 -Force
# Delete worktree but keep the branch
./scripts/Delete-Worktree.ps1 -Pattern feature/ui -KeepBranch
Use Git directly to list worktrees:
git worktree list --porcelain
./scripts/New-WorktreeFromIssue.ps1 -Number 1234 -Title "Fix null reference"
./scripts/Delete-Worktree.ps1 -Pattern workitem/1234
./scripts/New-WorktreeFromBranch.ps1 -Branch feature/login
./scripts/New-WorktreeFromBranch.ps1 -Branch feature/dashboard
| Source | Local Branch Name | Worktree Folder |
|---|---|---|
| Local/remote branch | Same as branch | <RepoName>-<hash>/ |
| Work item | workitem/<number>-<slug> | <RepoName>-<hash>/ |
Worktrees are created as sibling folders to the repository root (e.g., MyRepo/ and MyRepo-ab12/).
git fetch --all --prune periodically in the primary repo, not every worktree| Symptom | Solution |
|---|---|
| Cannot lock ref (*.lock error) | Run git worktree prune or delete stale .lock file manually |
| Worktree already exists | Use git worktree list to find existing path; reuse that folder |
| Local branch missing for remote | Run git branch --track <name> origin/<name> then retry |
| Submodules not initialized | Run git submodule update --init --recursive in the worktree |
# List all worktrees
git worktree list --porcelain
# List local branches with tracking info
git branch -vv
# List remotes
git remote -v
# Prune stale worktree references
git worktree prune
# Force remove a worktree with uncommitted changes
git worktree remove --force <path>
-Force flagAll implementation is self-contained within this skill folder:
Scripts (master source):
Human-friendly wrappers (in tools/git/):
tools/git/New-WorktreeFromBranch.cmd — delegates to skill's master scripttools/git/New-WorktreeFromIssue.cmd — delegates to skill's master scripttools/git/Delete-Worktree.cmd — delegates to skill's master scripttools/git/Worktree-Guidelines.md — quick reference for developers