Quickstart — Branchery

Before you install#

The project must already run in DDEV and its root must be a git repository. Branchery uses the project's web and database containers, so start from a working project rather than from an empty DDEV configuration.

The Branchery API is intentionally unauthenticated. Keep its port on the developer's own machine behind DDEV's router; do not expose it on a shared or public network.

Install Branchery#

Run these commands in the project root:

bash

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

The management interface is now available at https://<project>.ddev.site:8041. Open it with:

bash

ddev branchery launch

The project checkout keeps answering at https://<project>.ddev.site.

Describe how the project is built#

Branchery does not infer an application's setup from its files. Choose the shipped profile that matches the project:

Profile	Use it for
`typo3-app`	a TYPO3 instance, or an extension that builds one
`typo3-core`	the TYPO3 core repository, served from its own root
`symfony`	a Symfony application
`composer`	a project that only needs `composer install`

Write the starting configuration, for example:

bash

ddev branchery config:example --profile=typo3-app --write

This creates .ddev/branchery.yaml. Commit it with the project so the team and every branch share the setup. Print the complete shipped profile before customizing it with:

bash

ddev branchery config:example --profile=typo3-app --full

The configuration reference explains how a project changes its docroot, setup commands, data source and carried files. Without this file a worktree is only a checkout at an address of its own, with an empty database.

Create the first worktree#

Use fork when the branch does not exist yet and should start from the current project checkout:

bash

ddev branchery worktree:fork feature/checkout

Use add when the branch already exists locally or on a remote:

bash

ddev branchery worktree:add 13.4

A fork may start from another worktree instead of the project checkout:

bash

ddev branchery worktree:fork follow-up --from=feature-checkout

Branchery makes the name safe for a hostname. A branch called feature/checkout is normally served at:

text

https://feature-checkout.<project>.ddev.site

The git branch keeps its original name. Use --name=<worktree> only when the directory, address and database need a different safe name.

Check the result#

List what Branchery created:

bash

ddev branchery worktree:list

The row names the address, branch, PHP version and database. It also shows whether the build finished and whether dependencies have changed since it was built. ddev describe carries the same addresses in its Branchery section.

Open the worktree URL and the Branchery interface. A finished operation has a step-by-step record on the worktree page; a stopped one includes the command that continues from a safe point. See Troubleshooting when the first build does not finish.

Continue from here#

The overview now has a row for the worktree. Working with worktrees says what that row tells you, how to keep the worktree current and how to remove it when its work has landed. Open the checkout in an editor next: Editors says what Branchery has written into it for the debugger and what each window has to leave out. When a build stops, Troubleshooting has the way on.

Configuration reference is the project's file, key by key, and Worktree operations every operation, step by step. Updating and uninstalling the add-on are on Update and uninstall.