skills.rest
webdevcody
webdevcodyCOMMUNITY
Explore all skills by this author →
Website𝕏@webdevcodyGitHub

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
One-click install
npx skills add https://github.com/webdevcody/go-mailing-list --skill create-worktree-webdevcody
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
Patasse97Patasse97

git-worktree-manager

Create isolated Git worktrees with deterministic port allocation and environment syncing.

Community
Advanced
greglambgreglamb
1

using-git-worktrees

Create an isolated Git worktree for feature development without disrupting the current workspace.

Community
Intermediate
gitgoodordietryinggitgoodordietrying
1

container-debug

Diagnose Docker container and Compose service issues via CLI.

Community
Advanced
AgLyx3AgLyx3

Git Worktree Manager

Provision isolated git worktrees with deterministic port mapping and env-file synchronization.

Community
Advanced