Branches

Create and switch branches, save commits, and open change requests in the Istari Digital web app. Branches let you change a System's composition while keeping the work isolated and reviewable.

For how Resource versions and System branches fit together, see Version control. For a branch's history, see Commits.

Required role

Creating branches, committing changes, and merging change requests all require the Editor role or above on the System. Viewers can browse branches, commits, and change requests but cannot change them.

Switch branches

1. In the System's page header, click the chevron next to Branch | <name> to open Go to Branch.
2. Search for or select a branch. The System reloads on that branch's latest commit.

Click Branch | <name> itself, or Go to Branches in the dropdown, to open the Branches tab.

Create a branch

Requires Editor or above.

1. Click New Branch in the Go to Branch dropdown, or + Branch on the Branches tab.
2. In Create a new branch, choose the Source branch and enter a name for the new branch.
3. Click Create branch.

Commit work on the new branch, then merge it into another branch with a change request when the work is ready. To change what a branch tracks, see Edit what the branch tracks.

Branch options

The Branches tab lists the System's branches. Its tabs are Overview, Active, Archived, and All. Use Search branches to find one. Each row shows when the branch was updated and any open change request.

Open a branch's options menu (Branch Options) for these actions:

• Rename Branch: opens Rename branch. Enter a New name and click Rename branch.
• View Commits: opens the branch's Commits page.
• Copy Hash to Clipboard: copies the branch's latest commit ID.
• Archive Branch or Restore Branch: archiving keeps the branch's commits. Restore an archived branch to keep working on it.

The default baseline branch can't be archived, and you can't change which branch is the default.

Promote a branch

Promoting points a target branch at the same commit as a source branch, for example to move reviewed work into baseline. Promote is only available on the legacy Systems page. In the redesign, merge with a change request instead.

On the legacy page:

1. Open the branch switcher and select Go to Branches.
2. On the source branch's row, click Promote.
3. In Promote branch, confirm the Source branch and choose the Target branch.
4. Click Promote.

Commits

Each commit records one saved change to a branch: who made it, when, and a commit message. To see a branch's history, open its options menu on the Branches tab and select View Commits. From there you can open a commit to compare it with the one before it, or Restore it (called Rollback to this commit on the legacy Systems page). See Commits.

When tracked Resources or Subsystems have newer versions, Editors and above can accept them onto a branch that isn't archived from Changes Available. See Accept changes.

Change requests

Create a change request

1. Click Change Request in the System's page header.
2. Click Compare and Create Change Request.
3. On Comparing Branches, choose the From branch: (your working branch) and the Merge to: branch (the branch you want to update).
4. Enter a Change Request Title and an optional Description.
5. Review the System Delta, which lists the Resources and Systems that were added, removed, or changed.
6. Click Create Change Request.

You can also start a change request with Create change request on any row of the Commits page.

Review and merge

Merging requires Editor or above.

The Change Requests list has Open, Merged, and Closed tabs and a search box. Each request shows its title, status, and source and target branches. Open a request to see its Conversation, Resources Changed, and Commits tabs.

On Resources Changed, each entry shows a folder breadcrumb for where the Resource lives in the System. Files that were relocated are labeled moved.

• To merge, click Merge Change Request, add an optional comment, then click Confirm Merge and Close Change Request.
• To reject the changes, click Close, add an optional comment, then click Confirm Close.

If either branch has moved since the request was opened, merging is blocked until you refresh. This avoids merging a stale comparison.

Change requests have no separate approval step: anyone with edit permission can merge or close them.

What a merge changes

After a merge, opening the Merge to: branch shows the same Resources as the From branch:. You see the same versions, in the same folders, with the same Subsystems.

Read the System Delta before you merge. Each row is one change the merge makes on the Merge to: branch:

• Added. This Resource or Subsystem is on the working branch. After the merge, it is on the target branch too.
• Removed. This Resource or Subsystem is on the target branch and not on the working branch. After the merge, it is no longer on the target branch. It stays in an earlier commit on the target branch's Commits page.
• Changed. Both branches include this Resource or Subsystem, at different versions. After the merge, the target branch shows the version from the working branch. The whole file is that version. Two edits of the same text file stay two separate versions.

Someone may commit new work on the target branch after you create the working branch. That work stays on the target branch's Commits page, but opening the target branch after the merge does not show it. Open that earlier commit to view the work, or Restore it if you want the target branch to show it again.

To keep both sets of work, add the newer target-branch updates to the working branch before you merge.

Example. Baseline starts with requirements.txt at version 1. You create a branch named feature from that baseline.

• On feature, you commit requirements.txt at version 2 and add bracket.stl.
• A teammate then updates baseline: requirements.txt at version 3, and a new file, notes.txt.

You create a change request from feature (From branch:) to baseline (Merge to:), then merge it.

Resource	Baseline just before the merge	feature	Baseline just after the merge
requirements.txt	version 3	version 2	version 2, from feature
bracket.stl	not on baseline	on feature	on baseline
notes.txt	on baseline	not on feature	not on baseline; still in the teammate's commit on the Commits page

Version 2 and version 3 of requirements.txt are not combined into one file. To have version 3, notes.txt, and bracket.stl together on baseline, add the teammate's updates to feature before you merge.

Programmatic branching

To create branches, commit Resources, and open or merge change requests from Python, see Branching and change requests (istari-digital-client 10.14.0 or later).

Transitioning from configurations and snapshots

Branches replace configurations, which previous versions of the platform used to manage the set of Resources and Subsystems inside a System.

Your existing configurations were not deleted. They were moved to branches with the same names the configurations had before.

In previous versions, every update to a configuration captured a snapshot: a complete picture of the Resources and Subsystems at that moment. Those snapshots now appear as commits on the Commits page of the branch that replaced your configuration, in the same order they were created.

Opening any commit shows the System exactly as it was at that point. Anywhere you previously used a snapshot of a configuration, use a commit on a branch.