The Development Root model

The two previous pages describe what is stored and how it is organised. This one describes where it lands on your disk — and the answer is simpler than the equivalent in most version-control tools, because there is exactly one place for it.

The model on disk

A Development Root is the single folder that holds all your active work. You declare it once, with nexa root, and it reports the directory it has adopted. Everything you subsequently bring in lands beneath it.

The structure it produces is deliberately unremarkable. One root, one .nexa/ directory at that root, and an ordinary directory for each piece of work:

A Development Root holding two working contexts

~/Development/
├── .nexa/              the root's own bookkeeping — the only one
├── RinkoHub/           a working context: ordinary files, ordinary directory
│   └── readme.md
└── RinkoHub-auth/      another context, same repository, different workspace
    └── readme.md

One .nexa, at the root only

A working context has no .nexa/ of its own. Open one and you find your files and nothing else — no metadata directory, no per-directory state to avoid disturbing. The root keeps the bookkeeping for every context beneath it in one place, which is why moving between contexts is just changing directory. That bookkeeping is control state for many independent repositories: the root is not itself a repository, and its contexts share no history.

nexa root does not move, copy or reorganise anything you already have. It records that this directory is the root and creates the .nexa/ directory holding that record.

What a working context is

A working context is one repository, one branch and one workspace, materialised as a directory beneath the root. It is the unit you actually work in.

Two commands create one, both run at the root. nexa init my-project makes that one directory a managed repository — its siblings stay unmanaged, and the directory gets no .nexa/ of its own. nexa get brings in a repository that already exists. Given a repository, it reports exactly which context it materialised and where it put it:

Command

$ nexa get ../src/RinkoHub --as RinkoHub

Expected output

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

All four facts in that report matter, because a context is defined by them: which repository, which branch, which workspace, and which directory. A context knows its own answer to each, which is why nexa record and nexa sync never need to be told.

You do not choose where a context lands the way you choose where to put a clone. It lands under the root, named after the repository — or after whatever you pass to --as.

Many repositories, one root

One root holds as many contexts as you like, across as many repositories as you like. nexa contexts, run at the root, lists them:

Command

$ nexa contexts

Expected output

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

Those two rows are the same repository, twice, at different branches and workspaces. That is an ordinary thing to do rather than an advanced trick: one context for the work you are shipping and another for an experiment, both open, neither disturbing the other.

Why several contexts of one repository are cheap

Contexts of the same repository share its stored objects rather than duplicating them. A second context of a large repository costs roughly the files you can see in it, not a second copy of its entire history. This is mentioned only so the cost does not surprise you — there is nothing here to configure, and nothing to manage.

Removing a context is nexa drop, and it is a local operation only. The output says precisely what survives:

Command

$ nexa drop RinkoHub-auth

Expected output

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

Dropping a context removes a directory from your root. The repository, every version in it, and every other context of it are unaffected — consistent with the rule from the repositories and versions page that nothing destroys a recorded version.

For how to use this day to day, see Working the Nexa way; for several contexts in particular, Several contexts at once.