Working with workspaces

A workspace is a development context inside a branch, in which several competing versions of the same work can exist at once. One workspace per problem; one version per attempt at it.

This guide assumes you have a working context on disk — a repository materialized under your Development Root — and that you have recorded at least one version in it. If not, start with your first repository.

Create a workspace

Create a workspace when you start a distinct piece of work inside a branch. It gets its own selected version and its own candidate set, so recording in it cannot disturb the branch's other workspaces.

$ nexa workspace create auth-agent --branch development

Created workspace `auth-agent` in branch `development`

--branch names the top-level branch that will contain the workspace. Omit it and the workspace is created in the branch you are currently working in.

Creating a workspace is a repository-level act: it makes the workspace exist, but it does not put a directory on your disk. To work in one, bring it into your Development Root as its own working context, naming it as branch/workspace:

$ nexa get ../src/RinkoHub development/auth-agent --as RinkoHub-auth

Ready: RinkoHub-auth
  repository: ../src/RinkoHub
  branch:     development
  workspace:  auth-agent
  path:       ~/Development/RinkoHub-auth

You now have two directories side by side, on the same repository, in different workspaces. Neither can change the other's selected version. nexa workspace list shows every workspace in the repository, and nexa where tells you which one the directory you are standing in belongs to.

Derive from another

Deriving takes the version currently selected in one workspace and makes it the starting point of a new, independent sibling. The base is immutable: later work in the source workspace does not flow into the derived one, and vice versa.

$ nexa workspace derive --from auth-agent auth-agent-retry

--from is the existing workspace whose selection becomes the base, and the positional argument names the new sibling. The new workspace records where it came from, so the relationship stays legible afterwards rather than being reconstructed from timestamps.

Derive rather than create when:

• You want a second attempt that starts from work already done, not from the branch's state.
• You are handing a starting point to someone else — or to an AI tool — and want the origin recorded.
• You want to try something you may well throw away, without putting the current workspace's selected version at risk.

Select between candidates

A candidate is a version offered as a possible answer. The selected version is the one the workspace currently points at — its accepted state. Every other candidate remains recorded, addressable and restorable.

Record without selecting

By default, recording a version also selects it. --candidate records without selecting, which is what makes several parallel attempts possible:

$ nexa record -m "Try the cache-first approach" --candidate

To build genuinely competing attempts, each must start from the same place. --parent bases a version on a specific parent rather than on whatever is currently selected:

$ nexa record -m "Try the queue approach" --candidate --parent 996e6d0bb3b1

Two people — or a person and an AI tool — can each record from that same parent. The result is two candidates from one base, neither overwriting the other, with the choice deferred until both exist.

Look at what you have, then choose

Both version list and version select accept --workspace to act on a workspace other than the one you are standing in.

$ nexa version select 08692fb77a20

The previously selected version becomes a candidate again. You can select it back at any time; selection is a mutable reference, and changing it alters nothing about the versions themselves.

When two peers have both recorded, syncing takes the union of candidates rather than rejecting one side. Divergence adds a candidate; it does not produce a rejection or a silent overwrite. If a sync leaves a workspace with no selected version, choose one with nexa version select.

On Rinko Hub, a synced version waits to be accepted

The short id nexa version list prints is all any of these commands need; you never have to copy a full identifier. nexa version --help lists the whole workflow in one place.

nexa version select changes the copy you are working in. A repository on Rinko Hub keeps its own accepted version, and nexa sync does not replace it: after the first publication, a newer version arrives as a candidate and the repository goes on showing the accepted one. nexa sync says so when it happens.

To see or switch versions on the website, open the repository's Code page and expand Versions. Every version is listed with its message, author and time, and marked Accepted, Candidate, Newest or Viewing; View files shows any of them. Someone who may accept changes to the repository — its owner, an admin or a maintainer — also sees Accept this version on a candidate that builds on the accepted one. Accepting keeps the earlier version.