Working inside a project directory

The default way to work is from your Development Root, naming each project with -p — that is what Your first repository teaches. This page is the other style, the one Git users already know: change into the project directory and run the commands there. The directory you are standing in names the project, so -p is never needed.

Nothing about the repository differs between the two. They are two ways of addressing the same project, and you can use either at any moment.

When this style fits

You spend a long session in one project. An editor terminal already open in the project directory, or a shell you keep there, saves typing -p on every command.
Tools run from the project directory. Build scripts, editor integrations and other programs that start in a project's folder can call nexa with no project name.
There is no Development Root. A folder somewhere on its own can be a standalone repository, managed entirely from inside itself.

Inside a Development Root

The first publication, run from inside the project:

First publication, from the project directory

cd ~/Development/my-project
nexa init
# protect private files in ~/Development/.nexapolicy, then
nexa policy validate
nexa record -m "Initial version"
nexa publish

nexa init with no argument manages the directory you are in. Inside a root it does exactly what nexa init my-project does from the root — the root records the project, and the project gets no .nexa/ of its own:

Command

$ nexa init

Expected output

Initialised Nexa repository `my-project` in Development Root ~/Development
Created workspace `main`

nexa record, nexa publish, nexa sync, nexa status and nexa history all default to the project you are standing in, so each runs with no project named. Output and behaviour are the same as on Your first repository.

A standalone repository, without a root

Outside any Development Root, nexa init creates a standalone repository in the directory, with its own .nexa/ alongside your files:

Command

$ nexa init

Expected output

Initialised empty Nexa repository in .
Created workspace `main`

From then on it works exactly like a project inside a root: protect its private files, then nexa record, then nexa publish to create it on Rinko Hub, then nexa sync. Only the bookkeeping location differs — including the policy: a standalone repository keeps its own .nexapolicy beside .nexa/, with its label rules in global, which there means this repository. Protect private files before hosting applies unchanged otherwise. A standalone repository is also the natural shape for working local-first.

Bringing a standalone repository into a root

Because its control state lives in its own .nexa/, a standalone repository is not listed by nexa contexts and cannot be named with -p from a root. To join your other projects, move its folder under your Development Root and, from the root, run nexa migrate my-project. That moves its state into the root — history, versions and hosted binding included — and renames the old .nexa/ to a backup rather than deleting it. nexa migrate my-project --dry-run shows what would move first.

The everyday loop

After first publication, every change is the same two commands, from inside the project:

Every change after the first

cd ~/Development/my-project
# edit files
nexa record -m "Describe the change"
nexa sync

nexa sync needs no remote, URL or branch name here either: the project already knows which repository it is, where it is hosted and which credential to present.

Mixing the two styles

For a project inside a Development Root, these do the same thing to the same repository — use whichever suits the moment:

Two spellings, one project

# from the root
nexa record -p my-project -m "Describe the change"

# from inside the project
cd my-project
nexa record -m "Describe the change"

A version recorded from inside the directory syncs from the root with -p, and the other way round. Nothing is tracked per style, so there is nothing to keep consistent.

Coming from Git

This style will feel familiar, and the model underneath still differs: there is no staging area, and a branch holds competing candidates rather than a single pointer. Coming from Git maps the commands across and covers where the two genuinely diverge.