When to Invoke This Skill
- Creating isolated worktree for issue work
- Listing all active worktrees
- Removing worktree after issue merged
- Checking worktree status
- Troubleshooting worktree issues
Git Worktree Overview
Git worktrees allow multiple working directories from a single repository:
- Each worktree can be on a different branch
- Changes in one worktree don't affect others
- Perfect for parallel issue work
- Cleaner than stashing or multiple clones
Standard Workflows
#### Creating a Worktree
1. Ensure Worktrees Directory Exists
```bash
mkdir -p worktrees
```
2. Verify Worktree Doesn't Already Exist
```bash
git worktree list | grep "worktrees/issue-$ISSUE_NUMBER"
```
If exists, inform user and ask if they want to remove and recreate.
3. Create Worktree from Main
```bash
# Ensure main is up to date
git fetch origin main
# Create worktree with new branch
git worktree add -b feature/issue-$ISSUE_NUMBER worktrees/issue-$ISSUE_NUMBER origin/main
```
Branch Naming Convention:
feature/issue-$N - New featuresfix/issue-$N - Bug fixesrefactor/issue-$N - Refactoringdocs/issue-$N - Documentation
Determine prefix by analyzing issue labels/title.
4. Verify Creation
```bash
git worktree list
ls -la worktrees/issue-$ISSUE_NUMBER
```
5. Report Success
Inform user:
```
β
Worktree created successfully
- Location: worktrees/issue-$ISSUE_NUMBER/
- Branch: feature/issue-$ISSUE_NUMBER
- Based on: origin/main
- Status: Ready for work
```
#### Listing Worktrees
1. Get All Worktrees
```bash
git worktree list
```
2. Parse Output
Format shows:
```
/path/to/repo abc1234 [main]
/path/to/repo/worktrees/issue-123 def5678 [feature/issue-123]
/path/to/repo/worktrees/issue-456 ghi9012 [fix/issue-456]
```
3. Enhanced Status
For each worktree, check:
```bash
# Get branch status
cd worktrees/issue-$N && git status --short --branch
# Get last commit
cd worktrees/issue-$N && git log -1 --oneline
```
4. Display Formatted List
```
π Active Worktrees
===================
worktrees/issue-123/
Branch: feature/issue-123
Status: 2 files modified, 1 file added
Last Commit: Add user authentication endpoint
worktrees/issue-456/
Branch: fix/issue-456
Status: Clean working directory
Last Commit: Fix session timeout bug
```
#### Removing a Worktree
CRITICAL: Only remove worktrees after PR is merged and branch is deleted.
1. Verify Worktree Exists
```bash
git worktree list | grep "worktrees/issue-$ISSUE_NUMBER"
```
2. Check for Uncommitted Changes
```bash
cd worktrees/issue-$ISSUE_NUMBER && git status --short
```
If uncommitted changes exist:
- STOP - Warn user
- Ask if they want to:
- Commit changes first
- Discard changes
- Abort removal
3. Remove Worktree
```bash
git worktree remove worktrees/issue-$ISSUE_NUMBER
```
4. If Locked (Process Using It)
```bash
# Force removal if locked and confirmed by user
git worktree remove --force worktrees/issue-$ISSUE_NUMBER
```
5. Prune Stale References
```bash
git worktree prune
```
6. Verify Removal
```bash
git worktree list
ls worktrees/
```
7. Clean Up Empty Directory
```bash
# If worktrees/ is now empty, optionally remove it
if [ -z "$(ls -A worktrees/)" ]; then
rmdir worktrees/
fi
```
8. Report Success
```
β
Worktree removed successfully
- Removed: worktrees/issue-$ISSUE_NUMBER/
- Branch reference pruned
- Ready for new worktrees
```
#### Troubleshooting Worktrees
Locked Worktree
```bash
# Check lock reason
cat worktrees/issue-$N/.git | head -1
# Remove lock if safe
rm -f .git/worktrees/issue-$N/lock
```
Orphaned Worktree (directory exists but not in git)
```bash
# Prune git references
git worktree prune
# Manually remove directory
rm -rf worktrees/issue-$N/
```
Corrupted Worktree
```bash
# Remove and recreate
git worktree remove --force worktrees/issue-$N
git worktree prune
git worktree add -b feature/issue-$N worktrees/issue-$N origin/main
```
Best Practices
Before Creating:
- Always base on latest origin/main
- Use consistent naming:
worktrees/issue-$N/ - Use semantic branch names:
feature/issue-$N
During Use:
- Each worktree is independent
- Don't move or rename worktree directories manually
- Commit regularly within worktree
Before Removing:
- Verify PR is merged
- Verify remote branch is deleted
- Check for uncommitted changes
- Consider archiving important local changes
Directory Structure:
```
repository/
βββ .git/
βββ src/ # Main repo files
βββ worktrees/ # All worktrees
β βββ issue-123/ # Worktree for issue 123
β β βββ src/
β β βββ .git # Worktree git link
β βββ issue-456/ # Worktree for issue 456
β βββ src/
β βββ .git
```
Safety Checks
Always verify before creating:
- Main branch is up to date
- Worktree path doesn't already exist
- Branch name is unique
Always verify before removing:
- PR is merged (ask user to confirm)
- No uncommitted changes or user approves discarding
- No processes using the worktree
Never:
- Create worktree with existing branch name
- Remove worktree while process is running in it
- Manually delete worktree directory (use git worktree remove)
- Share worktrees between different repositories
|