create-worktree

Create isolated git worktrees with per-branch ports and databases.

22|3|Updated Jul 28, 2024

Search Tags:#database migrations #git worktree #parallel development #docker compose #port allocation #postgres isolation #env generation

Ready to run

npx skills add https://github.com/webdevcody/go-mailing-list --skill create-worktree-webdevcody

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: create-worktree
Source: https://github.com/webdevcody/go-mailing-list/tree/main/.claude/skills/create-worktree
Command: npx skills add https://github.com/webdevcody/go-mailing-list --skill create-worktree-webdevcody

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It eliminates the hassle and risk of manually running multiple app branches at once by preventing port and database collisions while creating isolated environments per branch.

Core Features & Use Cases

Isolated worktrees: Creates a dedicated git worktree under .worktrees/<branch>/ for side-by-side development.
Deterministic port + DB allocation: Allocates UI, API, and Postgres ports in a safe range and provisions a per-worktree Docker Compose project and database.
Auto-configuration on first run: Detects hardcoded port literals and requires a refactor approval using references/first-run-refactor.md before creating the first worktree.
Migrations & setup automation: Generates a concrete .env, installs dependencies for the worktree, starts Postgres, runs detected migrations, and reports a single readiness summary.

Quick Start

Ask the assistant to run the create-worktree skill to spin up an isolated environment for your new branch so you can work on two branches at once without port or database conflicts.

Frequently Asked Questions about create-worktree

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I run multiple git branches at once without port conflicts?▼

Git worktrees let you run multiple app branches simultaneously by creating isolated working directories under `.worktrees/<branch>/` with dedicated UI, API, and Postgres ports. This prevents port collisions and database conflicts during parallel development.

What's the best way to set up parallel development with Postgres and docker-compose?▼

Setting up parallel development requires provisioning a dedicated docker-compose project and isolated Postgres database per branch. Automated worktree creation handles deterministic port allocation, container startup with health checks, and migration execution from the worktree directory.

Does git worktree parallel development require refactoring hardcoded port literals?▼

Yes, hardcoded port literals must be refactored into environment variable configurations before creating the first worktree. A Phase 0 port-parameterization detection step identifies these literals and requires approval using a first-run refactor reference document.

Can I use git worktrees with a single-app repo that relies on environment variables?▼

Git worktrees work with single-app repos that use Postgres via docker-compose and have dev servers configurable through environment variables. The process generates a concrete `.env` file from `.env.example`, installs dependencies, and starts containers automatically.

How are database migrations handled when spinning up an isolated git worktree?▼

Database migrations are executed automatically from the worktree directory after Postgres container startup passes health checks. Each worktree gets a dedicated isolated Postgres database, ensuring migration scripts run safely without affecting other branch environments.