---
title: "Every branch, ready beside the project"
description: "Run several branches at once, each with its own URL, PHP runtime and database, while the project checkout keeps running."
canonical: index.html
navigation-title: "Branchery"
---

<a id="every-branch-ready-beside-the-project"></a>

# Every branch, ready beside the project

Run several branches at once, each with its own URL, PHP runtime and
database, while the project checkout keeps running.

![](images/branchery-hero.svg)

## Quick start

Pull Branchery into an existing DDEV project and restart it.

```bash
ddev add-on get benjaminkott/ddev-branchery
ddev restart
```

> [!WARNING]
> **Branchery is a pre-release.** The interface, the API and the shipped
> profiles can still change from one version to the next. What a project
> writes in `.ddev/branchery.yaml` is the part already held steady — that
> grammar is added to, never renamed or narrowed. A worktree is a checkout
> beside the project, so keep anything you would miss on a remote.

## What a worktree is

A worktree is a branch checked out beside the project instead of over it.
Branchery gives that checkout everything it needs to run in a browser.

**An address of its own**

`feature/checkout` is served at its own DDEV URL while the
project checkout keeps answering at its existing address.

**A database of its own**

Start empty, copy the project's data, or restore a dump without
touching the database beside it.

**A PHP version of its own**

Assign the runtime the branch needs. Different PHP versions remain
available at the same time.

**A record of how it was built**

Every operation records its steps. If it stops, the record says
where and names the safe command to continue.

## From a branch to a worktree

You name a branch, and what stands there afterwards is a worktree of it.
The interface and `ddev branchery worktree:add` build the same one.

1. **The branch is checked out beside the project**
   `.worktrees/feature-checkout`, cut from the branch. The
   project checkout is not moved and stays on the branch
   it was on.
2. **The worktree gets an address and a runtime**
   It answers without a DDEV restart, with the PHP version the
   branch asks for — a pool of its own where that differs
   from the project's.
3. **The project's own build runs inside it**
   `composer install`, `npm ci`, whatever
   `.ddev/branchery.yaml` names — in the project's web
   container, so a worktree is built by the same toolchain
   that serves it.
4. **It is given a database, and a way to reach it**
   Empty, or the project's data copied in and the schema
   fitted to the code that is checked out. The connection and
   the address are written into the checkout, and
   `database:sync` refills it whenever you ask.
5. **What was done to it stays on record**
   Every step, what it printed and where it stopped — on the
   worktree's page and in the shell, whichever end started the
   work.

```bash
ddev branchery worktree:add feature/checkout
```

What stands there afterwards

```text
https://feature-checkout.blog.ddev.site
.worktrees/feature-checkout
branchery_feature_checkout
```

## Nothing about a project is guessed

An operation creates a checkout, an address, a PHP version and an
empty database. Everything beyond that is written in the project's
own `.ddev/branchery.yaml` or does not happen.

Shipped profiles cover TYPO3 applications, TYPO3 Core, Symfony and
Composer-only projects. A project can amend every profile through
the same public configuration grammar.

Which steps are Branchery's own and which stand in that file is
drawn step by step in [Worktree operations](reference/operations.md).

.ddev/branchery.yaml

```yaml
profile: typo3-app
php: "8.3"
docroot: web
```

## Two ends, one record

The web interface and the command line perform the same operations
and leave the same history. A command run as `ddev branchery ...`
adopts a job of its own, so the page shows it while it runs and the
worktree's history has it afterwards.

```bash
ddev branchery worktree:list
ddev branchery worktree:add 13.4
ddev branchery launch
```

![](images/branchery-record.svg)

## The manual

**[Getting started](getting-started.md)**

From installing the add-on to the first usable worktree.

**[Guides](use-branchery.md)**

Operate a worktree, manage its data, work in an editor and recover
safely when something stops.

**[Reference](reference.md)**

Configure a project and drive Branchery from scripts or through
its API.

**[How Branchery works](architecture.md)**

See where the checkout and state live, what a worktree costs on
disk, and which boundaries keep operations safe.