git-branching-worktrees
Manage Git feature branches and isolated Git worktrees for concurrent tasks without context-switching overhead or stashing conflicts. Use when creating feature branches, running multi-agent tasks simu
SKILL.mdskills/git-branching-worktrees/SKILL.md
GitHubGit Branching and Worktrees
Managing parallel streams of development without polluting the working tree is essential for collaborative engineering and multi-agent workflows. This skill provides standard procedures for branch lifecycle management and Git worktrees—allowing multiple branches to be checked out simultaneously in separate directories sharing the same repository storage.
Core Rules
- Base branches on fresh upstream state: Never branch off an outdated local branch without fetching upstream first.
- Use descriptive branch naming conventions: Follow
type/short-description(e.g.,feat/auth-token-refresh,fix/null-pointer-header). - Never switch branches with dirty uncommitted changes: Use commits, stashes, or better yet, Git worktrees.
- Clean up after merge: Remove merged local and remote branches and pruned worktrees to prevent workspace clutter.
- Never delete a worktree directory manually: Use
git worktree removeto keep Git internal metadata synchronized.
1. Branch Management Workflow
Creating a Feature Branch
# 1. Fetch latest upstream changes
git fetch origin
# 2. Create and switch to new branch based on up-to-date main
git switch -c feat/oauth-pkce-support origin/main
# Or in older Git:
# git checkout -b feat/oauth-pkce-support origin/main
Inspecting Branch Status
# List local branches with their upstream tracking and commit status
git branch -vv
# Check which branches are merged into main
git branch --merged main
# Check which branches are not yet merged
git branch --no-merged main
Cleaning Up Merged Branches
# Delete a merged local branch
git branch -d feat/oauth-pkce-support
# If remote branch was merged via PR on GitHub:
git remote prune origin
2. Git Worktrees: Parallel Workspace Isolation
Git worktrees allow having multiple working directories attached to the same .git repository. Each worktree is checked out to a different branch. This enables running tests, building, or running subagents in parallel without branch-switching collisions.
Key Benefits for Agents
- No need to
git stashwhen interrupted by a high-priority bugfix. - Subagents can work in isolated directories without touching the primary branch.
- Zero extra disk clone overhead: object database is shared.
Creating a Worktree
# Syntax: git worktree add <path> <branch>
# Option A: Create a worktree with a new branch based on origin/main
git worktree add ../worktrees/fix-auth-leak -b fix/auth-leak origin/main
# Option B: Checkout an existing branch into a worktree
git worktree add ../worktrees/review-pr-42 feat/user-dashboard
Inspecting Worktrees
# List all active worktrees and their checked-out branches
git worktree list
# Output:
# /Users/dev/repo 0a1b2c3 [main]
# /Users/dev/worktrees/fix-auth-leak 4d5e6f7 [fix/auth-leak]
Safe Worktree Removal
# 1. Ensure any changes in the worktree are committed or discarded
cd ../worktrees/fix-auth-leak && git status
# 2. From the main repository directory, remove the worktree
cd /Users/dev/repo
git worktree remove ../worktrees/fix-auth-leak
# 3. Clean up internal metadata and stale worktree references
git worktree prune
3. Common Mistakes and Anti-Patterns
| Anti-Pattern | Risk | Correct Practice |
|---|---|---|
rm -rf <worktree-dir> |
Leaves orphaned administrative files in .git/worktrees |
Use git worktree remove <path> and git worktree prune |
| Checking out the same branch in 2 worktrees | Git prevents this to avoid index corruption | Always use a dedicated branch per worktree |
| Branching from dirty un-fetched local branch | Inherits stale commits or unintentional edits | Fetch first, then branch explicitly from origin/main |
Using git branch -D blindly |
Force deletes unmerged work permanently | Use -d first; verify with git log before forcing deletion |
4. Real-World Scenarios
Scenario A: Urgent Production Hotfix While Working on a Large Feature
You are halfway through a refactor on feat/data-pipeline with multiple modified files. A critical bug is reported in production.
# Do NOT stash or discard your changes.
# Create an isolated worktree for the hotfix:
git worktree add ../hotfix-session-crash -b fix/session-crash origin/main
# Move to the isolated hotfix directory
cd ../hotfix-session-crash
# Implement fix, test, and commit
pytest tests/test_session.py
git commit -am "fix(session): handle unexpected null payload gracefully"
# Push hotfix branch
git push origin fix/session-crash
# Return to your main repository and remove hotfix worktree
cd /Users/dev/repo
git worktree remove ../hotfix-session-crash
# Your feature workspace in /Users/dev/repo is completely untouched!
Scenario B: Pruning Stale Branches and Orphaned Worktree Records
# 1. Prune remote tracking branches deleted on GitHub
git fetch --prune origin
# 2. List worktrees to identify dead directories
git worktree list
# 3. Prune dangling worktree metadata
git worktree prune
# 4. Safely remove merged local branches
git branch --merged origin/main | grep -v '^[ *]*main$' | xargs git branch -d
5. Verification Checklist
- New branch is created from the correct upstream baseline (
origin/main). -
git branch -vvconfirms tracking configuration. -
git worktree listdisplays only active, existing directory paths. - Removed worktrees leave no dangling administrative references (
git worktree prunereports nothing).