Raised: $0
0% of monthly goal Help us cross the finish line!
Goal: $12,000
Raised: $0 Goal: $12,000
0% of monthly goal Help us cross the finish line!
Sponsor DDEV

If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.

add-on registry tests last commit release

DDEV Fire Worktrees

Overview

This add-on runs several branches of a Drupal site side by side. Each Git worktree gets its own DDEV project, database and URLs. Its database starts as a copy of your main checkout’s, then Drupal’s deploy steps run so the copy matches the branch. Your committed .ddev/config.yaml never changes.

A standard single-site Drupal project needs no settings. Multi-domain and multisite projects need a few. The add-on is part of the Fire family with ddev-fire, but neither add-on needs the other.

ddev fire-worktree-create ABC-123-hero   # new branch and checkout, its own site, a copy of your database
ddev fire-worktree-create --pr=123       # a pull request's branch, to review it in its own site
ddev fire-worktree-list                  # every worktree, its status and URL
ddev fire-worktree-info                  # in a worktree: its URLs, database source and a login link
ddev fire-worktree-refresh               # in a worktree: a new copy of your database
ddev fire-worktree-remove                # in a worktree: delete its site and checkout, keep the branch

Requirements

Installation

ddev add-on get fourkitchens/ddev-fire-worktrees
git add .ddev
git commit -m "Add ddev-fire-worktrees"

Commit the installed files, because a new worktree only has the commands its branch has. The commands run on your computer rather than in a container, so no ddev restart is needed.

Install only one worktree add-on per project. Other public add-ons also define ddev worktree-remove, which this add-on provides as an alias.

Usage

Command Alias What it does
ddev fire-worktree-create <branch> [start-point] worktree-create Checks out a new or existing branch in a directory beside your main checkout, such as ../mysite-abc-123-hero, then runs startup there. --pr=<number> checks out a pull request instead.
ddev fire-worktree-start worktree-start Gives the worktree you’re in its own DDEV project, copies the database into it, and builds it. Safe to rerun.
ddev fire-worktree-refresh [--yes]   Replaces the worktree’s database with a new copy, as its first start did, and builds it again. Keeps its DDEV project and other volumes, such as search indexes.
ddev fire-worktree-list   Lists every worktree with its branch, DDEV project, status, uncommitted changes and URL.
ddev fire-worktree-info [--json]   Shows the worktree’s DDEV project, status, URLs, and where and when its database was copied, and for a running Drupal site, a one-time login link. --json is for scripts and agents.
ddev fire-worktree-remove [--yes] [--keep-checkout] [path] worktree-remove Deletes the worktree’s DDEV project and database, then removes the checkout. Keeps the branch.
ddev fire-worktree-prune [--yes]   Finds DDEV projects whose checkout is gone, for example after a tool deletes a worktree. Deletes them with --yes.

Run create, list and prune from any checkout of the repository. Run start, refresh and info inside a worktree; start appends its output to the worktree’s .ddev/fire-worktree-start.log. Run remove inside a worktree, or pass its path. Every command accepts --help.

create checks out a branch you or origin already have, and starts a new one from WORKTREE_BASE_REF, else your remote’s default branch. It uses branches as they stand locally; add --fetch to fetch first. --pr=<number> checks out a pull request, and --base adds a worktree on its base branch to compare against. See Choosing the branch.

create and start copy your main checkout’s database by default. Pass --db=fresh for an empty database, --db=<file> for a snapshot or SQL dump, or --no-build to skip the build. A worktree’s database is copied once; when it falls behind, refresh replaces it with a new copy and takes the same options. See Choosing the database.

remove refuses the main checkout and a worktree with uncommitted or untracked files. remove and refresh ask before deleting anything; pass --yes when no one is at the terminal.

Documentation

Guide Read it to
Drupal projects Set up a standard site, a FIRE project, a multi-domain or multisite project, or search.
Configuration Change worktree names, copied files, the default database or the build command.
Choosing the branch Check out an existing branch or a pull request, fetch first, or compare a pull request with its base.
Choosing the database Copy, reuse or import a database, start empty, or get a new copy later.
Lando projects Use worktrees in a project that also has, or only has, a .lando.yml.
Agent tools Start and delete worktree environments from any agent tool, find out why a start failed, and clean up after them.
Migrating from project-local commands Replace a project’s own worktree-* commands and keep existing worktrees.
How it works See what startup does and how names, hostnames, locks and prune work.
Troubleshooting Fix common errors and warnings.
Contributing Run the tests, try changes in a project, and release.
Workflow Take an idea or a bug report to a merged pull request with the agent skills.

Removal

ddev add-on remove fire-worktrees

This removes the commands but not the worktrees’ DDEV projects. Run ddev fire-worktree-remove in each worktree first, or delete projects afterwards with ddev delete <name>.

Credits

Contributed and maintained by Four Kitchens, started by @mcortes19

If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.