Git Worktree Management Skill

This skill helps you manage git worktrees efficiently. Git worktrees allow you to check out multiple branches simultaneously in different directories, which is useful for:

• Working on multiple features in parallel
• Testing different branches without losing work-in-progress
• Reviewing code while continuing development
• Quick bug fixes on main while working on a feature branch

Naming Convention

Worktrees should be created as sibling directories with a clear naming pattern:

Pattern: ../<repo-name>-wt-<branch-name>

Example: For a repo named "MyProject" with branch "feature/new-login":

/Users/username/source/myproject/              # Main repo
/Users/username/source/myproject-wt-feature-new-login/  # Worktree

Available Operations

List Worktrees

Show all existing worktrees with their paths and branches:

git worktree list

Example output:

/Users/username/source/myproject        c5b174796b4 [main]
/Users/username/source/myproject-wt-feature-auth   def5378 [feature/new-login]
/Users/username/source/myproject-wt-hotfix-crash   ghi9022 [hotfix/button-crash-fix]

Create a New Worktree

When creating worktrees, automatically use the naming convention:

For existing branches:

git worktree add ../<repo-name>-wt-<sanitized-branch-name> <branch-name>

For new branches:

git worktree add -b <new-branch-name> ../<repo-name>-wt-<sanitized-branch-name> <base-branch>

Note: Branch names with slashes (e.g., feature/new-login) should be sanitized by replacing / with - for the directory name.

Examples:

# Checkout existing feature branch
git worktree add ../myproject-wt-feature-auth feature/auth

# Create new feature branch from main
git worktree add -b feature/new-payment ../myproject-wt-feature-new-payment main

# Create hotfix worktree
git worktree add -b hotfix/critical-bug ../myproject-wt-hotfix-critical-bug main

Remove a Worktree

When you're done with a worktree:

# Remove worktree (must not have uncommitted changes)
git worktree remove ../<repo-name>-wt-<branch-name>

# Force remove even with uncommitted changes
git worktree remove --force ../<repo-name>-wt-<branch-name>

Prune Stale Worktrees

Clean up worktree metadata for manually deleted directories:

git worktree prune

Move a Worktree

Relocate an existing worktree (maintaining naming convention):

git worktree move <old-path> <new-path>

Lock/Unlock Worktrees

Prevent accidental deletion:

git worktree lock <path>
git worktree unlock <path>

Helper Functions

When creating worktrees, the skill should:

1. Get the repository name: Extract from the current directory name
2. Sanitize the branch name: Replace / with - for the path
3. Build the path: ../<repo-name>-wt-<sanitized-branch-name>

Example logic:

REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
BRANCH_NAME="feature/new-login"
SANITIZED_BRANCH=$(echo "$BRANCH_NAME" | sed 's/\//-/g')
WORKTREE_PATH="../${REPO_NAME}-wt-${SANITIZED_BRANCH}"

git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

Best Practices

1. Naming Convention: Always use <repo-name>-wt-<branch-name> pattern
2. Location: Keep worktrees as siblings to the main repo directory
3. Cleanup: Remove worktrees when done to avoid clutter
4. Branch Tracking: Each worktree tracks a different branch
5. Shared Objects: Worktrees share the same .git repository, saving disk space
6. Multiple Repos: The naming convention prevents confusion when multiple repos are in the same parent directory

Troubleshooting

Worktree Already Exists

If you get an error that a worktree already exists for a branch, you can:

1. Use git worktree list to find where it is
2. Remove the existing worktree first
3. Check out a different branch in the existing worktree

Locked Worktree

If removal fails due to a lock:

git worktree unlock <path>
git worktree remove <path>

Stale Worktree References

If worktrees were manually deleted:

git worktree prune

Branch Name Sanitization

Remember to replace / with - when creating directory names from branch names like feature/new-login → feature-new-login.

Integration with This Skill

When you ask me to:

• "List my worktrees" - I'll run git worktree list
• "Create a worktree for feature X" - I'll use the <repo-name>-wt-X naming pattern
• "Clean up worktrees" - I'll help remove old ones safely
• "Switch to worktree Y" - I'll navigate to the properly named directory
• "What worktrees exist?" - I'll list and explain them with full paths

This skill automatically applies the naming convention to keep your workspace organized, especially when managing multiple repositories in the same parent directory.