Worktree Prompt Laravel Package

Getting Started

Install the CLI (global Composer install or as a dev dependency so the whole team gets the same version), then from the root of your Laravel app:

lwt add feature/invoices

That fetches, lets you pick or create feature/invoices (branched from origin/HEAD with --no-track), creates the worktree at ../<app>-feature-invoices, and runs setup: a copy-on-write vendor (or composer install if the lockfile doesn't match), .env, storage/, bootstrap/cache, public/build, public/storage, and .worktreeinclude paths.

Where to look first:

• lwt list — the canonical view of every worktree and whether it's set up. Run it after your first add to confirm the path and setup state before you start editing.
• .worktreeinclude — add per-project paths here (seed dumps, uploaded fixtures, .env.testing) so every new worktree gets them.
• lwt add --help — the --db, --npm, --build, --url and --db-admin flags are where the real day-to-day power lives.

First real use case: keep your main checkout on main with its vendor and database intact while you do a risky refactor in a separate directory, with its own database, without touching docker-compose or copying folders by hand.

Implementation Patterns

Parallel feature work with isolated databases. The default setup shares your app database, which is fine for a quick look but wrong for migrations. Use:

lwt add feature/invoices --db=copy --url

--db=copy clones the database (Postgres, MySQL/MariaDB or SQLite) and runs migrate; --url rewrites APP_URL and the related host keys so cookies, session domains, and asset URLs don't collide with your main checkout. If the app's DB user can't CREATE DATABASE, add --db-admin=root.

Reviewing PRs and other people's branches. You don't need add for this — it creates the branch. Once a worktree exists (plain git worktree add, git-prompt, or an agent's .claude/worktrees/<name>), run:

lwt setup ../myapp-hotfix

It's idempotent, so re-running is the standard fix for a half-broken worktree (bad autoload, missing storage/ subfolders, missing .env).

Frontend-heavy branches. --npm copies node_modules when the lockfile matches (plus .cache/puppeteer), otherwise falls back to npm ci. --build runs the build so public/build and bootstrap/ssr are populated. For a branch that only touches PHP, skip both — the copy is not free.

Scripting and CI-ish flows. Every command exits non-zero when something you asked for didn't happen, so chain safely:

lwt add "$BRANCH" --db=empty --npm || exit 1
cd "../myapp-$SLUG" && php artisan test

Test database discipline. Setup checks the shared test database and tells you how to load it (snapshot:load testing --env=testing --force). Treat that as a hint that --env=testing still points at one shared DB across worktrees — parallel test runs across two worktrees will step on each other unless you give each its own testing database.

Cleanup as a habit. lwt remove <path|branch> refuses a dirty worktree, drops the database it created, offers to delete the branch, prunes stale worktree metadata, and removes the now-empty parent folder. Run it the moment a branch merges rather than accumulating directories.

Gotchas and Tips

• vendor is never a symlink, by design. When composer.lock matches it's a real copy-on-write clone (cp -c on APFS, --reflink on btrfs/XFS). On filesystems without reflink support this silently degrades to a full copy or composer install — expect the first lwt add on ext4 to be slow, and don't be surprised by real disk usage.
• A stale composer.lock costs you the fast path. If you've run composer update locally without committing the lock, the worktree gets a fresh composer install instead of the clone. Commit the lock in the main checkout before lwt add.
• .env is copied, not linked, by default. Changes to the main checkout's .env after setup do not propagate. That's usually what you want (per-worktree DB_DATABASE), but it means secrets rotated in the main checkout need a manual re-copy or a re-run of lwt setup.
• Tracked files are never written over. Setup restores any tracked file it changed, so don't try to smuggle per-worktree config into tracked files — put it in gitignored files or .worktreeinclude.
• --no-track on new branches. lwt add creates branches without an upstream. Your first git push needs -u origin <branch>; don't assume git push just works.
• lwt remove will refuse a dirty worktree. Commit or stash first — untracked scratch files count. This is a safety net, not a bug, but it will block a scripted cleanup; check the exit code.
• It verifies App\ autoloads from the worktree. If that check fails, suspect a stale vendor/composer/autoload_* from the main checkout or an APP_ENV/composer.json mismatch — re-run lwt setup <path> before debugging anything else.
• --db-admin=root exists for a reason. On managed MySQL/Postgres where the app user has no CREATE DATABASE, --db=copy fails late (after vendor). Pass the admin flag from the start on those projects.
• Host collisions are the sneakiest failure. Two worktrees on the same APP_URL host share cookies and session state, producing "logged out randomly" bugs. Always reach for --url when running more than one worktree at a time.
• Exit codes are the contract. Because setup reports non-zero when anything requested didn't happen, wire lwt into shell scripts and check $?. Don't parse stdout, and don't assume a partially-successful setup is safe to test against.