Git Worktree Manager

Git Worktree Manager is an AI skill that streamlines the use of Git worktrees for parallel development workflows. It covers worktree creation and management, branch isolation strategies, multi-task development patterns, cleanup automation, and integration with development tools that enable developers to work on multiple branches simultaneously without stashing or context switching.

What Is This?

Overview

Git Worktree Manager provides structured workflows for using Git's worktree feature to maintain multiple checked-out branches simultaneously. It addresses worktree creation with sensible directory naming and branch association, parallel development patterns that let developers work on features, bugfixes, and reviews concurrently, IDE integration so each worktree has its own editor window and configuration, dependency management ensuring each worktree has correct installed packages, cleanup automation that removes stale worktrees and their associated branches, and status dashboards showing all active worktrees with their branch and change status.

Who Should Use This

This skill serves developers who frequently context-switch between multiple tasks, code reviewers who want to check out PR branches without disrupting their current work, team leads managing multiple feature branches simultaneously, and developers working on hotfixes while feature development is in progress.

Why Use It?

Problems It Solves

Developers using a single working directory must stash changes, switch branches, reinstall dependencies, and lose their editor state when moving between tasks. This context switching costs significant time and mental energy. Stashed changes can conflict when popped back. Running long builds or tests on one branch blocks work on another.

Core Highlights

The skill maintains separate directories for each active branch, preserving editor state and build artifacts. Worktree creation scripts handle directory setup, branch checkout, and dependency installation in one command. Cleanup tools identify and remove worktrees for merged or abandoned branches. Status overview shows all active workstreams at a glance.

How to Use It?

Basic Usage

git worktree add ../myproject-feature-auth feature/auth-redesign

git worktree add ../myproject-pr-247 origin/pr/247

git worktree list
git worktree remove ../myproject-pr-247

git worktree prune

Real-World Examples

import subprocess
import os
import json

class WorktreeManager:
    def __init__(self, repo_path):
        self.repo = repo_path
        self.base_dir = os.path.dirname(repo_path)

    def create(self, branch, install_deps=True):
        safe_name = branch.replace("/", "-")
        worktree_path = os.path.join(self.base_dir, f"wt-{safe_name}")
        subprocess.run(["git", "worktree", "add", worktree_path, branch],
                       cwd=self.repo, check=True)
        if install_deps and os.path.exists(os.path.join(worktree_path, "package.json")):
            subprocess.run(["npm", "install"], cwd=worktree_path, check=True)
        return worktree_path

    def list_active(self):
        result = subprocess.run(["git", "worktree", "list", "--porcelain"],
                                cwd=self.repo, capture_output=True, text=True)
        worktrees = []
        current = {}
        for line in result.stdout.split("\n"):
            if line.startswith("worktree "):
                if current: worktrees.append(current)
                current = {"path": line.split(" ", 1)[1]}
            elif line.startswith("branch "):
                current["branch"] = line.split(" ", 1)[1]
        if current: worktrees.append(current)
        return worktrees

    def cleanup_merged(self, base_branch="main"):
        for wt in self.list_active():
            if wt.get("branch") and self.is_merged(wt["branch"], base_branch):
                subprocess.run(["git", "worktree", "remove", wt["path"]], cwd=self.repo)

Advanced Tips

Create shell aliases that combine worktree creation with IDE launch so you can start working on a new branch in a single command. Use shared build caches between worktrees when your build tool supports it to avoid redundant compilation. Set up worktree-specific environment files for projects that need different configuration per branch.

When to Use It?

Use Cases

Use Git Worktree Manager when working on a feature while needing to switch to a hotfix without losing context, when reviewing multiple pull requests that each need a separate checkout, when running long-running tests on one branch while developing on another, or when maintaining release branches alongside active development.

Related Topics

Git branch management, parallel development workflows, IDE workspace configuration, CI/CD branch strategies, and developer productivity tools all complement worktree-based workflows.

Important Notes

Requirements

Git 2.5 or later, which introduced the worktree feature. Sufficient disk space for multiple checked-out copies of the repository. Understanding of Git branch operations to manage worktree branches effectively.

Usage Recommendations

Do: use consistent naming conventions for worktree directories to keep the filesystem organized. Run dependency installation after creating worktrees for projects with lock files. Clean up worktrees promptly when the associated task is complete.

Don't: create worktrees inside the main repository directory, as this causes confusion with nested Git operations. Forget to push or merge changes from worktrees before removing them. Create excessive worktrees that consume disk space and clutter the development environment.

Limitations

Each worktree requires disk space for the full working directory, which can be significant for large repositories. Some IDE extensions may not fully support multiple worktrees of the same repository. Worktrees cannot check out a branch that is already checked out in another worktree without using the detached HEAD state.