---
title: "Working with worktrees"
description: "The overview is the page Branchery opens on, and ddev branchery worktree:list prints the same list."
canonical: worktrees.html
navigation-title: "Worktrees"
---

<a id="worktrees"></a>

- [What a row says](#what-a-row-says)
- [Create one](#create-one)
- [Keep one current](#keep-one-current)
- [Try a patch and come back](#try-a-patch-and-come-back)
- [Build one again](#build-one-again)
- [Remove what is finished](#remove-what-is-finished)

<a id="working-with-worktrees"></a>

# Working with worktrees

The overview is the page Branchery opens on, and
`ddev branchery worktree:list` prints the same list. Each row is one
worktree: its name, the branch it is on and the commit that branch stands on,
what is outstanding in it, its PHP version, and the way into its own page. Over
the rows stands the project checkout with the same facts, and under them every
branch that has no worktree yet.

<a id="worktrees-marks"></a>

<a id="what-a-row-says"></a>

## What a row says

A row carries a mark only where something about the worktree is remarkable.

| Mark | What it means, and what to do |
| --- | --- |
| *not built* | the worktree has not been built yet; provision it |
| *build unfinished* | a build stopped before its end; provision it again |
| *dependencies changed* | what the build reads has changed since it was built; provision it again |
| *merged* | every commit is in the project's branch; the worktree can go |
| *branch gone* | the remote has deleted the branch; the worktree can probably go |

The column beside the branch counts what is not settled: changes never
committed, commits never pushed, and how far the branch is behind its remote. A
quiet row says nothing there.

Over the list, a note names the worktrees whose build did not finish, and
another the ones that look finished, with a press that removes them together.
[Remove what is finished](#worktrees-remove) says what that press does.

<a id="worktrees-create"></a>

<a id="create-one"></a>

## Create one

*New worktree* opens a dialog for any branch, and the branches without a
worktree offer the same press one by one. The dialog asks what the worktree is
called, which version it runs on and where its data comes from, and says
before the press what the operation would stop on. `n` opens it from the
keyboard, and `/` puts the cursor in the filter.

From a shell:

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

[add](../reference/build.md#operations-add) checks out a branch that exists, [fork](../reference/build.md#operations-fork) cuts one that does not; both are there step by step.

<a id="worktrees-current"></a>

<a id="keep-one-current"></a>

## Keep one current

*Fetch* at the top of the page asks the remote what moved, and the counts in
the list follow. A worktree that is behind is brought up with *Bring up to
date* on its page:

```bash
ddev branchery worktree:pull my-fix
```

Only a fast-forward: nothing the worktree has committed is touched. A branch
with commits of its own that is also behind is refused, and there are two ways
on: rebase in git, or drop the commits with *Discard what is not pushed*, which
shows every commit that would go before it asks.

The dependencies and the database are not part of this. Where the code now
asks for something else, the row says *dependencies changed*, and
[Build one again](#worktrees-rebuild) is the answer.

<a id="worktrees-patch"></a>

<a id="try-a-patch-and-come-back"></a>

## Try a patch and come back

A worktree is where a patch is looked at: `git-review -d` or a fetched ref
checks another branch out into it. Its page then says which branch it was made
for, and *Back to* that branch puts it there again and brings it up to date:

```bash
ddev branchery worktree:restore my-fix
```

The branch being left keeps everything committed on it. Uncommitted work is
refused rather than carried across.

<a id="worktrees-rebuild"></a>

<a id="build-one-again"></a>

## Build one again

*Provision again* rebuilds dependencies, configuration, docroot and PHP
version. The data is the choice the dialog asks: keep it and fit it to the
code that is checked out now, or install anew into an empty database.

```bash
ddev branchery worktree:provision my-fix
ddev branchery worktree:provision my-fix --fresh
```

*Copy data* takes the project checkout's data again instead of rebuilding;
[Databases and data](databases.md) is the page for that. *Change* switches the PHP version alone.

<a id="worktrees-remove"></a>

<a id="remove-what-is-finished"></a>

## Remove what is finished

*Remove* on a worktree's page takes its database, its checkout and its branch,
and says beforehand what is uncommitted or unpushed in it.

```bash
ddev branchery worktree:remove my-fix
```

*Tidy up* over the list offers every worktree that looks finished, together.
Merged ones are ticked, because nothing can be lost. Ones whose branch is gone
from the remote are offered unticked, because their commits may be nowhere
else. A worktree with uncommitted changes is not offered at all.