Git Worktree Manager

# Git Worktree Manager

Production workflow for parallel branch development with isolated ports, env sync, and cleanup safety checks. This skill packages practical CLI tooling and operating guidance for multi-worktree teams.

## Quick Start

```bash
# Create + prepare a worktree
python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

# Review stale worktrees
python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
```

## Included Tools

- `scripts/worktree_manager.py`: create/list-prep workflow, deterministic ports, `.env*` sync, optional dependency install
- `scripts/worktree_cleanup.py`: stale/dirty/merged analysis with optional safe removal

Both support `--input <json-file>` and stdin JSON for automation.

## References

- `references/port-allocation-strategy.md`
- `references/docker-compose-patterns.md`

## Installation

### Claude Code

```bash
cp -R engineering/git-worktree-manager ~/.claude/skills/git-worktree-manager
```

### OpenAI Codex

```bash
cp -R engineering/git-worktree-manager ~/.codex/skills/git-worktree-manager
```

### OpenClaw

```bash
cp -R engineering/git-worktree-manager ~/.openclaw/skills/git-worktree-manager
```


# Docker Compose Patterns For Worktrees

## Pattern 1: Override File Per Worktree

Base compose file remains shared; each worktree has a local override.

`docker-compose.worktree.yml`:

```yaml
services:
  app:
    ports:
      - "3010:3000"
  db:
    ports:
      - "5442:5432"
  redis:
    ports:
      - "6389:6379"
```

Run:

```bash
docker compose -f docker-compose.yml -f docker-compose.worktree.yml up -d
```

## Pattern 2: `.env` Driven Ports

Use compose variable substitution and write worktree-specific values into `.env.local`.

`docker-compose.yml` excerpt:

```yaml
services:
  app:
    ports: ["${APP_PORT:-3000}:3000"]
  db:
    ports: ["${DB_PORT:-5432}:5432"]
```

Worktree `.env.local`:

```env
APP_PORT=3010
DB_PORT=5442
REDIS_PORT=6389
```

## Pattern 3: Project Name Isolation

Use unique compose project name so container, network, and volume names do not collide.

```bash
docker compose -p myapp_wt_auth up -d
```

## Common Mistakes

- Reusing default `5432` from multiple worktrees simultaneously
- Sharing one database volume across incompatible migration branches
- Forgetting to scope compose project name per worktree


# Port Allocation Strategy

## Objective

Allocate deterministic, non-overlapping local ports for each worktree to avoid collisions across concurrent development sessions.

## Default Mapping

- App HTTP: `3000`
- Postgres: `5432`
- Redis: `6379`
- Stride per worktree: `10`

Formula by slot index `n`:

- `app = 3000 + (10 * n)`
- `db = 5432 + (10 * n)`
- `redis = 6379 + (10 * n)`

Examples:

- Slot 0: `3000/5432/6379`
- Slot 1: `3010/5442/6389`
- Slot 2: `3020/5452/6399`

## Collision Avoidance

1. Read `.worktree-ports.json` from existing worktrees.
2. Skip any slot where one or more ports are already assigned.
3. Persist selected mapping in the new worktree.

## Operational Notes

- Keep stride >= number of services to avoid accidental overlaps when adding ports later.
- For custom service sets, reserve a contiguous block per worktree.
- If you also run local infra outside worktrees, offset bases to avoid global collisions.

## Recommended File Format

```json
{
  "app": 3010,
  "db": 5442,
  "redis": 6389
}
```


#!/usr/bin/env python3
"""Inspect and clean stale git worktrees with safety checks.

Supports:
- JSON input from stdin or --input file
- Stale age detection
- Dirty working tree detection
- Merged branch detection
- Optional removal of merged, clean stale worktrees
"""

import argparse
import json
import subprocess
import sys
import time
from dataclasses import dataclass, asdict
from pathlib import Path
from typing import Any, Dict, List, Optional


class CLIError(Exception):
    """Raised for expected CLI errors."""