Skip to main content
Version: 2026.10

Version control

Version control on the Istari Digital Platform works at two levels: Resource versions track how a single registered file changes over time, and System branches track which Resources (and which of their versions) belong together as a coherent engineering state.

Note: A Resource is any registered file — uploaded or connected, model or artifact. See Resources. A System groups related Resources (and Subsystems) so ownership, sharing, and version tracking apply to the group. See Systems and Subsystems.

Why does it matter?​

  • Trace every file. Each Resource keeps an immutable revision history, so you can open, compare, or restore any earlier version without losing identity or permissions.
  • Iterate as a team. Branches isolate in-progress System work so engineers can add, remove, or pin Resources without colliding with each other's changes.
  • Review before you promote. A change request lists Resources and Subsystems added, removed, or changed. Those entries are the changes a merge applies to the target branch. A removed Resource or Subsystem is not on the target branch after the merge.
  • Recover and audit. Commits record who changed a System, when, and to what state, so you can step back through history or prove what was delivered at a milestone.

Two levels of versioning​

Resource versions​

When you register a file, the platform creates a Resource with a stable identity (UUID). Each time you upload or connect a new copy of that file, you add a version (also called a revision) to its history. Versions are immutable: later uploads append; they do not overwrite earlier ones.

Resource versioning is independent of Systems. A Resource keeps the same identity and revision history no matter how many Systems track it. When a System includes a Resource, it either tracks the latest version or pins a specific version until you change the pin.

Use Resource versions when you care about the evolution of one file — comparing geometry revisions, reviewing a requirements sheet update, or feeding a specific revision into a job.

System branches​

A System versions the composition: which Resources (at which versions) and which Subsystems belong in the group. That composition history is managed with branches, commits, and change requests:

ConceptRole
BranchA named line of work on a System. Every System starts with a baseline branch.
CommitOne saved change to a branch (add, remove, or update Resources, folders, or Subsystems). Newest first.
Change requestA reviewable proposal to make the target branch similar in content to the source branch. The source branch is the working branch.

Branches isolate parallel work. You commit on a working branch and open a change request when the work is ready. Merging updates the target branch (often baseline) so that opening it shows the same Resources as the working branch. Work saved on the target after the working branch was created stays in the target's commit history. Branches shows an example, including when the same text file was edited on each branch. Opening a commit shows the System exactly as it was at that point — every tracked Resource and Subsystem at the versions they had then.

Use System branches when you care about a deliverable as a set: a design review package, a simulation campaign baseline, or a release candidate that must freeze many Resources together.

How the two levels connect​

  • Updating a Resource's version does not by itself rewrite every System that tracks it. Tracked membership follows the latest version; pinned membership stays on the pinned version until you edit the branch and commit.
  • A System commit records which Resource versions (and Subsystem pins) were in the composition at that moment. Resource history and System history stay complementary, not duplicated.

Key details​

  • Baseline branch. Every System starts with a baseline branch. Other Systems that reference this one as a Subsystem default to it. The baseline branch cannot be archived.
  • Editor role. Creating branches, committing, and merging change requests require Editor or above on the System. Viewers can browse history but cannot change it.
  • Same Resource, many Systems. Version history lives on the Resource. Systems only record membership and pins.
  • Legacy names. Earlier releases used configurations and snapshots for System composition history. Those map to branches and commits in the current model; existing data was migrated in place. APIs and some SDK types may still expose the older names.

How to work with version control​

User guide (UI):

  • Update a Resource — Add a version and compare it with an earlier one.
  • Branches — Create, switch, and edit System branches; commits and change requests in the web app.

Python client (SDK):

Baseline, Branch, Change request, Commit, System