{"slug": "setup-script-should-support-git-worktrees", "title": "Setup Script Should Support Git Worktrees", "summary": "Ally Piechowski argues that setup scripts should support Git worktrees to isolate ports, databases, and state for safe parallel development, sharing one Docker stack while deriving a readable worktree identity and allocating unique resources via a locked registry. The approach enables multiple coding agents to run unrelated changes simultaneously without runtime collisions.", "body_md": "# Your Setup Script Should Support Git Worktrees\n\nA worktree-aware setup script can diagnose missing tools, share one Docker stack, and isolate ports, databases, and state for safe parallel development.\n\nAlly Piechowski · · 5 min readOn one production app I work on, a fresh Git worktree becomes runnable with one setup script:\n\n```\nbin/setup\n```\n\nSetup prepares the environment and exits, then the normal development command runs. I’ll use `bin/dev`\n\nhere as shorthand for whatever command the repository already uses. Setup doesn’t hide the server inside a clever process manager.\n\n`bin/setup`\n\nis a repo-owned executable that turns a checkout into a working development environment. Call it `make setup`\n\nor `script/bootstrap`\n\nif that fits your project. The interface matters more than the name: one command returns either a ready repository or exact repair instructions.\n\nThe same command should work from every Git worktree. Parallel coding agents made this important enough to treat as ordinary development infrastructure.\n\n## A Second Checkout Is Not a Second Environment\n\nA [Git worktree](https://git-scm.com/docs/git-worktree.html) is another checkout with its own working tree, `HEAD`\n\n, and index while sharing the repository’s common Git data. That separation is great for code. Git does not know that both copies of the app want the same port, database, cache keys, callback URL, Terraform state, or container name.\n\nThis works until two worktrees need to run:\n\n```\ngit worktree add ../app-payment-fix -b payment-fix\ncd ../app-payment-fix\nbin/setup\nbin/dev\n```\n\nA setup script written for one permanent clone can copy the same `.env`\n\nand point every checkout at the same databases. When two worktrees start, their dev servers can fight for host ports. Compose projects can also overlap when they reuse a project name or fixed container, network, or volume names, and published ports still collide. The second worktree either fails to start or quietly shares state.\n\nWorktrees existed long before coding agents. What changed is frequency. Keeping two branches open used to be an occasional convenience. Now several agents can implement and test unrelated changes at once. Their files are isolated by Git; their runtime state has to be isolated by the repository.\n\n## Share Services, Isolate Names\n\nRunning a complete Docker stack for every worktree is the simplest mental model and often the wrong default. Databases, object storage emulators, mail catchers, and other local services can be expensive compared with an app process. I run one shared stack, then give each worktree its own ports, databases, and resource names.\n\n| Shared once per machine | Isolated per worktree |\n|---|---|\n| Database and cache servers | Development and test database names, cache namespace |\n| Local service containers | Queue names, buckets, callback URLs, infra resource names |\n| Package-download and tool caches | App port, environment file, logs, PIDs, local state |\n\nThe setup script derives a readable worktree identity, checks it against a small local registry, then writes generated configuration such as:\n\n```\nWORKTREE_ID=<derived-worktree-id>\nAPP_PORT=<allocated-port>\nDATABASE_NAME=app_dev_<worktree-id>\nTEST_DATABASE_NAME=app_test_<worktree-id>\n```\n\nRegistry allocation needs a lock because agents can start setup together. The lock only serializes setup processes that honor it. A robust allocator should remove stale reservations, pick a candidate port, check for a current listener, then commit the identity atomically.\n\nThat listener check is only a snapshot. The dev command must still report a later bind collision clearly. A script can be safe to rerun and still fail under concurrency; idempotence alone is not enough.\n\n## What `bin/setup`\n\nOwns\n\nSetup owns every step between `git worktree add`\n\nand the normal development command:\n\n- Bootstrap the repository’s declared toolchain (I use mise).\n- Run\n`bin/doctor`\n\nto diagnose remaining host requirements, stopping with exact repair steps if needed. - Ensure the shared Docker services are running and healthy.\n- Allocate or recover the worktree’s identity and ports.\n- Generate local environment and service configuration.\n- Create and migrate isolated development and test databases.\n- Verify the app can reach its dependencies, then exit.\n\nThat bootstrap does not have to be mise. I use [mise](https://mise.jdx.dev/configuration.html) to pin language runtimes, package managers, and small CLI tools in the repository. Setup can run [ mise install](https://mise.jdx.dev/cli/install.html) for missing configured versions. Git, Docker, operating-system libraries, and credentials may still be required.\n\nIf a repository uses mise, installing a tool does not activate it for every shell. Setup should run repo commands through `mise exec -- ...`\n\nor explicitly require shell activation, so incidental shell configuration cannot change the result.\n\nThis shortens [time to first commit](/post/codebase-drag-audit/#5-time-to-first-commit), but onboarding is only the first payoff. The same path runs whenever a human or agent opens a worktree.\n\n## Make Setup Fail Early\n\n`bin/doctor`\n\nbelongs near the start of setup and should also run independently. Before I added it, setup could reach the seed step before discovering `ffmpeg`\n\nwas missing. Doctor now catches that before the expensive work begins.\n\nA useful doctor checks every requirement, collects all failures, exits nonzero, and prints repairs a person can paste:\n\n```\nFAIL container engine: daemon not reachable\n     Start Docker, then run bin/doctor again.\nFAIL tools: configured versions are missing\n     Run: mise install\n```\n\nDoctor should report the whole list in one run, with stable exit codes, no prompts, and output that works in a terminal or agent transcript.\n\n## The Limits of a Shared Stack\n\nRestarting a shared database interrupts every worktree. Branches that require incompatible service versions cannot use the same stack. Cache keys, mailboxes, queues, and object names still cross-talk unless setup prefixes them with the worktree identity.\n\nSome work needs stronger isolation. Destructive migration work, tests that reset an entire server, or a branch upgrading the database engine may deserve a dedicated stack. The shared stack is the fast default, not a rule.\n\nReset and teardown commands need the same boundaries. `git worktree remove`\n\ndoes not invoke app cleanup, so a repo-owned `bin/teardown`\n\nshould release the port, drop only that worktree’s databases, and delete only its generated state. A normal `bin/reset`\n\nmust never erase a shared volume or another checkout’s resources. Make any machine-wide reset explicit and difficult to run by accident.\n\nThe acceptance test should start from a clean worktree with no copied environment file. Run setup twice and concurrently beside another setup, start both dev servers, execute both test suites, then tear one worktree down while the other keeps running. Every manual fix found there belongs in `bin/setup`\n\nor `bin/doctor`\n\n.\n\nA coding agent should be able to create a worktree, prepare it, run the app, and leave without touching its siblings. If the repository cannot enforce that boundary, adding more agents only creates faster local-environment failures.", "url": "https://wpnews.pro/news/setup-script-should-support-git-worktrees", "canonical_source": "https://piechowski.io/post/setup-script-git-worktrees/", "published_at": "2026-07-28 15:32:58+00:00", "updated_at": "2026-07-28 16:45:21.362668+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Ally Piechowski", "Git"], "alternates": {"html": "https://wpnews.pro/news/setup-script-should-support-git-worktrees", "markdown": "https://wpnews.pro/news/setup-script-should-support-git-worktrees.md", "text": "https://wpnews.pro/news/setup-script-should-support-git-worktrees.txt", "jsonld": "https://wpnews.pro/news/setup-script-should-support-git-worktrees.jsonld"}}