mozex / laravel-worktree
Create and tear down isolated Laravel git worktrees, each with its own databases, .env and site, on any local server
Fund package maintenance!
Requires
- php: ^8.2.0
- ext-dom: *
- ext-pdo: *
- illuminate/console: ^12.69|^13.30
- illuminate/contracts: ^12.69|^13.30
- illuminate/filesystem: ^12.69|^13.30
- illuminate/process: ^12.69|^13.30
- illuminate/support: ^12.69|^13.30
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.14
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.8.2|^4.0.0|^5.0.0
- pestphp/pest-plugin-laravel: ^3.2|^4.0.0|^5.0.1
- pestphp/pest-plugin-type-coverage: ^3.5|^4.0.0|^5.0.1
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
Suggests
- mozex/laravel-test-lanes: Isolates concurrent test runs with lane databases, which worktree:teardown cleans up automatically
Provides
None
Conflicts
None
Replaces
None
README
Laravel Worktree
Work on a feature branch without touching your main checkout. One command turns a branch into a git worktree with its own .env, its own dependencies, a database of its own on every connection your app uses (for the app and for its tests, empty or cloned from your local data), and a local site served by Herd, Valet, a command you configure, or no server at all. A second command finishes the branch by opening a pull request, merging it, or throwing it away, then drops the databases, stops serving the site, and removes the worktree. A migration in one branch never touches another, and teardown removes what setup created.
Read the full documentation at mozex.dev: searchable docs, version requirements, detailed changelog, and more.
Table of Contents
- Installation
- How It Works
- Creating a Worktree
- Adopting a Worktree
- Claude Code
- Finishing a Worktree
- Pruning Gone Worktrees
- Listing Worktrees
- Finding a Worktree
- Configuration
- Warp Terminal
Support This Project
I maintain this package along with several other open-source PHP packages used by thousands of developers every day.
If my packages save you time or help your business, consider sponsoring my work on GitHub Sponsors. Your support lets me keep these packages updated, respond to issues quickly, and ship new features.
Business sponsors get logo placement in package READMEs. See sponsorship tiers →
Installation
Requires PHP 8.2+ - see all version requirements
Install it as a dev dependency:
composer require mozex/laravel-worktree --dev
Then run the install command. It publishes config/worktree.php, which is where you'll choose the site driver, where worktrees live, how databases are named, and the steps that run after setup:
php artisan worktree:install
If config/worktree.php already exists, the command leaves it as it is. Once that's done, every command below is ready to use.
How It Works
Git worktrees let you check out several branches at once, each in its own directory, all backed by one .git folder. That solves the code side of running two branches side by side, but it leaves the environment behind. The new directory has no vendor, no node_modules, no .env, and it points at the same database as your main checkout. Run migrations in one and you've changed the other.
This package fills that gap. worktree:setup runs from your main repository and does the rest of the work for you:
- Creates the worktree next to your project (or wherever you configure).
- Serves it as a local site through your server's site driver, so
blogon branchfeature/loginbecomesblog-feature-login.test. - Copies your
.env(plus any extra env files you configure), then rewrites the database name and every reference to the old host. - Creates an application database, empty or cloned from your main one, plus a separate test database, and writes the test database name into every PHPUnit config you run a suite with.
- Installs dependencies (or copies them from your main checkout when the lock matches), migrates the new database, then runs your own extra steps (build, storage link, whatever you list).
Because it all runs from the main repo, you never cd into a half-built directory. And because it's an Artisan command, it works the same whether you call it by hand, from a Composer script, or from a terminal shortcut.
Running from the main repository is a rule the commands enforce, not just a suggestion. Run any of them from inside a worktree and they stop with an error that points you back at the main checkout, because from there setup would derive the wrong names and teardown could pick the wrong directory to destroy.
Creating a Worktree
Pass a branch name:
php artisan worktree:setup feature/login
Leave it off and a branch is generated for you (feature/auto-260714-193000):
php artisan worktree:setup
When you're done you'll see where everything landed:
Worktree ready.
+---------------+------------------------------------------+
| Path | /Users/you/Sites/blog-feature-login |
| Branch | feature/login |
| URL | https://blog-feature-login.test |
| Database | blog_feature_login |
| Test database | blog_feature_login_testing |
+---------------+------------------------------------------+
The URL row only appears when the site driver served the worktree.
A few options change what runs:
| Option | What it does |
|---|---|
--base=develop |
Branch off develop instead of the configured base branch |
--seed |
Seed the database after migrating |
--clone |
Start from a copy of your main database instead of an empty one (see Cloning Your Data) |
--no-clone |
Start from an empty database even when cloning is turned on in the config |
--no-migrate |
Create the databases but skip migrations |
--no-database |
Skip databases and PHPUnit entirely |
--no-install |
Skip installing or copying dependencies, plus the migrations and steps that need them |
--print-path |
Send all output to stderr except the final worktree path, for shell integration |
If the branch already exists, its worktree is checked out as-is instead of branching from scratch.
Setup is also safe to run twice. If the worktree for that branch is already there, say because a dependency install died halfway through the first run, the command picks it back up and finishes provisioning instead of demanding a teardown. A directory that belongs to some other branch is still refused.
Each worktree setup makes is recorded in .git/laravel-worktree/registry.json: its name, the site driver that served it, and every database it created, with the server that database lives on. The file sits inside git's own directory, so it's never committed, and every worktree of the clone shares it. Teardown and worktree:list read it back, as described below. If the file can't be read, the commands say so, leave it untouched, and work from your config instead.
Two setup or adopt runs on the same repository at once, say from agents working side by side, take turns at the steps that would collide: checking the name is free, creating the worktree and recording it, and running the site driver's commands. The one that has to wait says so, and gives up after ten minutes.
Adopting a Worktree
Agent apps and editors such as Cursor, Codex and Conductor make worktrees of their own. A worktree like that gets your code and nothing else: its .env is missing, or it's a copy of yours, or a link to yours, all of which point it at your main database. worktree:adopt provisions it the way setup provisions its own worktrees, without creating it:
php artisan worktree:adopt ../agent-worktrees/blog-3f2a
The path has to be one that git worktree list shows for this repository, so your main checkout and unrelated directories are refused. Everything after that is setup's: the site, the .env, databases, dependencies, migrations, PHPUnit configs and your steps, with the same options (--clone, --seed, --no-install and the rest), plus --no-secure, which serves the site over http even when your driver would secure it. Some tools link files back to your main checkout instead of copying them. When the worktree's .env, vendor, node_modules, SQLite database or PHPUnit config is a link (a hard link included) to something outside the worktree, adopt removes the link, never what it points to, and gives the worktree its own, since writing through it would change your main app. It only checks what the run is about to write, so --no-install leaves dependency links alone and --no-database leaves database and PHPUnit links alone.
A tool's worktree isn't named after a branch, and many tools start it on a detached HEAD, so adopt names it with --name, which takes the branch's place in the host template. In a repository called blog, --name=agent gives blog-agent.test and a blog_agent database. Without --name, adopt uses the workspace name Conductor sets when it runs from Conductor's setup script for that worktree, and otherwise a short hash of the path, such as blog-3f2a91c0.
A name that would give two worktrees the same databases is refused, by adopt and by setup alike: blog-feature_login and blog-feature-login both make blog_feature_login, and so would a name matching your main site's. Adopting a worktree a second time picks up where the first run stopped and keeps the name it got then. A worktree that worktree:setup made is sent back to setup, which resumes its own.
Adopt records the worktree with what made it (--tool=cursor, say, or adopt when you don't pass one). After that, worktree:list shows it, and worktree:teardown blog-agent and worktree:path blog-agent find it by its name. Teardown treats it like any other worktree: it drops the databases adopt created, removes the worktree directory the tool made, and deletes its branch unless you finish with --pr. A name that matches more than one worktree is refused; give the path instead. A tool's worktree that was never adopted has no record, so teardown leaves its site and databases alone and says so.
From a Tool's Setup Script
Tools run their setup script inside the new worktree, which has no vendor directory yet, so artisan can't run there. Publish a small script into your app and commit it:
php artisan vendor:publish --tag=worktree-adopt
That writes worktree-adopt.php to your project root. It finds your main checkout through git and runs php artisan worktree:adopt there for the worktree it was started in, passing on any options you add. Make it the tool's setup command:
php worktree-adopt.php --clone
Commit the script, and push it: a new worktree holds only what's committed on the branch it starts from, and some tools start from your remote's copy of that branch.
Agent Apps and Editors
worktree:install-agent sets each tool up for you, and publishes worktree-adopt.php when it isn't there yet:
php artisan worktree:install-agent conductor
Where a tool reads a settings file that's yours alone, the installer writes the setup command into it. Where the tool keeps its setup in a file your team shares, or in the app's own settings, it prints what to add there instead, since changing how every teammate's worktrees are made is the team's call.
| Tool | Argument | What the installer does |
|---|---|---|
| Conductor | conductor |
Writes .conductor/settings.local.toml |
| Paradev (formerly Superset) | paradev |
Adds the command to .superset/config.local.json |
| Cursor | cursor |
Prints the lines for .cursor/worktrees.json |
| Codex | codex |
Prints the setup script for the ChatGPT desktop app's local environment |
| Zed | zed |
Prints a task for .zed/tasks.json |
| Devin Desktop (formerly Windsurf) | devin |
Prints a hook for .devin/hooks.json |
Anything that runs git worktree add |
git |
Writes a git hook, see With a git Hook |
| Claude Code | claude |
Writes Claude Code's own hooks, see Claude Code |
The installer passes setup's options on to adopt (--clone, --no-clone, --seed, --no-migrate, --no-database, --no-install), along with --tool, so worktree:list shows which tool made each worktree. The worktrees are served over http, because securing a site makes Herd reload its server and Valet ask for a password, for every worktree a tool makes; --secure leaves HTTPS to your site.secure setting instead. Run the installer again to change the options.
The adopt command has to run after anything else in the tool's setup that touches .env. Several of these tools copy your .env into each new worktree, or tell you to in their docs, and adopt is what rewrites it. A copy made after adopt points the worktree back at your main database.
These tools delete their worktrees on their own schedule, and the installer doesn't hook their delete or archive scripts: an archived Conductor workspace can be restored, and its databases should still be there when it is. Run worktree:prune to clean up after the worktrees they've deleted.
Conductor
Conductor uses the first setup script it finds, and your local settings come before the repository's .conductor/settings.toml or conductor.json. So once the installer writes .conductor/settings.local.toml, the repository's own setup script stops running for you; when it has one, the installer says so, and anything it does that adopt doesn't belongs in your local setup line, before the adopt command. A rerun replaces the file it wrote. A local file of your own is left alone, and the installer prints the line to add to it.
Conductor copies .env files into each workspace by default and starts its agent without waiting for the setup script, so until adopt has run, that agent's .env points at your main database. Leave .env out of Conductor's files to copy; adopt copies it from your main checkout itself. Adopt names the worktree after Conductor's workspace name.
Paradev
The installer adds the command to the end of the after list under setup in .superset/config.local.json, Paradev's config for you alone, so it runs after the repository's own setup commands. A rerun replaces it. Paradev starts a workspace's agent alongside its setup unless you turn on Settings > Experimental > "Wait for workspace setup before starting agents", so turn that on.
Paradev ignores every JSON config once .superset/config.toml exists. With one, the installer writes nothing and prints the command to add to its setup list.
Cursor
Cursor runs the commands in .cursor/worktrees.json in each worktree it makes:
{
"setup-worktree": [
"php worktree-adopt.php --tool=cursor --no-secure"
]
}
Cursor stops a setup after 300 seconds and starts its agent anyway. A setup that installs dependencies can take longer than that, so turn on copying dependencies. Adopt rewrites .env before it installs anything, so a stopped setup doesn't leave the worktree on your main database, and running php worktree-adopt.php in the worktree again finishes it.
Codex
In the ChatGPT desktop app's settings, under Local environments, set your project's setup script to:
php worktree-adopt.php --tool=codex --no-secure
Then choose that environment when you start a chat in a worktree. Codex copies the files .worktreeinclude lists before the setup script runs, and waits for the script before the chat starts. Its worktrees start on a detached HEAD, in a directory named after your repository, so adopt names each one by a short hash of its path.
Zed
Zed runs any task with a create_worktree hook in each worktree it makes. Add one to .zed/tasks.json, committed on the branch new worktrees start from:
[
{
"label": "Set up the worktree",
"command": "php",
"args": ["worktree-adopt.php", "--tool=zed", "--no-secure"],
"hooks": ["create_worktree"],
"reveal": "no_focus",
"hide": "on_success"
}
]
Zed starts its agent without waiting for the task. In a project Zed trusts, it runs git's hooks too, so the git hook works for Zed with nothing committed, and sets the worktree up inside git worktree add itself, before the add returns to Zed.
Devin Desktop
Devin Desktop runs its post_setup_worktree hooks in each worktree it makes:
{
"hooks": {
"post_setup_worktree": [
{
"command": "php worktree-adopt.php --tool=devin --no-secure",
"show_output": true
}
]
}
}
It reads the older .windsurf/hooks.json only while .devin/hooks.json is missing, so the installer prints the hook for whichever file your project already uses.
With a git Hook
Any tool that makes its worktrees with git worktree add, and you yourself, can have them adopted by a git hook:
php artisan worktree:install-agent git
That writes a post-checkout hook into your repository's own git directory (.git/hooks), where nothing is committed. git runs it when git worktree add checks out a new worktree, and the hook runs worktree:adopt for that worktree from your main checkout. Switching branches and checking out files don't run adopt, and neither does anything in your main checkout or in another repository. A worktree that switches back from an orphan branch looks new to git, so the hook asks adopt, which leaves it alone once it has been set up and still has its .env. The worktrees worktree:setup and Claude Code's hook make set themselves up and skip the hook. To make a worktree the hook should leave alone, set LARAVEL_WORKTREE_SKIP_ADOPT:
LARAVEL_WORKTREE_SKIP_ADOPT=1 git worktree add ../blog-scratch
Adopt runs inside git worktree add, so the add takes as long as the setup. If adopt fails, git worktree add still succeeds, since git keeps the new worktree either way: the error says what went wrong, and php artisan worktree:adopt <path> picks up where it stopped. The hook names its worktrees the way adopt always does, by a short hash of the path, never the branch. A worktree in the exact directory worktree:setup gives its branch is refused, with the setup command to run instead. The hook starts PHP and artisan by their full paths, so run the installer again after you move the project or remove that PHP version. A rerun replaces the whole hook file. Nothing runs when git removes a worktree, so worktree:prune cleans up after the ones you or a tool removed.
Cursor, Codex and Claude Code run no git hooks for the worktrees they make, so Cursor and Codex need their setup scripts above, and Claude Code its own hooks. Without them, a claude --worktree worktree gets your main .env when .worktreeinclude lists it. Zed, in a project it trusts, and Paradev run git's hooks, so with the hook installed their worktrees are adopted inside git worktree add, before the tool's own setup runs. If that setup copies .env, the copy lands after adopt and points the worktree back at your main database, so set such a tool up with its own installer instead; the git installer warns when it finds Conductor's or Paradev's settings. With both in place, the tool's setup would adopt each worktree a second time, and the tool installers warn when they find the hook.
A post-checkout hook another tool wrote (git-lfs writes one) is left alone, and the installer prints the lines to add at the end of it. It does the same when core.hooksPath points git at another hooks directory, such as one a hook manager owns. Those lines hold paths on your machine, so keep them out of a hooks directory you commit.
Claude Code
Claude Code makes worktrees of its own: when you start it with claude --worktree, when it moves into one during a session, for a background session, and for every subagent that runs with isolation: worktree. A worktree Claude makes by itself gets your code and, when .worktreeinclude lists it, a copy of your .env, which still points at your main database. Install this package's hooks and Claude asks worktree:hook for each worktree instead:
php artisan worktree:install-agent claude
That writes a WorktreeCreate and a WorktreeRemove hook into .claude/settings.local.json, your own settings for the project. A WorktreeCreate hook replaces how Claude makes every worktree, so it belongs to each developer rather than to the shared .claude/settings.json. The installer adds /.claude/settings.local.json to .git/info/exclude, the ignore list git keeps for your clone alone, which every worktree reads and nothing commits, and warns when the file is committed. It refuses to run when either file already has a hook for those events: Claude runs every hook it finds, and two of them would both make the worktree. Hooks in your user settings or a plugin run as well, and /hooks in Claude Code lists everything that will.
Each worktree Claude asks for then gets what worktree:setup gives a branch: its own databases, .env, dependencies and site. The branch is named after the name Claude picked (worktree-bold-oak-a3f2), and the directory follows your path setting. If a step fails, the hook removes the worktree and databases that run made before it exits, since Claude never learns where a failed worktree is. When Claude comes back to a worktree it asks for it again, and the hook hands it back as it is instead of migrating or cloning over its data.
Claude Code won't start claude --worktree in a folder you haven't trusted yet, so run claude once in the project and accept the trust dialog first.
The installer takes these options and writes them into the hook:
| Option | What it does |
|---|---|
--base=develop |
Branch off develop. Without it, the configured base branch, or the branch checked out in your main repository when the configured one doesn't exist. The branch is written into the hook, so run the installer again after you change base_branch |
--secure |
Leave HTTPS to your site.secure setting, as worktree:setup does (Herd secures by default). Without it the worktrees are served over http, because securing a site makes Herd reload its server and Valet ask for a password, for every worktree an agent makes |
--clone, --no-clone, --seed, --no-migrate, --no-database, --no-install |
Passed on to every setup the hook runs, as on worktree:setup |
--timeout=1800 |
Seconds Claude gives each hook before stopping it. A setup stopped partway is set up again the next time Claude asks for that worktree |
Run the installer again to change the options; it replaces the hooks it wrote. Claude starts the hooks without a shell, so they name PHP and your app's artisan by their full paths: run the installer again after you remove the PHP version it ran on, or move the project. To stop using the hooks, delete the two entries under hooks in .claude/settings.local.json.
With a WorktreeCreate hook in place, Claude Code no longer reads .worktreeinclude, so the files it lists stop reaching new worktrees, and the installer says so when you have one. Gitignored env files go under env.copy instead.
Claude Code on Windows reads a session's local settings from the folder the session works in, so a session inside a worktree would miss the hooks in your main checkout's .claude/settings.local.json. The create hook therefore copies that file into each worktree it makes, and into one it hands back without a copy. It copies only when git ignores the file in the worktree, which the installer's exclude line makes sure of, since an unignored copy would be uncommitted work that the remove hook refuses; otherwise it warns and carries on without it. A copy the worktree already has is left as it is, so running the installer again doesn't update the worktrees you have: delete the copy in a worktree you keep using, and the hook copies the new one the next time Claude asks for that worktree.
When you exit a worktree session, Claude Code asks whether to keep or remove the worktree, with Keep as the default. It asks for every worktree the hook made, unnamed ones included, because it can't tell what they hold. Remove runs the WorktreeRemove hook, which finishes the worktree the way worktree:teardown --abandon does: it drops the databases, stops serving the site and deletes the directory. It keeps the branch, so whatever you committed there stays, and Claude never deletes a hook's branch either. A session you leave without committing anything therefore leaves its worktree-... branch behind for git branch -d. The hook refuses to remove a worktree with uncommitted or untracked changes, or with commits no branch holds, and only removes worktrees it made.
On Windows, a program still sitting in the worktree's folder (Claude Code itself can be one) keeps the empty folder there after everything else is gone. The hook counts the worktree as removed and says so, and the folder can be deleted once that program exits. A session that runs without the hooks, because the settings file wasn't copied, removes the worktree Claude's own way, which on Windows can leave the folder holding only its .git file, still listed by git and with its databases in place. Teardown finishes it by its branch:
php artisan worktree:teardown worktree-bold-oak-a3f2 --abandon --keep-branch
Subagent Worktrees
When a subagent or workflow agent finishes, Claude Code keeps the worktree the hook made for it and never runs the WorktreeRemove hook, so each one stays, databases included. worktree:list shows them with claude in the Tool column, and teardown finishes each by its branch like any other worktree:
php artisan worktree:teardown worktree-agent-ae9d3dae39ccf408e --into=main
Running the Hook by Hand
worktree:hook reads Claude's JSON from stdin, so to try it yourself, pipe some in:
echo '{"name": "try-it"}' | php artisan worktree:hook claude create
Started from a terminal with nothing piped in, it stops with an error instead of waiting. A terminal or editor panel that connects stdin to a pipe it never closes makes it wait for that input to end.
Finishing a Worktree
When the work is done, run:
php artisan worktree:teardown
It lists your worktrees, asks how you want to finish, and then cleans up. Name the worktree by its branch, its directory, or the name it was adopted under to skip the first question, and use flags for the rest:
# Push the branch and open a pull request with the GitHub CLI php artisan worktree:teardown feature/login --pr # Merge the branch into main, then clean up php artisan worktree:teardown feature/login --into=main # Throw the branch away php artisan worktree:teardown feature/login --abandon --force
--pr commits any pending changes first, pushes the branch, and opens the PR with gh. Set the commit message with --message="..." if you don't want the default.
Leave --into off and you'll be asked which branch to merge into. Because the merge happens in your main repository, that's the branch you'll be left on afterwards.
Whichever path you pick, the cleanup is the same: drop the application and test databases, stop serving the site, remove the worktree, and delete the branch (except after a pull request, where the branch stays for the open PR). Pass --keep-database if you want the databases left alone, and --keep-branch to keep the branch whichever way you finish.
Teardown goes by what setup recorded. It stops serving the site through the driver that served it and drops the databases setup created, even if you've changed a name template or switched to another server since. A recorded database is only dropped on the server it was created on: if its connection now points somewhere else, teardown leaves it there and tells you. A worktree made by a release that kept no record is worked out from its name instead, never from the copied .env, as long as it still has the name setup gives its branch's worktree. One that doesn't (its branch was switched or detached, or the host template changed) keeps its site and databases, and teardown tells you, since a worktree another tool made looks the same. Either way, teardown refuses outright to drop a database matching any of your main repository's databases, ignoring case, since MySQL on Windows and macOS does too.
Sometimes git can't delete every file in a worktree, because another program holds one open or a path runs past Windows' 260-character limit. Git has already unregistered the worktree by then, so teardown deletes the leftovers itself and carries on, rather than stopping with the databases and branch still around. Teardown also passes git core.longpaths, so a deep vendor tree on Windows doesn't cause that failure in the first place. A worktree git refuses to remove on purpose, because it's locked or has changes you didn't --force, still stops the teardown.
A worktree left in detached HEAD state has no branch to push or merge, so --pr and --into refuse it with a clear message. Finish it with --abandon, which still drops the databases setup recorded for it.
Pruning Gone Worktrees
Agent apps and editors clean up their own worktrees by deleting the directory, and people do the same by hand. Nothing runs teardown then, so the site stays linked and the databases stay on your server. worktree:prune finds the worktrees the package recorded whose directory is gone:
php artisan worktree:prune
On its own it only lists them, with the site driver that served each one and the databases it was given. A directory can also be missing because you moved it or its drive isn't mounted, so read the list before you clean up:
php artisan worktree:prune --force
For each one, --force stops the site through the driver that served it and drops the databases its record names, with the same checks teardown makes: a database is dropped only on the server it was created on, and never one matching your main databases. It also deletes the worktree's SQLite files next to a main database outside the repository, forgets the record, and runs git worktree prune. It drops nothing the record doesn't name, so the blog_feature_login_test_1 databases a parallel test run left stay until you clear them with --orphans below. When the server that served a site isn't installed any more, prune says which site to stop by hand. A worktree keeps its record, and its databases, when one of them is in use by your main app or another worktree now (your .env.testing points at it, say), when a guard refuses a drop, or when its database server can't be reached, so the next run can look again.
git worktree prune clears git's own entry for every worktree whose directory is gone, whichever tool made it. That touches no site or database, but it does cut off a worktree folder you moved or renamed by hand: git can no longer find it. Run git worktree repair <new path> for such a folder before pruning, and git and prune then see it where it is.
Prune leaves a gone worktree alone when another worktree seems to have taken its place: one with its branch checked out, one under its name or site name, or one that records or names one of its databases. That's what a worktree moved with git worktree move looks like. When exactly one such worktree has no record of its own and its .env or PHPUnit config names the gone one's databases, --force moves the record there, so teardown finds it later. Run prune before adopting a worktree you moved: adopt refuses one that uses a gone worktree's databases, since adopting it afresh would give it new, empty ones. A worktree git has locked (git worktree lock, the usual way to keep one on a removable drive) is skipped as well. Setup and adopt tell you when recorded worktrees are gone, and leave the cleanup to prune.
Databases Nothing Claims
Some databases outlive their record. teardown --keep-database forgets the worktree and keeps its databases, a worktree made by a release that kept no record leaves nothing to find them by, and prune leaves a gone worktree's parallel-test databases. --orphans looks on each configured server for databases named the way this repository's worktrees are (blog_ and then anything, in a repository called blog). It leaves out every name a record or a worktree git still lists accounts for, and every database your main app uses: those its .env, its PHPUnit config and every env.copy file (.env.testing by default) name, and every connection's database in config/database.php.
php artisan worktree:prune --orphans php artisan worktree:prune --orphans --force
The first command lists them. With --force, prune also cleans up after gone worktrees as above, then asks about each of these databases by name and drops only the ones you say yes to. The answer defaults to no, and a run that can't ask (--no-interaction, or no terminal) drops none of them. Another project on the same server may use matching names, blog_admin say, so read each name before you answer. Databases from a name template that doesn't include the repository's name before the worktree's, such as a host template of {branch} alone, could belong to anything on the server, so prune doesn't look for them. Neither does it when the repository's name is long enough that worktree names get cut short.
Listing Worktrees
worktree:list shows every worktree of the repository, along with the URL and database each one was provisioned with:
php artisan worktree:list
---------------- -------------------------------------- ------- ---------------------------------- ---------------------
Branch Path Tool URL Database
---------------- -------------------------------------- ------- ---------------------------------- ---------------------
feature/login /Users/you/Sites/blog-feature-login setup https://blog-feature-login.test blog_feature_login
feature/search /Users/you/Sites/blog-feature-search setup https://blog-feature-search.test blog_feature_search
---------------- -------------------------------------- ------- ---------------------------------- ---------------------
The Tool column says what made each worktree: setup, adopt (or the tool that made it, such as --tool=cursor), or claude for one Claude Code's hook made. A worktree with no record shows -.
For a worktree setup recorded, these are the URL and databases it was set up with, even after your config changes; an older worktree's are worked out from the config, and a worktree that has no record and isn't named the way setup names its branch's worktree shows neither. The URL column shows - when the site driver serves nothing. The Database column only appears when a connection has a database the package named: a server database (MySQL, MariaDB, or PostgreSQL), or the SQLite file it places next to a main database kept outside the repository. A SQLite file inside the worktree belongs to the worktree's own .env, so there's no single name worth printing.
Finding a Worktree
worktree:path prints where a branch's worktree lives, or an adopted worktree's, given the name it was adopted under. It creates nothing and touches nothing:
php artisan worktree:path feature/login
# /Users/you/Sites/blog-feature-login
A branch that's checked out in a worktree gives that worktree's directory, wherever it is. Otherwise the path is resolved from your config rather than guessed, so it stays correct even after you change path or the host template. That's what makes the cd in the Warp tab configs below land in the right place.
Configuration
Every part of the workflow is driven by config/worktree.php, so the package adapts to your stack instead of forcing one setup. Here are the parts you're most likely to touch.
Worktrees go next to your project by default. Set path (WORKTREE_PATH) to a nested directory such as .worktrees to keep them inside it instead, and add that directory to your .gitignore, or the worktrees show up as untracked files in the main repository's git status.
Site Drivers
A site driver serves each worktree as a local site during setup and stops serving it during teardown. Pick one with site.driver:
'site' => [ 'driver' => env('WORKTREE_DRIVER'), 'secure' => env('WORKTREE_SECURE'), 'timeout' => 60, ],
| Driver | Serves the worktree with |
|---|---|
auto |
Herd when the herd command is installed, otherwise Valet when valet is, otherwise nothing |
herd |
Laravel Herd on macOS or Windows: herd link, then herd secure for HTTPS |
valet |
Laravel Valet on macOS, valet-linux on Linux, or valet-windows on Windows: valet link, then valet secure |
command |
Commands you configure, for any server with a command line |
none |
Nothing. Use it when you serve the site some other way, or not at all |
A class of your own works too. Leave site.driver empty and auto decides, unless your config still sets the older herd option.
site.secure (WORKTREE_SECURE) serves the site over HTTPS. Left empty, Herd secures it and every other driver serves plain HTTP, since Valet asks for a password to secure a site.
Setup writes the site's address to APP_URL, such as https://blog-feature-login.test. With none it still writes http://blog-feature-login.test, so a site you serve by hand later needs no .env change. Set env.app_url_key to null to skip that; the host rewrite still swaps your main site's host for the worktree's. Setup's summary shows the URL row only when the driver served the site, and worktree:list shows - in its URL column under a driver that serves nothing.
The host is the worktree's site name plus host.tld (test by default). The package doesn't ask your server for its TLD, so if you changed it there, set WORKTREE_TLD to match.
The herd and valet drivers run the command of that name from your PATH. If yours lives elsewhere, put its full path in site.drivers.herd.binary or site.drivers.valet.binary. A driver you chose by name whose command can't be found serves nothing: setup warns, writes an http:// address, and carries on. auto moves on to the next server without a warning.
A server's command line can hang while it waits on something you can't see, like a dialog in the Herd app or a password prompt. Each driver command gets site.timeout seconds (0 turns the limit off). One that runs out is stopped, setup or teardown warns you, and the driver's remaining commands are skipped and listed by name, so you can run them yourself once the server responds. Everything else carries on.
Herd
The worktree is always linked before it's secured. Herd only serves parked and linked directories, and a worktree in a nested path such as .worktrees is neither, so herd secure alone would create a certificate for a site that never answers.
Herd's command line can report success when the Herd app never did the work, and it links in the background. So after herd link, setup reads herd links for up to five seconds and secures the site once Herd lists it, or when the list can't be read. A site Herd never lists isn't secured, and setup warns with the commands to run by hand. Running setup again on a worktree Herd already serves doesn't link it a second time, because herd link also runs php artisan boost:update in a worktree that has Laravel Boost installed.
Herd links sites by name, so a second clone of your repository that sets up the same branch takes over the worktree's site name. Teardown and worktree:prune read herd links --json before they run herd unlink, and when Herd serves the name from another folder, they leave that site alone and say so. Both name the site and run from your main checkout, so they don't need the worktree folder to still be there. Running setup again on a worktree whose name Herd serves from another folder links it to the worktree again, with a warning.
Herd 2 can also serve a git worktree itself, as a site under your main one: open feature-login.blog.test for a worktree of feature/login in blog, and Herd offers to serve it. Don't accept that offer, or run herd workspace inside the worktree, for a worktree this package set up: Herd links it a second time under that address and points its APP_URL there. Teardown doesn't remove a site Herd added itself. It names the site, and herd unlink feature-login.blog removes it.
Valet
One driver covers Laravel Valet, valet-linux, and valet-windows, since all three take the same commands. They ask for a password or for elevation more often than Herd does:
- macOS: Valet runs most of its commands through
sudo. Runvalet trustonce, or setup waits on a password prompt until the timeout stops it. - Linux: valet-linux asks for
sudoto secure a site and to remove a secured one. - Windows: run setup and teardown from an elevated terminal, or valet-windows asks for elevation.
Teardown and worktree:prune remove the site with valet unlink from your main checkout. When the worktree folder is already gone, they read valet links first, and leave the site alone with a warning when Valet serves its name from another folder.
The command Driver
Any server with a command line can serve worktrees through command. Configure up to five commands under site.drivers.command:
| Command | When it runs | Where it runs |
|---|---|---|
serve |
During setup; required | In the worktree |
secure |
After serve, when site.secure is on |
In the worktree |
check |
After serve and secure, to confirm the server lists the site |
In the main repository |
unsecure |
During teardown, for a secured site | In the main repository |
unserve |
During teardown | In the main repository |
Each command is a list of arguments, or one string split on its spaces. A string doesn't go through a shell, so quotes don't group anything: use a list when an argument holds a space. serve and secure take every worktree token ({repo}, {branch}, {name}, {slug}, {site}, {host}, {tld}) plus {path}, the worktree directory. check, unsecure, and unserve know a site only by its name and directory, since teardown can meet a worktree with no branch, so they take {name}, {site}, {path}, {host}, and {tld}. In all five commands {name} is the site name, the same as {site}, so a serve and an unserve written with {name} always name the same site.
The check passes when its output names the site, alone or followed by .{tld}: blog-feature-login and https://blog-feature-login.test both count, blog-feature-login-v2 doesn't. Leave unserve empty for a server that can't remove a site, and teardown reminds you to remove it by hand. Choosing command without a serve command is an error.
Yerd on macOS or Linux, for example:
'site' => [ 'driver' => 'command', 'drivers' => [ 'command' => [ 'serve' => ['yerd', 'link', '{name}', '{path}'], 'secure' => ['yerd', 'secure', '{name}'], 'check' => ['yerd', 'sites'], 'unsecure' => ['yerd', 'unsecure', '{name}'], 'unserve' => ['yerd', 'unlink', '{name}'], ], ], ],
EnvKit on Windows or macOS registers a folder with envkit sites-link and removes the site with envkit sites-remove, which leaves the files on disk:
'command' => [ 'serve' => 'envkit sites-link {path}', 'unserve' => 'envkit sites-remove {name}', ],
EnvKit names a site after its folder. For a repository or branch name with capitals or _, the worktree's site name lowercases them and turns _ into -, so it may not be the name EnvKit gave the folder. Then sites-remove fails, teardown warns, and you remove the site in the EnvKit app.
Laragon on Windows serves every project folder in its www directory as {folder}.test once it reloads. Keep your project in www with the default path of .., and each worktree lands there too, in a folder named after it. Laragon's only command reloads it, and the Laragon app has to be running for it:
'command' => [ 'serve' => ['C:\laragon\laragon.exe', 'reload'], ],
Laragon can't remove a site from the command line. After teardown, delete the worktree's auto.{host}.conf file from Laragon's etc\nginx\sites-enabled (or etc\apache2\sites-enabled) and reload.
Writing Your Own Driver
When none of these fits, write a class for your server and put its name in site.driver:
'driver' => App\Worktree\YerdDriver::class,
The class implements Mozex\Worktree\Contracts\SiteDriver. Laravel's container builds it, so its constructor can ask for whatever it needs. It never starts a process itself: it hands each command, as a list of arguments, to the runner it's given. The runner keeps your main app's .env values out of the command's environment and applies site.timeout. Its run() returns null for a command that didn't run to its end, after warning about it. Here's the Yerd recipe above as a class:
namespace App\Worktree; use Mozex\Worktree\Contracts\SiteDriver; use Mozex\Worktree\Contracts\SiteRunner; use Mozex\Worktree\Worktree; use Symfony\Component\Process\ExecutableFinder; class YerdDriver implements SiteDriver { public function available(): bool { return (new ExecutableFinder)->find('yerd') !== null; } public function url(Worktree $worktree, bool $secure): ?string { return ($secure ? 'https' : 'http').'://'.$worktree->host(); } public function serve(Worktree $worktree, bool $secure, SiteRunner $runner): bool { $name = $worktree->site(); if ($runner->run(['yerd', 'link', $name, $worktree->path()])?->successful() !== true) { $runner->warn("Yerd could not link [{$name}]."); return false; } if ($secure && $runner->run(['yerd', 'secure', $name])?->successful() !== true) { $runner->warn("Yerd could not secure [{$name}]."); return false; } return true; } public function isServed(string $name, string $path, SiteRunner $runner): ?bool { return null; } public function unserve(string $name, string $path, bool $secure, SiteRunner $runner): void { if ($secure) { $runner->run(['yerd', 'unsecure', $name]); } $runner->run(['yerd', 'unlink', $name]); } public function timeoutHint(): string { return 'Check that the Yerd daemon is running.'; } }
What each method is for:
available()says whether the server is installed. A driver that isn't available serves nothing.url()is the address the site answers at, ornullwhen the driver serves nothing.serve()links the worktree under its site name,$worktree->site(), and secures it when asked. It returnsfalsewhen that didn't work, and setup then leaves the URL out of its summary.isServed()says whether the server lists the site, ornullwhen the driver can't tell.unserve()gets the site name, a path, and whether the site was secured, not aWorktree, because the worktree may have no branch and its directory may already be gone.timeoutHint()is added to the warning when a command runs out of time.
Every method is best effort: report a problem with $runner->warn() rather than throwing, so setup and teardown can finish. The interface won't gain methods in later 1.x releases; anything new arrives as a separate interface a driver can choose to implement.
A driver for a server many people use belongs in the package, and pull requests for one are welcome. The repository's CLAUDE.md lists the places a driver is registered and how its commands are tested against a stand-in for the real server.
The Older herd Option
Configs published by earlier versions choose the server with herd (WORKTREE_HERD), and it still works while site.driver is empty. secure serves through Herd over HTTPS, link through Herd over HTTP, and none serves nothing. Any other value is read as secure, as it always was, and setup warns about it.
Those configs set herd to secure unless you changed it, so they keep using Herd. To let the package find your server instead, set WORKTREE_DRIVER=auto.
Lerd
When Lerd serves a site, it sets up every new git worktree of that site by itself. If it serves your repository, Lerd and worktree:setup would both provision the same worktree at once. So when Lerd is installed, setup warns if your repository holds a .lerd.yaml file or lerd sites lists it. Let one of the two set worktrees up. To turn the check off, set site.lerd.binary to null.
Site Names
Each worktree is served under a site name, and its host is that name plus the TLD. By default the site name is the worktree's name, so blog on branch feature/login is served at blog-feature-login.test. Between its dots a host can only hold lowercase letters, digits and hyphens, so the site name is cleaned up to match: branch Feature_Login keeps the directory blog-Feature_Login and the database blog_feature_login, and is served at blog-feature-login.test.
host.site (WORKTREE_SITE_TEMPLATE) changes the site name without moving a directory or a database. It takes {name}, {repo}, {branch} and {slug}. Set it to {branch}.{repo} to serve each worktree under your main site's host:
'host' => [ 'template' => '{repo}-{branch}', 'site' => '{branch}.{repo}', ],
Branch feature/login is then served at feature-login.blog.test, and its directory is still blog-feature-login. A site name that would come out as your main site's own name, or empty, gets a short hash added (blog-3f9a1c), so a worktree is never served over your main site. Setup refuses a worktree whose site another worktree already has: branches feature-x and feature-x_ get different databases, but both would be served as blog-feature-x.
A worktree keeps the site it was first served under. A new host.site applies to the worktrees you set up afterwards, while running setup again on an existing worktree, or tearing it down, goes by the site the package recorded. A worktree set up by a version from before site names is served under its worktree name, as it always was.
If your main app sets SESSION_DOMAIN=.blog.test, browsers send its cookies to feature-login.blog.test too, under the same names. So setup gives a worktree served under your main site's host a session cookie of its own, SESSION_COOKIE=blog_feature_login_session, and the two apps don't log each other out. A SESSION_COOKIE entry in env.replace wins over it. Laravel's XSRF-TOKEN cookie can't be renamed, though, so JavaScript in the worktree may still send your main app's token and get a 419. Leave SESSION_DOMAIN empty in your main .env while you use subdomain sites. And when your main site is served over HTTPS, serve the worktrees over HTTPS too (site.secure, and --secure for the agent installers): Herd's and Valet's HTTPS setup for blog.test also answers *.blog.test and sends plain-http requests on to https, under the main site's certificate.
Herd 2 serves the worktrees it takes over itself at addresses of this same shape. How Herd treats a worktree this package already serves at such an address hasn't been checked yet, so if you also use Herd's own worktree feature on the repository, keep the default site names. With either kind of name, leave alone Herd's offer to serve these worktrees itself, as Herd explains.
Long Names
A host has to fit in a TLS certificate, which holds 64 characters at most. A long repository name plus a long branch would break securing the site, so the worktree name is capped to keep the whole host (.test included) within 63 characters. A longer name is cut and given a short hash, so two long branches never share a name. The directory and database names derive from the same capped name. A worktree an older version created under its full name keeps that name: every command recognizes it by its directory, so it still resumes, lists, and tears down with the databases it really has. A site template gets the same cap on its own: when {branch}.{repo} runs long, the branch part is cut and hashed, so the site stays under your main site's host.
Databases
Each worktree gets its own database on every connection you list under database.connections, so two branches never share data. What that means depends on the driver, because the isolation problem is different for each.
MySQL, MariaDB, and PostgreSQL put every worktree on one shared server, so each worktree gets a database of its own, named after it (blog_feature_login). The name is lowercased, with anything that isn't a letter or number turned into an underscore, so it stays valid everywhere. A name that would blow past the server's identifier limit (64 characters on MySQL, 63 on Postgres) gets cut and given a short hash, so a long repo plus a long branch can't produce a name the server rejects. Postgres works too: databases are created against the postgres maintenance connection and dropped WITH (FORCE), which needs PostgreSQL 13 or newer. Teardown drops every database it made, plus the {name}_test_{token} databases parallel test runs derived from them (paratest worker databases, mozex/laravel-test-lanes lanes), so they never outlive the worktree. A name like that which is another worktree's own database stays: branch feature/login-test-2 gets blog_feature_login_test_2, which looks like a lane of feature/login. If teardown can't read what the other worktrees use, it drops none of these and says so.
The server is reached through the connection's host, port, username, and password values. A connection configured through a single DB_URL or a unix_socket isn't parsed, so give the connection explicit host values if you use one of those.
SQLite usually needs none of that. The database is a file inside your project, so the worktree already has its own copy and nothing has to be named, created on a server, or dropped afterwards. The package makes sure the file exists so migrations can run, and leaves it alone otherwise. When DB_DATABASE holds an absolute path back into the main checkout, it gets repointed at the worktree so the two don't share a file.
A SQLite file kept outside the repository (DB_DATABASE=/Users/you/databases/blog.sqlite, or a relative path that climbs out, like ../databases/blog.sqlite) would be shared by every worktree, and the first migrate:fresh in one of them would wipe your main data. So it's treated like a server: the worktree gets a file of its own next to the main one, named by the connection's name template (/Users/you/databases/blog_feature_login.sqlite), and teardown deletes it. Setup refuses a template that would name the main file itself.
A stock app never touches this config. The shipped entry covers the default connection, and null means "whatever DB_CONNECTION resolves to," so it works whether you develop on SQLite, MySQL, or Postgres:
'database' => [ 'connections' => [ [ 'connection' => null, // null is the app's default connection 'env' => 'DB_DATABASE', // the .env key holding this database's name 'name' => '{slug}', // the worktree database name 'test' => [ 'env' => 'DB_DATABASE', // the phpunit.xml <env> key to rewrite 'name' => '{slug}_testing', ], ], ], ],
The {slug} token is the worktree name, lowercased with each run of non-alphanumerics collapsed to one underscore. The {repo}, {branch}, {name}, {site}, {host}, and {tld} tokens work here too.
The database.migrate option controls what happens after creation. fresh runs migrate:fresh, which gives you a clean schema every time, even when you reuse a branch name and its old database is still lying around. Use migrate for a plain migration, or none to handle it yourself. With cloning on, fresh runs a plain migrate instead, so the copied data survives. Only the default connection is migrated; a second connection is migrated by your own migrations pinning their connection, or by a provisioning step.
Test Databases
If your suite runs against a real database server, each connection with a test block gets a second database for tests, and its name is written into phpunit.xml, so running tests in a worktree can never touch your development data:
<env name="DB_DATABASE" value="blog_feature_login_testing"/>
For the default connection, the package reads phpunit.xml to work out which connection your tests run on and creates the test database there. So a project that develops on SQLite but tests against MySQL gets its test database on MySQL, and teardown drops it from the same place. A stock Laravel app pins its suite to an in-memory SQLite database, which is already isolated, so nothing is created and nothing is rewritten. A named connection keeps its own name in tests. Leave the test block off a connection to skip a test database there.
The rewrite is marked skip-worktree in the worktree's own git index, so the change never shows up in git status and never lands in a commit. Your phpunit.xml is a tracked file, and without that the worktree would look permanently dirty.
Running a second suite from a second config? List it. database.phpunit_files defaults to ['phpunit.xml', 'phpunit.xml.dist'], and every listed file that exists gets patched, each one read for the connection its own suite runs on:
'phpunit_files' => ['phpunit.xml', 'phpunit.browser.xml'],
A file you leave out keeps whatever test database name your main checkout put there, and that's the database its suite runs against from inside the worktree. Nothing errors, nothing looks wrong, and one of your suites is quietly sharing a database with the main repo. Leave out the configs that only run on CI, though: those name a database on the CI runner, not on your machine.
Multiple Connections
Some apps talk to more than one database: a main connection plus an analytics or reporting one, say. List each connection you want isolated, and every worktree gets its own database on all of them, kept apart in development and in tests.
You have to name the env key yourself, and there's a reason the package can't guess it. Laravel resolves env() at boot, so the connection config it hands back holds the database value, not the variable it came from, and there's no way back. So each entry spells it out:
'database' => [ 'connections' => [ [ 'connection' => null, 'env' => 'DB_DATABASE', 'name' => '{slug}', 'test' => ['env' => 'DB_DATABASE', 'name' => '{slug}_testing'], ], [ 'connection' => 'analytics', // the name from config/database.php 'env' => 'ANALYTICS_DB_DATABASE', // this connection's .env key 'name' => '{slug}_analytics', 'test' => ['env' => 'ANALYTICS_DB_DATABASE', 'name' => '{slug}_analytics_testing'], ], ], ],
Setup creates each database, rewrites each env key in the worktree's .env, and writes each test database into every configured PHPUnit file. Both commands guard your real data the same way. If any worktree name, application or test, matches the main database of any listed connection (ignoring case, as MySQL on Windows and macOS does), setup stops before it creates anything and teardown refuses to drop it, so a bad template can't take out your main databases. Give each connection a distinct name. If two would land on the same server with the same name, setup stops before touching anything.
Cloning Your Data
A new worktree database starts empty: migrated, maybe seeded, but without the users, orders, and settings you've built up locally. When you'd rather start the branch from that data, clone it:
php artisan worktree:setup feature/login --clone
Or turn it on for every worktree:
'database' => [ 'clone' => [ 'enabled' => true, // or WORKTREE_CLONE=true in .env ], ],
Setup copies each connection's database from your main checkout into the worktree's, then runs migrate instead of migrate:fresh. The copy survives, and only the branch's own new migrations run on top of it. When the config has cloning on, --no-clone turns it off for a single run.
How the copy is made depends on the driver:
- MySQL and MariaDB copy on the server, table by table, with
INSERT ... SELECTbetween the two databases. No rows pass through PHP and you don't needmysqldump. Foreign keys, generated columns, views, triggers, and stored routines come along, and auto-increment counters carry on where your main database left off. - PostgreSQL creates the worktree database with your main one as its template, which copies the files directly. Postgres refuses a template copy while anything else is connected to the source, and a running queue worker or an open database GUI is enough for that. In that case setup falls back to
pg_dumpandpg_restore, which need to be on your PATH. It never disconnects anyone from your main database to make the template copy work. - SQLite writes a snapshot of the file with
VACUUM INTO, so rows still sitting in a WAL file make it into the copy.
Some tables shouldn't bring their rows along. The queue's pending jobs matter most: a worker running in the worktree would process them a second time, and a job can send real email. Tables listed under structure_only are created with their schema and no rows:
'clone' => [ 'structure_only' => [ 'jobs', 'job_batches', 'failed_jobs', 'cache', 'cache_locks', 'sessions', 'telescope_*', 'pulse_*', ], ],
That's the default list. Names accept * wildcards and match with or without the connection's table prefix. If you renamed the queue tables, add the new names. Setting your own list replaces the default rather than adding to it, so keep the entries you still want. It's also the place for a huge table whose rows the branch doesn't need, like an event log.
A few things to know:
- Test databases are never cloned. They start empty, the way your suite expects them.
- Running setup again on the same branch clones again, replacing the worktree's data with a fresh copy, the same way
migrate:freshwould reset it. - The
database.seedsetting doesn't apply to a cloned database, because seeding on top of real data duplicates rows. Pass--seedif you want it anyway. - Every connection in
database.connectionsis cloned. They go together because Laravel records every migration, including those pinned to a second connection, in the default connection'smigrationstable. - If your main database doesn't exist yet, setup warns and starts the worktree from an empty one.
- On MySQL, rows are read without locking them, so your main app keeps writing while a clone runs. The copy also stays out of the binary log when your account may turn it off. A server that logs in
STATEMENTformat and won't let you do that refuses lock-free reads, so there the copy reads the usual locking way instead. - A table that keeps its rows may have a foreign key into a
structure_onlytable. MySQL and SQLite copy it anyway, leaving those keys pointing at rows that weren't copied. Postgres won't empty such a table withTRUNCATE, so its rows are deleted with foreign keys unenforced, which needs a Postgres superuser. Without one, setup says so.
Host Rewriting
When host.remap_source_host is on, every mention of the old host in the copied .env is repointed at the worktree. So blog.test becomes blog-feature-login.test across APP_URL, mail addresses, and any custom domain keys you keep. A cookie domain written with a leading dot comes along too, so SESSION_DOMAIN=.blog.test becomes .blog-feature-login.test and your worktree's sessions actually work.
Hostnames that only happen to contain the old one are left alone. myblog.test, sub.blog.test, and blog.testing are all different sites, and none of them get touched.
Extra Env Files
Gitignored env files never arrive through git worktree add, so a project that keeps a .env.testing would end up with a worktree whose suite can't boot. The env.copy option fixes that:
'env' => [ 'copy' => ['.env.testing'], ],
Each listed file is copied from the main repository into the worktree when it exists, with the host rewrite and your environment replacements applied and nothing else changed. Files that git already placed (tracked ones) are left alone. And a file that exists but isn't gitignored is skipped with a warning, because the copy would sit in the worktree as an untracked file, block a merge teardown, and ride into a --pr commit.
A stock Laravel .gitignore covers .env but not .env.testing, so add .env.testing to your .gitignore if you keep one. Until you do, setup skips it with that warning.
Environment Replacements
The database name and the host are rewritten for you, but some values need to be worktree-specific in ways this package can't know about in advance. A Redis key prefix, a cache prefix, a queue name: leave them shared and two worktrees end up writing over each other. The env.replace option rewrites any env key you name, without the package hardcoding a handler for each one:
'env' => [ 'replace' => [ 'REDIS_PREFIX' => '{slug}-database-', 'CACHE_PREFIX' => '{slug}-cache-', ], ],
Each entry is a key and a template. The template is expanded with the same worktree tokens used everywhere else, {repo}, {branch}, {name}, {slug}, {site}, {host}, and {tld}, plus one more: {value}, which stands for the key's current value in the copied file. A key that isn't in the file yet is added.
Write the whole value unless your .env sets the key. A stock Laravel app leaves REDIS_PREFIX and CACHE_PREFIX out of .env and builds them in config from APP_NAME (laravel-database-, laravel-cache-), so for those keys {value} is empty, and that's why the example above spells the prefixes out. Use {value} for a key your .env does set: with REDIS_PREFIX=shop_ in .env, {value}{slug}_ gives shop_blog_feature_login_.
The rewrites run on the copied .env and on every file in env.copy, so a .env.testing is isolated the same way. The keys the package already manages, DB_DATABASE and APP_URL along with the host remap, stay separate and aren't configured here.
Copying Dependencies
Every worktree installs the same vendor and node_modules your main checkout already has. When a branch doesn't touch its dependencies, that install is wasted time. Turn on copying and the package copies the directory from the main repository instead, but only when it's safe:
'dependencies' => [ 'vendor' => ['copy' => true, /* ... */], 'node_modules' => ['copy' => true, /* ... */], ],
Safe means the worktree's lock file is byte-for-byte the main repository's. If the branch changed composer.lock or package-lock.json, the copy would be stale, so the package installs from scratch instead. You get the speed on the common path and the correct install on the branch that bumped a package, with nothing to remember.
A copy skips the downloading, unpacking, and install scripts an install runs, so it finishes in a fraction of the time. A copied vendor boots and a copied node_modules builds, because both are portable within one machine.
Copying is off by default. Flip it with WORKTREE_COPY_VENDOR and WORKTREE_COPY_NODE_MODULES, or per entry. An entry whose manifest is missing from the worktree is skipped, so an app with no package.json never runs npm.
The entries are yours to change. Delete node_modules from your published config and npm never runs; add an entry of your own (a bower_components, say) and it's provisioned the same way. An entry you keep still picks up any option a later version of the package adds to it.
Provisioning Steps
Before the steps run, the worktree provisions the dependencies above. Then it runs the commands in steps, which by default build assets and link storage:
'steps' => [ 'npm run build --if-present', 'php artisan storage:link', ],
The npm ci that installs node_modules lives in the dependencies block, not here, so copying can skip it. It's npm ci rather than npm install on purpose. Laravel's package.json ships without a name, so npm install writes the worktree's directory name into the tracked package-lock.json and it looks modified. npm ci installs straight from the lockfile and never rewrites it. If your project has no committed lockfile, switch it to npm install and add a name to your package.json.
Warp Terminal
If you use Warp, you can drive these commands from Tab Configs and turn them into one-click buttons. Each block below is one .toml file. Save it in Warp's tab configs directory, or paste it into the tab config editor. The title field names the tab, so it reads as feature/login rather than the command that ran.
Warp parameters are text fields or repo and branch pickers, with no dropdown to choose from, so a single config can't offer a menu of actions. Three buttons cover the flow instead: create, resume, finish.
Create a worktree and drop into it. Type a branch name, or leave it blank to auto-generate feature/auto-<timestamp>:
name = "Worktree Create" title = "{{branch}}" color = "green" [[panes]] id = "main" type = "terminal" directory = "{{repo}}" commands = [ '''P="$(php artisan worktree:setup {{branch}} --base={{base}} --print-path)" && cd "$P"''', ] [params.repo] type = "repo" description = "Repository" [params.base] type = "branch" description = "Base branch" default = "main" [params.branch] type = "text" description = "Branch name, or blank to auto-generate" default = ""
The branch field carries an empty default, and that's what lets you submit it blank. A parameter with no default at all is treated as required. The --print-path flag sends everything except the final worktree path to stderr, so $(...) captures just the path and drops you in, generated name and all. Leave the {{...}} substitutions unquoted: Warp quotes them for you, and wrapping them a second time turns the value into a literal quoted string.
Resume work in an existing worktree:
name = "Worktree Resume" title = "{{branch}}" color = "blue" [[panes]] id = "main" type = "terminal" directory = "{{repo}}" commands = [ '''cd "$(php artisan worktree:path {{branch}})"''', ] [params.repo] type = "repo" description = "Repository" [params.branch] type = "branch" description = "Worktree branch to resume"
Finish a worktree with the interactive teardown:
name = "Worktree Finish" title = "Worktree Finish" color = "yellow" [[panes]] id = "main" type = "terminal" directory = "{{repo}}" commands = [ '''php artisan worktree:teardown''', ] [params.repo] type = "repo" description = "Repository"
Create and resume read the worktree path from the package, through --print-path and worktree:path, so both tabs land in the right place even after you change path or the host template.
Resources
Visit the documentation site for searchable docs auto-updated from this repository.
- AI Integration: Use this package with AI coding assistants via Context7 and Laravel Boost
- Requirements: PHP, Laravel, and dependency versions
- Changelog: Release history with linked pull requests and diffs
- Contributing: Development setup, code quality, and PR guidelines
- Questions & Issues: Bug reports, feature requests, and help
- Security: Report vulnerabilities directly via email
License
The MIT License (MIT). Please see License File for more information.
