Refs
A ref is what you want to materialize. It is the second positional argument of a workspace command:
uxd <project> <ref> [verb]
Resolution order
uxd tries these forms in order. First match wins.
| Input | Meaning | Example |
|---|---|---|
<n> or #<n> | Pull request | uxd my-project 42 · uxd my-project '#42' |
pr/<n> | Pull request (case-insensitive) | uxd my-project pr/42 |
Starts with /, ./, ../, or ~ | Adopt an existing working tree | uxd my-project ~/code/checkout shell |
| 40-char hex | Commit SHA — detached worktree | uxd my-project 1a2b3c… |
- | The last-used ref for this project | uxd my-project - shell |
| Anything else valid as a branch | Branch name | uxd my-project feat/login code |
uxd refuses to guess. Pass the full 40 characters, or force the
interpretation with a flag.Forcing an interpretation
Three global flags bypass the table above entirely:
uxd my-project --pr 42 code # treat 42 as a PR
uxd my-project --branch 42 code # treat 42 as a branch literally named "42"
uxd my-project --path ./here shell # adopt ./here
Reach for these when a branch name collides with another form — a branch called
42, or one whose name is 40 hex characters.
URL form
Pass a clone or web URL in place of the project name. uxd matches it against
the project whose repo has the same host, owner, and repository — ssh and
https forms are equivalent, and a trailing .git is optional.
A /pull/<n> or /tree/<branch> segment in the URL is consumed as the ref:
uxd https://github.com/my-org/my-project/pull/42 code
uxd https://github.com/my-org/my-project/tree/feat/login diff
uxd git@github.com:my-org/my-project.git 42 code # ref given separately
This is the "paste the link from Slack" path — no need to remember which project name you gave the repository.
Adopting an existing checkout
A path ref does not create a worktree. uxd adopts the working tree that is
already there, wrapping it with the same environment, ports, and commands as a
managed workspace:
uxd my-project ~/code/my-project-hotfix shell
Adopted workspaces are excluded from clean filters unless you pass
--include-adopted, because uxd did not create them and should not assume it
may delete them.
The last-used ref
- resolves to the last ref you materialized for that project. It is the
shortcut for "the thing I was just looking at":
uxd my-project - shell
uxd my-project - run dev
The last ref is recorded in uxd's
state directory.
If a project has no history, uxd exits with E_RESOLVE.
When resolution fails
Resolution errors exit with code 4 (E_RESOLVE) and name the problem:
uxd my-project no/such/branch checkout
→ fetching origin/no/such/branch
error(E_RESOLVE): branch 'no/such/branch' does not exist on origin
hint: check the name, or push the ref first
See Exit codes for the full list.