Working local-first

Suppose you have ~/Development/NewThing/ with files already in it, written before you had thought about version control at all. Nexa works on it as it stands. You do not need an account, a network connection, or a decision about hosting — and you can defer that last one indefinitely without working differently in the meantime.

Everything works offline

A repository is a local thing: one object database, one set of references. Creating one, recording work into it and reading its history are entirely local operations. None of them contacts Rinko Hub, and none of them checks whether you have an account.

Make the folder Nexa-managed

Run nexa init inside the folder. It creates the repository in place, alongside the files already there, and does not move or rewrite any of them:

Command

$ nexa init

Expected output

Initialised empty Nexa repository in .
Created workspace `main`

nexa start is an alias for the same command — it resolves to init and prints no notice. "Empty" in that output describes the repository's history, not your folder: nothing has been recorded yet, which is what you do next. A workspace called main is created to record into.

init is not root

nexa init creates a repository in this directory. nexa root is a different command that declares a Development Root — the folder your projects live underneath. This page does not need one: a repository created in place works on its own.

Record a first version

Recording captures the working tree as it stands. There is no staging step to perform first:

Command

$ nexa record -m "First version"

Expected output

Created version 996e6d0bb3b1
  workspace: main
  files:     1

Selected on branch main.

The file count reflects whatever the folder held; the capture above came from a directory with one file in it. That recorded version is now the selected version on branch main — a complete tree you can return to, entirely on your own disk.

From here, nexa status reports what has changed since, and nexa history lists what you have recorded. Both are local, and you can work this way for as long as you like. A repository that is never published is not a degraded one: it has the same objects, the same immutable history and the same candidate model as any hosted repository. It simply has no copy anywhere else — which also means no backup, and no way for anyone else to reach it.

Publishing later

When you do want the work hosted, there are two commands, and which one you need depends on whether the Rinko Hub repository already exists. Both require that you have authorized this machine with nexa login first; without a profile, hosted commands fail with error: this machine is not signed in to Rinko Hub with that profile; run `nexa login`.

Publish it

nexa publish creates a new Rinko Hub repository for the work in this directory and publishes the version you recorded. It is one command and it finishes the job: it creates the repository — named after the directory, or after the name you pass as nexa publish [NAME] — waits for Rinko Hub to prepare it, which can take up to about two minutes, and then performs the initial synchronization. New repositories are private unless you pass --public, and --org <ORG> creates the repository under an organization rather than your personal account.

Command

$ nexa publish

Expected output

Published to Rinko Hub.

The output ends with that line, and when it appears the repository and its code are live on Rinko Hub. You do not run nexa sync to make the code show up — that is what publish just did.

Three things to know about it. It publishes recorded state: with nothing recorded it refuses — No recorded version to publish. Run nexa record -m "Initial version" first. — and edits made since your last nexa record are left out, with Warning: unrecorded working-tree changes were not included. printed so you know. And it is safe to run again: a second nexa publish in the same directory never creates a second hosted repository; it synchronizes the one that exists.

Or associate it with an existing one

If the Rinko Hub repository already exists — someone created it in the web interface, or it belongs to your organization — use nexa link instead. It associates the work in this directory with that hosted repository rather than creating a second one, and performs a first exchange with it:

Command

$ nexa link acme/capture-demo

After either command, nexa sync is how you exchange every later recorded change, and it never needs a destination named: both commands register this directory as a working context that knows which hosted repository it belongs to.

One association, chosen once

publish creates a hosted repository; link associates with one that already exists. Running publish in a directory that has never been published, when you meant link, leaves you with an extra repository on Rinko Hub rather than an error, so check nexa repos first if you are unsure whether one exists. Re-running publish in a directory that has already been published is different, and safe: it finds its own repository and synchronizes it.

Nothing about the local repository changes when it becomes hosted. The versions you recorded offline are the same objects, with the same identifiers, and your history is not rewritten to accommodate the association. If you would rather stay local, that remains a supported way to use Nexa — it is simply not the path that gets you backup or collaborators.