Working the Nexa way

Nexa expects one folder on your machine to hold everything you are actively working on. That folder is your Development Root, and the directories inside it are your working contexts. This page is the shape of that arrangement and why it is worth adopting; the pages either side of it cover the individual commands.

The shape of a working day

A Development Root is an ordinary directory that you have marked with nexa root. Marking it creates a single .nexa/ directory at the top, and after that every piece of work you bring in becomes a plain subdirectory beside the others:

~/Development

~/Development/
    .nexa/

    RinkoHub/
    RinokaArena/
    NexajiManager/
    RinkoHub-auth/

Four directories, four things being worked on, all visible at once. There is no wrapper around each one and no per-project setup to repeat — they are just folders, editable with any editor and listable with ls.

Each of those directories is a working context: one repository, one branch, and one workspace, materialized as a directory with its own working files. Those three things together are what a context is, and naming them is how you ask for one.

Two contexts, one repository

Because a context is a repository and a branch and a workspace, the same repository can be open more than once. The last two lines of the listing above resolve like this:

What those directories are

RinkoHub/        repository: RinkoHub   branch: main          workspace: main
RinkoHub-auth/   repository: RinkoHub   branch: development   workspace: auth-agent

RinkoHub/ and RinkoHub-auth/ are the same repository open in two contexts: main, and the auth-agent workspace of the development branch. That is enough to make them fully independent on disk: each has its own working files, so editing one changes nothing in the other. Both sit side by side in the listing, and you move between them by changing directory.

You do not need to know how this works

Nexa stores objects once and materializes each context from them, which is why a second context of the same repository is cheap. You never have to think about that to use it. The directory listing above is the whole model you need.

What this buys you

The practical differences show up in ordinary moments during a working day.

Nothing to open first. Every active project is already a directory under one root, so switching from one to another is cd ../RinokaArena rather than locating and opening an isolated project folder.
Several projects at once. The four directories above can be four unrelated repositories. Searching across them, copying a file between them, or pointing one editor window at the lot of them all work because they are ordinary neighbouring folders.
Several branches or attempts at once. A long-running piece of work and an urgent fix can each have a directory. Neither has to be stashed or put down for the other, because neither is sharing working files with the other.
Temporary contexts are genuinely temporary. Bring one in to review something or try an approach, then remove it with nexa drop when you are finished. The repository and its history are untouched.
A person and an AI tool can work at the same time. Give each its own context on the same branch, as with RinkoHub/ and RinkoHub-auth/ above, and they never write over each other's files.

Bringing work in

nexa get brings a repository into the root as a working context. Given only a target, it takes the repository's default branch and workspace and names the directory after the repository:

Command

$ nexa get ../src/RinkoHub

Expected output

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

To open the same repository a second time, name the context you want as branch/workspace and give the new directory a name with --as. Without --as the command would want the repository's own name, which is already taken:

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

That is the whole of the arrangement shown at the top of this page: run nexa get once per thing you want open. A hosted repository is the same command with an owner/repository target instead of a path, once this machine is authorized with nexa login. Several contexts at once covers listing, orienting and removing them.

Work that starts on this machine takes the other route in, still from the root: nexa init my-project; then protect its private files in the root's .nexapolicy and run nexa my-project policy validate; then nexa record -p my-project, and nexa publish -p my-project once to create the hosted repository and put the recorded version on it. Your first repository, Protect private files before hosting and Host it on Rinko Hub walk through it.

Recording and syncing

Edit a context's files like any other directory's. When you want to keep a state of it, record a version from the root, naming the context with -p — there is no staging step, so recording captures the working tree as it stands unless you name specific paths:

Command

$ nexa record -p RinkoHub -m "Add the feature note"

Expected output

Created version 08692fb77a20
  workspace: main
  files:     1

Selected on branch main.

Recording is local and per-context. The context next door is a different workspace with its own working files, so it is unaffected, and its own recording is a separate act.

When you want your work and Rinko Hub's to meet, nexa sync on a hosted context exchanges both directions at once. No remote is named, because the context already knows which repository it belongs to:

Command

$ nexa sync -p RinkoHub

Expected output

Synchronized with Rinko Hub.

Syncing is per context, not per root

Each context syncs the repository it belongs to. A root holding four repositories does not have one combined sync; you sync the context whose work you want exchanged, by naming it.

That is the loop, run from the root: nexa get what you need — or nexa init and nexa publish what you start — work, nexa record -p what is worth keeping, and nexa sync -p when it should reach Rinko Hub. Everything else on this page is a consequence of those four directories sitting side by side.

If you would rather stand inside one context and run the same commands without -p, cd RinkoHub and do exactly that — the directory names the context. Working inside a project directory covers that style.