Download the PHP package anthonyiles/worktree-isolation without Composer

Worktree Isolation

Per-worktree test database isolation and bootstrap automation for PHP projects.

Works with any PHP project and any development environment: native PHP (Herd, Valet), Docker Compose, Laravel Sail, or any standalone Docker image. No framework required — Laravel integration is included but optional.

The Problem

When using git worktree with a PHP project, each worktree needs:

• Composer and npm dependencies installed
• Environment files (.env, .env.testing) configured
• An isolated test database to avoid conflicts with other worktrees running in parallel

This package automates all of that. After installation, every git worktree add automatically bootstraps the new worktree — no manual steps required.

Requirements

• PHP 8.2+
• Git 2.54+ (for config-based hooks)
• MySQL (for per-worktree database isolation)

Installation

Every scenario starts the same way:

This installs three commands under vendor/bin/ — worktree-install, worktree-setup, test, worktree-clean — kept in sync automatically by Composer. Nothing is copied into your project except the config file you choose to write (below). Laravel projects can swap vendor/bin/worktree-install for php artisan worktree:install in any scenario below — same flags, artisan just delegates to the same installer.

Then pick the section that matches your setup:

• Native PHP — Herd, Valet, or any local PHP/Node install
• Docker Compose — a service running via docker compose up -d
• Laravel Sail — Sail, or any other standalone Docker image

Native PHP

For Herd, Valet, or any setup where composer, npm, and your test runner already run directly on the host.

This is the default runtime, so no --runtime flag is needed. It writes .worktree-isolation.env:

Non-Laravel projects should also set WORKTREE_TEST_COMMAND — see Custom Test Command.

Docker Compose

For projects where the app runs as a service in docker-compose.yml, started with docker compose up -d.

--compose-service should match the service name in your docker-compose.yml that has PHP, Composer, and Node available (default: app). This writes:

composer install, npm install, and your test command all run via docker compose exec -T, so the compose stack must already be up when you run git worktree add or vendor/bin/test.

Laravel Sail

Sail is just Laravel's name for a pre-built Docker image, so it uses the docker-image runtime — this also covers any other standalone Docker image (non-Sail) the same way, just with different --docker-image/--docker-network values.

• --docker-image — the image Sail already built (check with docker images, or see vendor/bin/sail config; typically <project>-<php-version>/app)
• --docker-network — the Docker network Sail's containers (including MySQL) run on, so the ephemeral test container can reach them (typically <project>_sail)

This writes:

composer install, npm install, and your test command each run via a throwaway docker run --rm against that image, attached to the given network — the image must already be built (vendor/bin/sail build, or docker compose build for a non-Sail standalone image).

Custom Test Command

By default, tests run via php artisan test. For non-Laravel projects (in any of the scenarios above), set a custom test command:

Or set WORKTREE_TEST_COMMAND directly in .worktree-isolation.env:

For Other Engineers

After pulling a branch that has .worktree-isolation.env committed, each engineer just runs:

The command is idempotent — it detects the existing .worktree-isolation.env and only (re)configures the git hook.

Hook activation is local to that clone (git config --local), so each engineer runs this once per clone — same as any git-hooks tool (Husky, pre-commit, etc.), since git never auto-trusts hooks from a fresh clone. It is not tied to any branch: because the hook command is registered as an absolute path resolved at install time, worktrees created from any branch — including ones that never had this package's config committed — get bootstrapped automatically. You don't need to merge anything hook-related into every branch you plan to git worktree add from.

How It Works

Automatic Worktree Bootstrap

When you run git worktree add, the post-checkout hook detects the new worktree and runs worktree-setup (straight out of vendor/), which:

1. Copies .env from the main repo
2. Copies .env.testing (or falls back to .env.testing.example)
3. Forces TEST_DB_PER_WORKTREE=true in the worktree's .env.testing
4. Runs composer install (via the configured runtime)
5. Derives the per-worktree database name, creates it, and writes it as DB_DATABASE in the worktree's .env.testing
6. Runs npm install (via the configured runtime)

Per-Worktree Test Databases

The database name is derived from the worktree directory:

For example, a worktree at ../worktrees/my-project/feature-auth gets database testing-feature-auth. A safety guard ensures the derived name always contains "test" to prevent accidental use of production databases.

Because this name is written directly into .env.testing at bootstrap time (step 5 above), it applies no matter how you run tests — vendor/bin/test, sail test, php artisan test, vendor/bin/phpunit, or anything else that reads .env.testing the normal way. vendor/bin/test also re-derives and re-creates the database dynamically on every run, so it stays correct even if step 5 failed at setup time (e.g. the database wasn't reachable yet) or the worktree directory gets renamed later.

Running Tests

From any worktree:

Cleaning Up

Drop all per-worktree test databases:

This lists all databases matching the {base}-* pattern and asks for confirmation before dropping them. Use --force to skip the prompt.

Configuration

Runtime Drivers

.worktree-isolation.env (full reference)

Project-level configuration (committed to repo). The scenario sections above show the subset of these that matter for each runtime — this is the complete list:

Laravel Config (optional)

Laravel projects can also publish a config file:

This creates config/worktree-isolation.php which mirrors the .worktree-isolation.env settings through Laravel's config system.

Available Commands

All installed via Composer's bin mechanism — vendor/bin/* always matches the installed package version, nothing to republish on upgrade.

AI Agent Integration

The per-worktree database is baked into .env.testing at bootstrap time (see Per-Worktree Test Databases), so an agent that runs sail test or php artisan test directly still hits the correct, isolated database — it doesn't depend on the agent knowing about vendor/bin/test. vendor/bin/test is still worth pointing agents at for its runtime dispatch (docker-compose/docker-image projects need composer/npm/test commands routed into the right container). Add this to your project's cursor rules or AGENTS.md:

License

MIT