← Files UnityARCHIVED FILE

skills/using-unity/references/unity-cli/references/worktrees.md

1.88 KB · Nov 20, 2026 · 18:10 UTC

↓ Download file

See the change to this file →

# One Editor per worktree — unity-cli reference

Working in several worktrees or agent sessions: use one Editor per worktree. Make each worktree with `unity vcs git worktree add <branch> --output-dir <path>`, so you choose where it lands. `--output-dir` is optional: `--format json` reports the real worktree and project paths, and only the human output masks the account name in a home-directory path. The Unity project is `<path>` when it sits at the repository root, and `<path>/<its folder>` when it doesn't. Open that project's own Editor with `unity open <project>`. Then pin every call that reaches the Editor to that project: pass `--project-path <full project path>`, or prefix the call with the variable, as in `UNITY_PROJECT_PATH=<full project path> unity command editor status`. Most agent tools run each command in a fresh shell, so an `export` or a bare assignment in one call never reaches the next one. Every command that takes `--project-path` reads the variable when you pass no path, and so does `unity open`. Only `close`, `projects unlink cloud`, `mcp configure` and `ci init` don't read it: pass the path to those. Without the variable, a bare `unity open` opens the project of the current directory, which is still your source checkout. Target that Editor by the same full path every time, including `unity status --until-ready --project-path <project>`. A path that exists matches only that project, while a bare name also matches a sibling whose path contains it. Never drive an Editor whose project is not your own checkout (or one of its Multiplayer Play Mode clones). An Editor open on a sibling worktree answers every command just like yours. A command sent there edits that checkout's scenes, and its Play mode, recompiles and imports run against that checkout's code. If your own Editor isn't open, open it. If it has gone away, tell the user rather than borrowing the one that is running.

SHA-256: df100b132e0453cc195d2d50fc7176a0acec61dfe5efd6ed4dc2fe11a93afc53