Using Version Control with Altium NEXUS

Altium NEXUS supports the Subversion (SVN) and Git version control systems (VCS). Because it has internal support for these systems, it provides access to the common SVN/Git file handling commands such as Commit, Update, etc within Altium NEXUS, along with additional Subversion capabilities such as the ability to create a SVN repository. This integrates with the schematic and PCB comparison features, making it easy to quickly compare and identify differences between two revisions of a schematic or PCB document, and for PCB designs, resolving concurrent revision conflicts using the Altium NEXUS Collaboration capabilities.

There are a few preliminarily steps that need to be completed before using Version Control for design projects. In essence, these are:

• Ensure that the VCS Provider – SVN and VCS Provider – Git Extensions are installed in Altium NEXUS. These are installed by default, but can be accessed in the software's Extensions and Updates view.
• Check that SVN Version Control is enabled in the Data Management – Version Control page of the Altium NEXUS Preferences dialog.
• Select and/or create a SVN design Repository, and set up its connection with Altium NEXUS. Git repositories are handled outside Altium NEXUS.

► See VCS Repositories for more information on creating and connecting to SVN repositories.

Version Control access

In Altium NEXUS, VCS-related actions can be performed through the Projects and Storage Manager panels, with the latter providing direct access to additional VCS commands and information. The panels are populated with project documents and their related VCS status when opened in Altium NEXUS.

The panels can be opened from the button menu at the bottom right of the workspace, or from the main View » Panels menu.

Projects panel

The Projects panel displays all projects that are currently open in Altium NEXUS, along with their constituent documents and the associated Version Control status for each file.

The VCS file status in the panel is indicated through a series of icons that relate to specific file conditions detected by the version control system. The condition status for each file is, in general terms, relative to its equivalent that exists under version control in the linked repository. The VCS commands in the Projects panel are accessed from the Version Control option in the panel's right click context menu.

Storage Manager panel

The Storage Manager panel provides a rich view of the active document from a file storage perspective, and provides access to the local document history feature and version control status/commands.

The VCS file status in the panel is indicated through a series of descriptions and matching icons that relate to specific file conditions detected by the version control system. The condition status for each file is, in general terms, relative to its equivalent that exists under version control in the linked repository.

The VCS commands in the Storage Manager panel are accessed from the right click context menu. To perform a VCS action on a specific file, right click on its entry in the panel and select the desired command – for example, Commit, Update, Resolve conflict etc. The Storage Manager panel also includes detailed VCS and history events as time-stamped streams in the lower sections of the panel.

Version Control status

For both the Projects and Storage Manager panels, the current VCS status of each file that is under version control is displayed along with its entry in the panel.

The version control system essentially monitors and compares the files in the working folder to their counterparts in the design repository. Altium NEXUS both requests and exchanges information with the version control system via its VCS interface, and responds to the comparative file status conditions accordingly. In practice, this manifests itself in the Projects and Storage Manager panel file icons, through a range of VCS alerts, and by appropriate changes in the available file management commands.

The icons and their meaning are as follows:

[blank]		The file is not under version control in a VCS repository,
	No modification	The local copy of the file matches the file in the repository, and is up to date.
	Scheduled for Addition	A file has been added to version control, but not yet committed to the VCS repository.
	Modified	The local copy of the file has been modified in Altium NEXUS and saved to the working folder. Commit the file to create a new revision in the repository.
	Out of date	The local copy of the file (in the working folder) is older than its counterpart in the repository, and is therefore out of date. Use the VCS Update option to retrieve the latest file from the repository, or save the file, which will create a conflict condition.
	Conflict	The file has been committed by another Altium NEXUS user before you have committed your own edited and saved version of that file. Use the Update, Revert or Resolve CVS options to determine which version of the file will become the latest revision in the repository.
	Ahead of server (Git)	The file in the local working repository is newer than its counterpart in the remote Git repository. This occurs when a local file has been modified, saved and committed to the local repository, but not yet Pushed to the remote repository.
	Scheduled for Deletion	The project file has been removed from version control in Altium NEXUS, and will be deleted from the VCS repository and database during the commit process. This icon is also used when a file is missing from a populated local working folder – it has been deleted, renamed or moved – which is resolved by repopulating the folder from the repository with the VCS Update command.
	Locked	The file has been locked by yourself or by another user. When locked by you, the file cannot be updated to a new revision in the repository by another user (unless it is forced to be unlocked). While a single icon type is used to flag a locked file, its associated text will indicate who has locked the file – Locked by me or Locked by someone else. The VCS text will also indicate combined conditions, for example; Modified and locked by me.

► See Version Control Terminology for definitions of VCS functions such as Commit and Check Out, etc

Add to SVN Version Control

In general, project files can be added to a version control repository using the commands from either the Projects or Storage Manager panels, which involves the steps of registering the files for addition and then committing those files to VCS.

The process shown below uses the Projects panel, which more conveniently at hand, but it is worth noting that the Storage Manager panel provides more VCS detail and options.

Add a Project

The most direct approach to adding a project and its constituent documents to version control is to add the complete project folder to the VCS repository. To do so, select the Add Project Folder to Version Control command from the right click menu in the Projects (or Storage Manager) panel.

The following Add to Version Control dialog provides options to select the target design repository and subfolder. Use the button to automatically create a repository subfolder that matches the name of the source project folder – click to confirm the settings. The dialog will then populate with files entries derived from the source folder, with the project's constituent files selected – if necessary use the checkboxes to enable or disable files for inclusion.

Select to confirm the selections – note that file entries in the Projects panel now have the status of Scheduled for addition (). This indicates that the VCS has registered the files for addition to version control and are ready to be checked in (Committed) to the VCS repository.

Commit a Project

Files that have the status of Scheduled for addition () will be added to version control and the design repository when Committed. To do so, select the Version Control » Commit Whole Project command from the Projects panel right click menu to instigate the process.

The subsequent Add to Version Control dialog allows individual project files to be deselected (or additional ones selected) for inclusion under version control. A comment can also be added, which will be included in the forthcoming VCS revision.

The project and its constituent design documents are then copied to the VCS repository and registered as a new revision, while the status of the files in Altium NEXUS's panels is changed to No Modification ().

For more detailed information on the new revision, open any project document for editing and then select a file in the Storage Manager panel. The selected file's revision history and local document history can be seen in the panel's lower section, or an overall time line of events if you switch to 'classic view' – Switch to Classic View on the right click options. The indicated revision number will increment with each VCS commit, where the first revision (Revision 1) corresponds to the creation of the VCS project folders, prior to files being added.

Add to Git Version Control

As a distributed version control system, Git uses a different workflow to that of SVN, although the difference is minimal when working with established project files in Altium NEXUS. In short, Git applies the transfer of data between multiple repositories, rather than focusing on the dependency of a single repository target.

► See the Git website for more information and Version Control Essentials for an overview of the principles that apply.

A Git VCS system is typically based on a centralized, remote Git server that can host multiple Git repositories as needed. The fast, lightweight nature of Git lends itself to the practice of creating a remote repository for each project, which can then be cloned (copied) as a working repository to any user that is working on the project. Updated files in a user's working Git repository are then ‘pushed’ to the remote repository on the Git server to achieve synchronization.

The method used to establish an Altium NEXUS project in a Git system will depend on company infrastructure and practice, and will involve tools and processes that are external to Altium NEXUS. Once a project is in the version control system and made available as a local working repository however, working with a Git VCS in Altium NEXUS is virtually the same as working with a SVN VCS.

Add a project to Git

By way of example, an existing Altium NEXUS project can be added to a local Git repository using the basic Git command line tools. With this approach, the project folder becomes the local (working) Git repository, and this is linked and ultimately updated to an available remote Git repository.

Here, the tools are used to:

1. Create (initialize) the working Git repository in the project folder.
2. Add the project files to Git version control. The *.* file spec adds files but not folders.
3. Specify the link reference to the shared remote Git repository on a web server. PCrepo is a nominated local alias of the remote repository URL.

When the project is opened in Altium NEXUS, the status of its files in the Projects and Storage Manager panels is Scheduled for Addition (). When then committed to the working repository, the files change to the Ahead of Server status () since they are not, as yet, under version control in the remote Git repository.

The Push command will update the local repository files to the remote Git server, which may request valid credentials for the targeted repository – a once off process. Note that the Commit and Push operations can be called in one action in Altium NEXUS (), but are completed in individual steps here for explanation purposes.

The Altium NEXUS project, which is now fully under Git version control, becomes available to other users from the remote Git repository. Another user may clone the repository to their local machine, for example, and ultimately push their edited files back to the remote repository in a collaborative workflow.

Update new changes to Version Control

When a project has been added to version control, its local working project folder is now linked to its counterpart in the VCS repository, as indicated by the link icon associated with the project folder entries in the Storage Manager panel. To confirm the locations of the linked folder and repository, right click on any file entry in the panel and select the VCS Properties option (not available when using Git). The following Properties dialog includes the paths of the linked locations and information on the latest VCS revision.

As a result of the registered VCS link, the version control system can monitor and detect any differences between files in the local project folder and their equivalents in the VCS repository folder. When a difference is detected, such as when a design file has been edited and saved in Altium NEXUS, the version control system will change the status of the local file to Modified () and Altium NEXUS will offer an appropriate set of VCS commands on the right-click menu in the panels.

Commit changes

After a project document file has been edited and saved in Altium NEXUS it is flagged as Modified, and indicated as such () in both the Projects and Storage Manager panels. To commit those changes as a new revision in the VCS, right click on the file entry in the panel and select the Commit command from the context menu. The Commit Whole Project command could also be used, which will commit all modified files in the project,

• When using Subversion (SVN): The commit process copies the updated file from the local folder into the repository, incrementing the VCS entry's revision number and setting the file status back to No Modification ().
• When using Git: The commit process updates the local working repository VCS while incrementing the entry's revision number and setting the file status to Ahead of Server (). You can continue to edit, save and commit files in the working repository, or ratify the new changes by using the Push command to update the remote Git repository – the file status will then return to No Modification ().

View the Storage Manager panel to see the sequence of actions in the VCS Revisions section, which will include the creation of a new VCS revision (with an incremented revision number) for that file – in this case, Revision 3 and its added comment. The icon indicates the latest and current revision of the selected file, or in version control terms, the Head revision.

For a combined view of both revision and history event entries, change to the single Timeline view by selecting Switch to Combined View from the right click context menu.

Check out from Version Control

As outlined above, a local project that has been added to Version Control can be edited by Altium NEXUS from the project's local folder, and the changes then updated to the VCS repository. The local folder and the repository folder are linked and ultimately synchronized by the VCS.

Another user, who will not have access to the project from its source folder (which is local to your PC), can use the Check Out process to obtain their own copy of the files from the SVN repository that hosts the project. All users that wish to collaborate on the project design will need to connect to that common or 'centralized' SVN design repository, which is typically arranged to be accessible via the local network or from a server.

► See VCS Repositories for information on accessing design repositories.

To check out a project from a repository, select File » Check Out from Altium NEXUS main menu. Use the following Check Out dialog to select the desired repository from the drop down menu, or use the button to establish a new repository connection in the Data Management – Design Repositories page of the Preferences dialog. The Check out to option can be edited to override the path established in the initial repository connection setup.

The selected repository project folder and its constituent files will be checked out to the specified local folder and opened in Altium NEXUS. Note that the local folder is that defined as a checkout folder for the selected repository, and the checked out project is subsequently linked to its counterpart in the SVN repository. The VCS link instructs the version control system to monitor and detect any differences between the files in the local checkout folder and their equivalents in the VCS repository folder.

Commit the changes when the file edits are complete, which will synchronize the files in the design repository to match those in the checkout folder, creating a new VCS revision.

Checkout vs Open Project

When a local project has been added to version control there are in fact two ways that it can be edited and updated to VCS:

• By opening the local project (File » Open Project) in Altium NEXUS, and then committing saved changes to the VCS repository.
  In this case the local project folder and its counterpart in the repository are linked by the VCS.
  
• By checking out the project (File » Check Out) from the VCS repository, and then committing saved changes made in Altium NEXUS back to the repository.
  In this case the project in the nominated checkout folder and its counterpart in the repository are linked by the VCS.
  

The local project is the source, or origin, of the VCS project that is being shared with other users. Depending on how you would like to work, this local source version could be removed or locked as an archived project source, and the Check Out approach then used to make further edits. Or indeed, you could continue to open and work on the project files from the local 'source' folder (Open Project).

The best approach is to stick to one method (Check Out is recommended), since the two options deal with a working folder in different locations – the local source project folder, or in the nominated VCS checkout folder. Conversely, if both methods are used there will be multiple, active copies of the same project on the local PC. If these versions are dutifully Committed to the centralized VCS repository after each edit however, the repository will always hold the latest revision of the project, as intended.

Also note that once a project has been initially checked out from the VCS repository, it then exists locally and can be reopened directly from the checkout folder (File » Open Project). In this case there is again the choice of checking out a project from the VCS (File » Check Out) or opening the local version (Open Project), however there is only ever one local copy. In practical VCS terms the two methods are very similar, but will behave differently in some circumstances – such as when a local file is missing, where it will be restored by the Check Out command, but it will be removed from the Project by an Open Project command.

Clone a Git repository

A local project that has been added to Git Version Control can be edited by Altium NEXUS from the project's local folder (the working repository), and the committed changes then updated to the remote Git repository. The local repository and the remote repository are linked and ultimately synchronized by a VCS Push command.

Other users who wish to collaborate on the design can access the project by cloning the remote Git repository to a local working repository. While the approach to accessing files from a remote Git repository will differ with company systems and methods, a basic way to clone the content from a remote repository to a local working repository is by using the Git command; git clone [remote repository URL] [target working repository folder], as shown in the below image.

The process will replicate the shared remote repository as a local working repository and automatically check out the latest (HEAD) revision from the master branch. The files may then be edited, saved and committed to VCS in Altium NEXUS, and ultimately pushed back to the remote Git repository.

Version Control Revisions

During the course of working with design documents in Altium NEXUS that are under Version Control, design files that have been accessed from the central (shared) VCS repository will represent the latest revision of those files. When the local edits are complete and have been committed (or with Git; pushed) back to the shared VCS repository, these file versions then become the latest revisions.

As such, the normal sequence of check out, edit, save and commit (and Push, with Git) progressively adds new file revisions to the central VCS as the project design is developed. When a project is being collaboratively developed by several designers however, new revisions can be committed to the central (shared) repository at any time, by any designer.

Out of date Revision

The interaction between multiple designers and the central repository can manifest itself in a number of ways, one being that a locally open project is no longer the latest revision – a project checked out from the repository or opened from the local working folder, has a status of Out of date () in the Projects panel.

In this case another user has edited and committed the same project to the repository since it was last edited locally. For example, a local user Barry is working on the project and has committed say, Revision 14, but another user Harold has committed Revision 15 after that time, as indicated in the Storage Manager panel shown below. Because the VCS detects the difference between a file in the local working folder and its counterpart in the repository (which is newer in this case), the system deems the newest local revision (indicated by the icon) as out of date.

This situation is corrected by updating the local files to match those in the central VCS repository using the Update command from the Projects or Storage Manager panel right click context menu. The two file versions are then synchronized, with the local version (for user Barry) being updated to the latest revision version – in this example, Revision 15. Note that if you Save a file while designated as Out of date it will create a VCS Conflict situation, where the VCS detects that an older revision of a file has been updated in the working folder.

Revision Conflict

The interaction between multiple designers and the central repository can also create a situation where the same file has been locally edited and saved by two Altium NEXUS users, and one has committed those changes.

This means that one designer's sequence of steps (check out, edit, save, commit) have interleaved with that of another designer, so a file that a user has checked out from the repository for editing may not remain as the latest revision while it is being worked on – another user has updated the revision in the interim. Whoever first commits the edits to the repository in this case will dominate by creating a new revision, while another user that has edited and saved the same file will face a Conflict situation – indicated by the icon.

From a VCS perspective, which compares the working folder files to the repository files, a Conflict represents the condition where an out of date revision of a file in the working folder has been edited and saved.

The Storage Manager panel offers several command options that can be used when a file has a Conflict status:

• Commit – This option will trigger a Subversion error, since committing the locally edited revision (say, Revision 15) would overwrite the newer revision (Revision 16) already committed by another user.
• Update – This option will update the local file revision to the latest version from the central repository (Revision 16), thereby losing any local changes you have made to Revision 15.
• Resolve Conflict – This option is only recommended when a text file is in conflict, since the Subversion system will attempt to Merge the differences into the local file. That process will potentially corrupt other file types such as design documents, so a Conflict is best resolved by Updating to the latest source revision or by Reverting the local changes.
  When using Git, the Resolve Conflict command will override the conflict condition by committing the file to the local repository folder. When the file is then Pushed to the remote repository, the other designer's file will be flagged as Out of Date and must be updated. As with using Subversion however, the safest path is to Update the conflicted file to the latest source revision (a Pull in Git terms) or to Revert the local changes.
• Revert – This option will lose (undo) local changes, reverting the local file back to its base revision – here, Revision 15. The revision conflict is therefore resolved, but the file will then be flagged as Out of date since a newer revision (Revision 16) exists in the repository.

Compare Revisions

A valuable asset to working with Version Control is the ability to compare historical revisions of design files, which is provided by Altium NEXUS's built-in Difference Comparator and accessed from the Storage Manager panel. When used in conjunction with the Differences panel, a logical or graphical comparison can be made between VCS revisions while interactively exploring the affected objects. Both Schematic and PCB revisions can be compared.

To instigate a comparison between two revisions, select both entries (using the standard Ctrl+click method) in the Storage Manager panel VCS Revisions list, and then select the Compare command from the panel's right click context menu.

Both file revisions will be opened in split-screen mode, where they can be visually compared. The differences that are shown are determined by the options selected for the Physical comparison types in the Comparator tab of the Options for Project dialog – Project » Project Options.

The key to locating and viewing the comparison differences is in the Differences panel, which provides a selectable list of the logical or graphical differences between the documents. The panel's listed entries for each document revision interact with the editor, allowing a detected difference (such as a moved object) to be graphically highlighted when selected.

The Compare functionality also applies to revisions of PCB documents, along with revisions of Schematic and text-based documents.

The Compare command can be applied to any pair of revisions, including between the current local revision (in the working folder) and a newer revision in the repository. In this situation the latest local revision is indicated in the Storage Manager panel as Out of date () but can nevertheless be compared to a newer revision that has been added to the repository by another user.

This approach allows you to graphically preview the changes that will be imposed by updating to the new revision. In the example image above, the current local revision (indicated by the icon) is Revision 19 but another user has committed a new revision to the repository (Revision 22). Instigating a visual comparison between Revision 19 and Revision 22 allows you to make an informed decision about accepting the new changes from the repository, and by implication, whether you will apply the Update command or overrule by inducing a Conflict condition – through resaving the local file and resolving the conflict in favor of your local version.