Laravel Herd + Git Worktrees

Run multiple branches of a Laravel project in parallel, each reachable at its own *.test URL through Laravel Herd, with isolated dependencies, env, database, and caches.

Mental Model

• A worktree is a sibling directory of the main checkout with its own HEAD. Composer/Node deps, vendor/, node_modules/, storage/, and bootstrap/cache/ are per-worktree: never share via symlink.
• Herd's parked directory auto-serves every immediate subdirectory as <dir>.test. Park the parent of all worktrees once and every new worktree gets a URL for free.
• .env is untracked, so it must be re-created in each worktree. APP_URL, DB_DATABASE, cache prefixes must differ per worktree to prevent cross-branch bleed.

When to Use This Skill

• User asks to create a worktree for a Laravel app served by Herd.
• User reports vendor/, migrations, cache, or .env problems after switching worktrees.
• User wants per-branch URL like myapp-feat.test without manual Nginx/Valet config.
• User wants the same Laravel project on multiple PHP versions simultaneously.

Workflow

1. One-time setup

Park the parent directory that holds the main checkout (worktrees become siblings of the main checkout, so they land in the same parked dir):

cd ~/Code           # parent of your laravel project
herd park

Verify:

herd parked

Each immediate subdir is now <name>.test. Adding a worktree at ~/Code/myapp-feat makes myapp-feat.test resolve immediately.

If parking the parent is not desired (other non-Laravel dirs live there), use explicit herd link per worktree instead: see references/herd-commands.md.

2. Create a new worktree

Use the helper script. It creates the worktree, copies .env, rewrites APP_URL + DB_DATABASE + cache prefixes, installs deps, generates app key, and runs migrations (when Composer hooks require assets built before composer install, follow step 1 of Bootstrap a bare worktree):

bash scripts/worktree-new.sh <branch-suffix> <base-branch> [--driver sqlite|mysql|pgsql]

Example:

bash scripts/worktree-new.sh feat-billing main --driver sqlite

Result: ../myapp-feat-billing/ exists, myapp-feat-billing.test works, isolated DB.

See scripts/worktree-new.sh for the exact transformations applied to .env.

3. Remove a worktree

bash scripts/worktree-rm.sh <branch-suffix> [--drop-db]

Runs git worktree remove, optionally drops the per-worktree DB, and herd unlinks if a manual link exists.

4. Switch PHP version per worktree (optional)

cd ../myapp-legacy
herd isolate [email protected]

Site uses 8.1; sibling worktrees keep their isolated or default version. herd isolated lists all overrides. herd unisolate reverts.

Bootstrap a bare worktree

A worktree made with plain git worktree add (the PR, issue, and CI recipes in other skills, at .claude/worktrees/<name>) has no vendor/, node_modules/, or .env; nor does one the harness made (claude --worktree, a subagent with isolation: worktree). With the leek-skills plugin in Claude Code, a session that opens in such a worktree is told so at start; elsewhere, check for vendor/ yourself before running anything. Make it runnable from inside the worktree, with main set to the main checkout (git worktree list --porcelain | sed -n '1s/^worktree //p'):

1. Dependencies and assets. cp -Rc "$main/vendor" vendor (an APFS clone: instant, no extra disk), then composer install so it matches this branch's lock. Do the same for node_modules when the run builds assets. When Composer hooks require generated assets that do not exist yet (such as @php artisan filament:assets needing an editor bundle from npm run build), run composer install --no-scripts, build the assets, then run composer install. Each tree owns a real copy: Composer's autoloader resolves app/ and tests/ relative to vendor/, so a symlinked vendor/ makes Pest run the main checkout's code.
2. Environment. Copy .env (and .env.testing when present) from $main. When the calling skill gives the run its own database, set DB_DATABASE to that name in both. When the worktree lives under .claude/worktrees/<name> (not an immediate subdirectory of Herd's parked parent) and the run needs a .test URL for HTTP verification, run herd link <name> (and herd secure <name> when APP_URL uses https://), then herd unlink <name> from inside the worktree before removing it (each skill's worktree removal step says so).
3. Proof. git rev-parse HEAD equals the commit the run means to test, and test ! -L vendor passes. Run nothing until both hold.

Per-Worktree Isolation Rules

Full rationale: references/isolation.md. DB strategy details (sharing seeds, schema dumps, fresh vs. migrate): references/db-strategies.md.

Common Pitfalls

• Sharing `vendor/` via symlink: breaks when branches have different package versions; autoload class maps drift.
• Forgetting `php artisan key:generate`: encrypted cookies/sessions fail silently across worktrees that share APP_KEY.
• *Same `SESSION_COOKIE` across `.test siblings**: cookies leak between branches because they share the .test parent domain. Set a unique SESSION_COOKIE` per worktree.
• Same Redis DB without prefix: cache keys collide; one branch invalidates another's cache.
• Running `composer install` against a stale `composer.lock` after rebasing: always re-run install after switching base branches inside a worktree.
• Herd not picking up new worktree: happens if the parent isn't parked or if the worktree directory name contains characters Herd rejects (stick to [a-z0-9-]).

Quick Diagnostics

herd parked              # confirm parent is parked
herd isolated            # list per-site PHP overrides
herd which-php           # PHP version Herd resolves for current dir
git worktree list        # all worktrees + branches
ls -1 ../ | grep <app>   # worktree dirs as Herd sees them

If a .test URL 404s: check herd parked includes the parent, dir name is lowercase, and php artisan route:list works inside the worktree.

Out of Scope

• Valet: different tool. Herd-only here.
• Linux Herd: paths and CLI differ; this skill assumes macOS Herd.
• Docker / Sail: covered by other workflows. Worktrees still work but routing is via Docker, not Herd.