Version Control

When enabled, Sym3 allows users to save snapshots of a project, inside a project. The project version history is saved inside the project file and uses the popular Git version control system.

While an integrated Git library is used as fall-back, it is recommended that Git is installed on the system to allow for more advanced operations that would reduce file size and allow auto recovery. Git can be downloaded from here: https://git-scm.com/downloads.

A Note About Size

The very first commit takes the existing project data as a base for the changes going forward. All this data and each subsequent change is stored in project file and so the total file size will increase.

The extra size does not impact project loading times dramatically as the version history is not processed at load time.

For Operator projects, the upload window allows uploading a project without history to decrease upload data load.

Enable / Disable Version Control

PLEASE NOTE
When version control is disabled on a project with version history, then all history will be deleted.

Enabling

There are various methods of enabling Version Control and all result in an initial commit to show when version control was enabled.

Creating a new project opens the ‘New Project’ popup with the option to enable or disable Version Control.

The default can be set in the application settings (see below).
Using the ‘Version Control’ Panel, click ‘Enable’.
Using Sym3 Version Control context menu by right-clicking on a project file in Windows Explorer and then clicking Enable.

Disabling

WARNING
Disabling version control deletes all history

In either the Version Control panel, or the Sym3 Version Control context menu application, click the delete icon:

Application Defaults

Application settings in File->Settings->General->Project Version Control control the default behavior.

Enable version control for all projects: By default, new projects will have the ‘Enable Version Control’ checkbox selected.
Require commit message on save: On every save, a message must be entered to save. If not selected, then empty messages are allowed.
User Name: Default user name to use for each commit message.
E-Mail: Default user e-mail address to use for each commit message.
Git version: The currently installed version of Git if any.

It is recommended to install Git for better file size management. The installer can be downloaded from https://git-scm.com/downloads

Commits

A new commit is created every time the project is saved and represents a moment in history.

Each commit has the following parts:

Commit User: The user is derived from the current Windows user and domain.
Commit Date: The date and time of when the commit was created.
Commit Message: The message entered when saving. If allowed and no message was entered, a generic message will be created.
Commit ID: An automatically generated identifier for the commit.

Save Commit As

To get a project from any point in history, a new project can be created based on a selected commit. This new project will contain all the history up to that point in history.

Right-click at the desired point of history and select ‘Save Project As’:

Compare Commits

To see the difference between two points in history:

Right-click this first item to compare,
Choose ‘Select For Compare’,
Right-click on the second item to compare,
Select ‘Compare’

Each point in history selected is saved as a temporary project and then compared. Depending on the size of the project, this process could take few seconds.

Each file name is derived as follows: [ProjectName]_[Commit ID]_[Commit DateTime]
To see the location of these files, hover the mouse over its name.

Operator Upload

When uploading a project from Operator Editor, an option allows the upload to exclude the history. This saves upload data usage and does not delete history from the local project.

Macro Access

Version control can be accessed via macros. This requires a valid project and project file (i.e a project saved at least once).

The Macro API includes the following:

Enabled

Returns true/false to indicate if version control is enabled.
```
  var isEnabled = Project.VersionControl.Enabled;
```
History

Returns the list of commits in descending order (newest first).
```
  var commits = Project.VersionControl.History;
```
Enable()

Enables version control on a project. If already enabled, this does nothing.
```
  Project.VersionControl.Enable();
```
Disable()

Disables (and deletes!) version control on a project. If already disabled, this does nothing.
```
  Project.VersionControl.Disable();
```

SaveCommitAs(filename, commitId)

Saves a new project at a specific point of history.

filename: Full path to the file to create (string)
commitId: ID of the commit to save. Can be Commit.Id, Commit.Id.RawId or Commit.Id.Sha

  //get all commits
  var commits = Project.VersionControl.History;
  //History is ordered descending
  var firstCommit = commits[commits.Count-1];
  //Build a new filename based on the existing filename
  var saveasName = "C:\\MyProjects\\saved.s3i";
  //Save project at the first history point
  Project.VersionControl.SaveCommitAs(saveasName, firstCommit.Id);

CommitMessage

A string to store the commit message for the next commit.

  //Set a message
  Project.VersionControl.CommitMessage = "Saved from my macro!";
  //At save, a new commit will be created with the above message
  Project.Save();

Data Types

Commit

Id: CommitId - The unique ID of the commit
Committer: VersionControlUser - Committer of this commit
Message: String - Commit message
Parents: Commit[] - List of parent commits if any

CommitId

RawId: byte[] - The unique ID of the commit in bytes
Sha: String - The unique ID of the commit as a string

VersionControlUser

Name: String - User name (Windows login user)
EMail: String - Derived from Windows login: [Username]@[domain]
When: DateTime - Time of commit