If you find this add-on useful, please star it on GitHub — stars show appreciation and help maintainers know their work matters.
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
.ddev/config.yaml committed.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.
| 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.
| 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. |
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>.
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.