Several contexts at once

A working context is one repository, one branch and one workspace, materialized as a directory in your Development Root. You can have as many open as you have use for. This page is the operational detail: Working the Nexa way is the reason to.

Why several contexts

One context per thing you are actually doing. The common cases are an urgent fix alongside unfinished work, a review of someone else's branch while your own stays open, two approaches to the same problem kept side by side, and a person and an AI tool working the same branch without sharing files.

What makes this workable is that contexts do not share working files. Two contexts of the same repository on the same branch still have separate directories on disk, so editing src/auth.ts in one leaves the other's copy exactly as it was. Nothing is stashed, nothing is switched, and neither context has to be put down for the other to proceed.

Isolation is about working files

Separate working files are what keeps contexts from interfering. They still belong to the same repository and the same history, so a version recorded in one becomes visible to the other in the ordinary way — by reaching the repository, not by appearing in its directory.

Creating them

nexa get takes a target and, optionally, the context to open as branch/workspace. Omit the context and you get the repository's default; name only a branch and you get that branch's like-named workspace.

Command

$ nexa get ../src/RinkoHub

Expected output

Ready: RinkoHub
  repository: ../src/RinkoHub
  branch:     main
  workspace:  main
  path:       ~/Development/RinkoHub

The directory is named after the repository unless you say otherwise. Opening the same repository again therefore needs --as to give the second directory its own name:

Command

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

Expected output

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

If the workspace you name does not exist yet, create it first with nexa workspace create <NAME> --branch <BRANCH>, then open a context on it.

Moving between them

Listing what is open

nexa contexts, run anywhere under the root, prints a tab-separated table of every context in it:

Command

$ nexa contexts

Expected output

LOCAL	REPOSITORY	BRANCH	WORKSPACE
RinkoHub	local:~/src/RinkoHub	main	main
RinkoHub-auth	local:~/src/RinkoHub	development	auth-agent

The two rows share a repository and differ in branch and workspace — the arrangement from the previous section, seen from the root. For tooling, the same listing is available as JSON:

Command

$ nexa --format json contexts

Expected output

[{ "local_path": "capture-demo", "repository": "rh_repo_…", "branch": "main", "workspace": "main" }]

Knowing where you are

Directories named after branches and workspaces start to look alike. nexa where answers the question directly:

Command

$ nexa where

Expected output

path:       ~/Development/RinkoHub
root:       ~/Development
context:    RinkoHub
repository: local:~/src/RinkoHub
branch:     main
workspace:  main

Run it from inside a subdirectory of a context and an extra within: line shows how deep you are. Run it at the Development Root itself and it prints the short form instead:

At the root

path: ~/Development
root: ~/Development

Removing one

When a context has served its purpose, nexa drop removes it from the Development Root:

Command

$ nexa drop RinkoHub-auth

Expected output

Removed RinkoHub-auth from this Development Root.
The repository, its history and its workspaces were not touched.

nexa drop is local only. It removes one directory from your machine. The repository, every version recorded in it, the workspace the context was opened on, and every other context stay exactly as they were — including contexts on the same repository. Dropping RinkoHub-auth leaves RinkoHub untouched.

Because removal deletes working files, it refuses when those files hold work that was never recorded, and names both ways forward:

Command

$ nexa drop RinkoHub-auth

Refused

error: cannot do that here: this working context has unrecorded changes; record them with `nexa record`, or discard them with `nexa drop --force`

--force discards, it does not save

nexa drop --force removes the context along with the unrecorded changes in it. They were never recorded in any version, so there is nothing to recover them from. Record first if there is any doubt.