Worktrees

Use worktrees when one branch is reproducing an incident and another is active development.

Branch isolation with its own runtime state is the natural unit for a "one issue, one PR" loop — a sandbox per task, for a developer or for an agent. See Why ldev Exists for the broader argument.

Create an isolated environment

ldev worktree setup --name incident-123 --with-env
cd .worktrees/incident-123
ldev start

Inspect registered worktrees without guessing from port scans:

ldev worktree list
ldev worktree status incident-123

list and status report the configured ports, Compose project name, portal URL and whether Docker currently has running containers for that worktree's com.docker.compose.project label.

If you already created a linked git worktree manually outside .worktrees/, run ldev worktree setup from inside that checkout to wire its local environment in place:

git -C ..\labweb worktree add ..\labweb.worktrees\testworktree -b feat/testworktree HEAD
cd ..\labweb.worktrees\testworktree
ldev worktree setup --with-env

When you run ldev worktree setup --name <name> from the main checkout, ldev still prefers .worktrees/<name> when it exists. Otherwise it can reuse a registered external worktree whose checkout folder is also named <name>.

If the main environment is still running and your platform cannot clone state hot, you can opt into a temporary handoff instead of doing the stop/start sequence manually:

ldev worktree setup --name incident-123 --with-env --stop-main-for-clone
ldev worktree setup --name incident-123 --with-env --stop-main-for-clone --restart-main-after-clone

Why use it

• keep production-repro work separate from feature work
• compare fixes across branches
• avoid mixing runtime state between unrelated tasks

Runtime Note

Worktrees inherit the files that exist in the branch or commit used as their base.

If your project uses runtime storage overrides such as:

• docker-compose.postgres.volume.yml
• docker-compose.liferay.volume.yml
• docker-compose.elasticsearch.volume.yml

make sure those files already exist in the branch history before you create the worktree. A local copy in the main checkout is not enough if it has not been committed into the branch the worktree uses.

If you are inside a worktree and still need read-only discovery against the main runtime, target it explicitly instead of changing directories:

ldev --repo-root ../.. portal inventory page --url /web/guest/home --json
ldev --repo-root ../.. resource structure --site /global --structure BASIC --json

Clean up

ldev worktree clean incident-123 --force

Use this workflow only when isolation matters. Most day-to-day work does not need it.