Laravel Worktree

Work on a feature branch without touching your main checkout. One command turns a branch into a git worktree that has its own Laravel Herd site, its own application and test databases, and a rewritten .env. A second command finishes the branch, whether that means opening a pull request, merging it, or throwing it away, and then drops the databases and removes the worktree. No leftover databases, no stale .test sites, no shared state between branches.

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
• Finishing a Worktree
• Finding a Worktree
• Configuration
  • Herd Modes
  • Databases
  • Test Databases
  • Host Rewriting
• 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

Publish the config file if you want to change the defaults:

php artisan vendor:publish --tag=worktree-config

That's it. All three Artisan commands are 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:

1. Creates the worktree next to your project (or wherever you configure).
2. Serves it through Herd, so blog on branch feature/login becomes blog-feature-login.test.
3. Copies your .env, then rewrites the database name and every reference to the old host.
4. Creates a fresh application database and a separate test database, and writes the test database name into phpunit.xml.
5. Runs composer install, migrates the new database, then runs your own extra steps (npm, 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.

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               |
+---------------+------------------------------------------+

A few options change what runs:

If the branch already exists, its worktree is checked out as-is instead of branching from scratch.

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. You can skip the questions with flags:

# 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, unsecure the Herd site, remove the worktree, and delete the branch (except after a pull request, where the branch stays for the open PR). The databases to drop are worked out from the worktree's own name rather than the copied .env, and teardown refuses outright to drop one matching your main repository's DB_DATABASE. Pass --keep-database if you want them left alone.

Finding a Worktree

worktree:path prints where a branch's worktree lives. It creates nothing and touches nothing:

php artisan worktree:path feature/login
# /Users/you/Sites/blog-feature-login

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.

Herd Modes

The herd option decides how the site is served:

'herd' => env('WORKTREE_HERD', 'secure'),

• secure serves the worktree over HTTPS with herd secure and sets APP_URL to https://.
• link serves it over HTTP with herd link, which suits a Vite dev server.
• none skips Herd, for when you serve the site some other way.

Databases

What happens here depends on the kind of database you use, 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), plus a test database with the _testing suffix. The name is lowercased, with anything that isn't a letter or number turned into an underscore, so it stays valid everywhere. Postgres works too: databases are created against the postgres maintenance connection and dropped WITH (FORCE). Teardown drops both.

SQLite 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. The one case it does step in is a DB_DATABASE holding an absolute path back into the main checkout, which gets repointed at the worktree so the two don't share a file. A database somewhere else entirely is left shared, with a warning, since that's usually deliberate.

The database.migrate option controls what happens after creation:

'database' => [
    'migrate' => env('WORKTREE_MIGRATE', 'fresh'),
],

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.

Test Databases

If your suite runs against a real database server, the worktree gets a second one 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"/>

The package reads phpunit.xml to work out which connection your tests use, and only steps in when that connection is a server. 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. Point your suite at MySQL or Postgres and it starts happening on its own, no configuration needed.

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.

Set the suffix with WORKTREE_TEST_SUFFIX if -testing suits your naming better than _testing, or turn the whole thing off with database.test.enabled.

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.

Warp Terminal

If you use Warp, you can wrap these commands in tab configs and get a one-click worktree button with pickers for the repo and branch. Save each block as a .toml file in Warp's tab configs directory, or paste it into Warp's tab config editor.

Create a worktree (drops you into it):

name = "Worktree"
color = "green"

[[panes]]
id = "main"
type = "terminal"
directory = "{{repo}}"
commands = [
  '''B="{{branch}}"; php artisan worktree:setup "$B" --base="{{base}}" && [ -n "$B" ] && cd "$(php artisan worktree:path "$B")"''',
]

[params.repo]
type = "repo"

[params.base]
type = "branch"
default = "main"

[params.branch]
type = "text"
description = "Branch name (leave blank to auto-generate)"

Open an existing worktree:

name = "Worktree Open"
color = "blue"

[[panes]]
id = "main"
type = "terminal"
directory = "{{repo}}"
commands = [
  '''cd "$(php artisan worktree:path "{{branch}}")"''',
]

[params.repo]
type = "repo"

[params.branch]
type = "branch"
description = "Which worktree branch to open?"

Finish a worktree (runs the interactive teardown):

name = "Worktree Finish"
color = "yellow"

[[panes]]
id = "main"
type = "terminal"
directory = "{{repo}}"
commands = [
  '''php artisan worktree:teardown''',
]

[params.repo]
type = "repo"

Each tab leans on worktree:path for the cd, which is why they keep working after a config change.

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 the LICENSE file for more information.