Source control

Every Nexus keeps a version history of its own projects. Each time someone commits, Nexus records which screens, scripts and queries changed, who committed them, and why. From that history you can see what changed on the gateway, compare any two versions, put one screen back the way it was, or undo a whole commit.

The history lives on the gateway itself, in its data directory. There is nothing to install and nothing to connect to: it is switched on the first time Nexus starts, and it never talks to a server outside the gateway.

Where it appears

Where	For	What you can do
ConfigHub › Source Control	Whoever asks "what changed, and can I put it back?"	Read the history and every diff, restore one file, undo a commit, create and switch branches.
Studio › View › Source Control	The designer, while working	See what is not yet committed, read the diff, commit, and double-click a screen to open it on the canvas. History in ConfigHub… opens the page above.

Who can do what

• Reading the history and diffs needs only a sign-in. An operator debugging the plant at night can see what changed without being able to change it.
• Committing, restoring, undoing and branching need the Source control permission. Administrators and Designers have it by default; Operators and Viewers do not. Change it per role on ConfigHub › Security › Roles.

What is tracked

Only the configuration file and the projects are under version control:

• raylux_project.json: tags, devices, providers, historian connections, alarm and notification settings, and the gateway's own settings.
• projects/: one file per screen, script, named query and the rest of each project.

Nothing else in the data directory is ever committed, whatever anyone does to it. Passwords and other secrets, user accounts, keys and certificates, the license, history, alarms and logs all stay out. A password in a configuration field is stored in raylux_secrets.json and the configuration only names it, so a commit never carries one.

Committing

1. In Studio, open View › Source Control.
2. Not yet committed lists every change saved to the gateway since the last commit, whoever saved it. Select one to see its diff.
3. Write a message that says what changed and why. Whoever reads it later may be debugging a plant.
4. Click Commit.

The commit is recorded under your Nexus user name. It always takes everything that is not yet committed, including changes other people saved. There is no staging area to pick from.

Saving a screen does not commit it. Commit when a change is finished, the way you would tag a version before handing it over.

Restoring one file

On ConfigHub › Source Control, select a commit in History. The inspector lists the files it changed, grouped by project. Next to each:

• Diff shows exactly what that commit changed in the file.
• Restore… puts the file back to that version. For a file the commit deleted, it brings back the version from just before.

Before anything changes, Nexus shows the files it would write and warns when one of them holds work that is not yet committed. That work is lost if you go ahead. On confirm the screen changes on every client at once.

A restore is itself an ordinary change: it appears under Not yet committed, and someone commits it to keep it.

Undoing a commit

Select the commit and click Undo this commit…. Nexus works out the reverse of that commit and applies it to the current project, leaving every later change in place. As with a restore, the result is uncommitted until someone commits it.

Nexus refuses the undo when a file it would change holds uncommitted work. Commit that work, or restore the file, first.

Branches

A branch is a separate line of history, for trying out a rework without losing the version the plant runs today. The gateway starts on main.

• New branch from this commit in the inspector starts a branch at the selected commit.
• Switch to… in Branches moves the gateway to that branch. The projects change to that branch's version on every client.

Nexus refuses to switch while anything is uncommitted. Branches cannot be merged yet: to bring a change across, restore the file from the other branch's commit.

When a designer has unsaved work

When a restore, undo or branch switch changes a project that a designer has open in Studio:

• With nothing unsaved, Studio reloads the project straight away.
• With unsaved edits, Studio keeps them and marks the project as changed on the gateway. The next save stops and asks whether to reload the gateway's version, save over it anyway, or cancel. Cancel is the default, because the other two each lose something.

Edited outside Nexus

Nexus is the only thing that should write to its project files. If a file on disk differs from what Nexus last wrote, for example because someone edited it in a text editor or copied files in, it appears under Edited outside Nexus.

Such a file is never committed, and the next save of the same resource from Studio or ConfigHub replaces it. Make the change through Studio or ConfigHub instead. There is deliberately no "scan the disk" button to pull hand edits in.

Limits

• Only project files can be restored, undone or switched. Restoring the configuration file would change tags, devices, the historian and other gateway settings, and those cannot yet be applied to a running gateway from source control. Nexus refuses rather than asking you to restart. A commit that changed both shows the configuration file as not restorable.
• No push or pull. The gateway's history is the only copy, and Nexus holds no credentials for another repository. A data-directory backup carries the history with it; a configuration (.rnbk) backup does not.
• A configuration restore is not committed for you. Restoring a .rnbk file lands as uncommitted changes, so the next commit records it.
• The confirmation does not say whose work is lost. Nexus records who committed, not who saved an uncommitted change. ConfigHub › Security › Audit Log has that.
• History is kept for good. Nothing is pruned. Each commit stores a compressed copy of every file it changed, so the history grows with use.
• Keep the data directory on a local disk. A data directory on a network share is not supported: saving a project and recording history both rely on file renames and locks that network file systems do not guarantee.

If the history cannot be opened, for example because the files are damaged, Nexus keeps running. The log says why, and ConfigHub and Studio report that source control is unavailable.