Using External Version Control with Altium Designer

One of the greatest strengths of an electronic authoring and editing environment is the ease with which you can create and modify a file. This capability means that ideas can be captured, explored, and matured quickly, but it also means that it can be difficult to keep track of changes made to valuable files such as source code and electronic design data.

The need to keep track of changes made to a file, combined with the need for a systematic solution for managing sources captured in an electronic form, has given rise to Version Control Systems (VCS). Version control systems are software tools that are not only able to maintain a history of the various versions of a file, they also support opening any revision of that file, as well as comparing changes made between any two versions of the file. A VCS will generally integrate with the local Operating System (OS) by providing additional versioning functions and operations for folders and files.

Version Control Systems can be operated completely independently of the authoring and editing environment used to create a file. They typically offer an interface that allows you to Add then Commit files into a central storage area called the repository, a Checkout feature to copy a file from the repository to a working folder, a Commit feature to check back in any changes to the repository, a method of logging information about a change, and much more.

These features are found in Windows shell extensions such as the Tortoise client and are also included in Altium Designer itself. VCS operations can be performed within the Altium Designer environment without the need to access the OS file system.

It is helpful to understand the terminology used with version control systems. Even though there are numerous systems available, they generally all use similar terms to describe their functionality.

Version Control Essentials

Altium Designer 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 Designer, along with additional Subversion capabilities such as the ability to create an 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.

The basic approach to working with a Version Control System (VCS) is to access a copy of the project files that you want to work on from a repository, edit the files in Altium Designer and then ‘commit’ the modified files back to the repository. The interaction with the repository is through a version control system interface, which Altium Designer has built into its Storage Manager panel and Projects panel.

The key to how a version control system works is that it monitors the status of files that have been accessed from the repository, via a working folder, and therefore tracks what revision is being worked on and if it has been modified. Although the outcome is the same, the repository and working file arrangements differ between types of version control systems – Git or SVN.

Git VCS

The figure below illustrates the concept of a Remote Git repository share that holds a sequence of design file revisions (up to revision 5), where its content has been copied to a local Working Git repository – typically by Cloning the remote repository or Pulling its data into the working repository. When the files in the working repository are opened in the Altium Designer environment, Altium Designer recognizes that a project file is under Git version control, with its current version control status being shown in both the Storage Manager and Projects panel.

► See the Git-based Version Control page for further information.

Subversion VCS

The figure below illustrates the concept of a Subversion repository that holds a sequence of design file revisions (up to revision 5), with the latest copy checked out (File » Check Out) in a working folder. When the files in the working folder are opened in the Altium Designer environment, Altium Designer recognizes that a project file is under SVN version control, with its current version control status being shown in both the Storage Manager and Projects panel.

► See the SVN-based Version Control page for further information.

In both of the above VCS systems, the link between the source repository and the working location is referenced in the latter’s VCS database (in the .svn or .git system subfolder).

When VCS working files are open in Altium Designer the right-click menu in the Storage Manager panel (and the Projects panel) allows you to perform standard VCS actions, such as committing a changed file to the central repository (SVN) or working repository (Git).

Version Control Access

In Altium Designer, 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 Designer.

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 Designer, 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.

Version Control icons as they appear in the Projects panel

► See the Projects panel page for further information.

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 Storage Manager panel

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 selected file's revision history and local document history can be seen in the panel's lower section, or an overall timeline 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.

► See the Storage Manager panel page for further information.

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 Designer 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 described in the Version Control Status Icons section of the Managing Project Documents page.

Multiple User Access

In most situations, a company’s Version Control infrastructure will be based on central SVN or Git repositories, served over the network using one of the available protocol methods – svn, svn+ssh, https, etc. This provides access to all users on the network, subject to permissions, and a vehicle for collaborative project development from a single source.

In turn, the multiple access capabilities allow different team members to continue working on a project independently, without having to wait for someone else to check a file back in before they can work on it. A distributed Git version control system takes this advantage one step further by allowing files to be committed to the local working repository as you work, and those committed changes ‘pushed’ back to the central Git repository at any later time – and as such, does not require a network connection until then.

Nevertheless, a team-compatible VCS does require that the tools and techniques are available to resolve the inevitable situation where two users have modified the same file. When these capabilities are available, the foundation is in place for true multi-user design collaboration and its associated benefits.

To support this situation, Altium Designer includes schematic and PCB comparison (or 'diff') capabilities, available through the Storage Manager panel.

VCS Repositories

The best way of working from a known set of source files is to store the design project in a controlled environment, such as a Version Control repository. This is important because the only way of ensuring the outputs come from the correct source files is to:

1. Confirm that the source file set is up-to-date.
2. Take a snapshot of them.
3. Generate outputs from that snapshot.

In Altium Designer, such a repository is referred to as a Design Repository. Owned by the design team, the Design Repository contains a high-resolution view of the history of the design process and is the primary collaboration tool used by the design team.

The Design Repository becomes the central repository from which multiple team members can check data in and out, all the while maintaining a complete revision history of all changes made to the design. A design is therefore stored as a series of versions of its constituent project and source documents, building a progressive picture of the intent of a designer over time. By using a version-controlled Design Repository, you have the integral assurance that no revision of a design is ever lost, allowing for safe collaboration on the same design between members of a team that can be geographically dispersed in their locations. The very nature of the version control system provides an audit trail for the design. Full accountability arises through transparency of whom changed what, in which source document, and when. The system can support multiple version-controlled Design Repositories with the link to a particular repository being established by the version control link within the project folder.

Before using version control, the project files must be recognized by both the VCS and Altium Designer as being under version control. This process can be different for the various VCS methods and applications, but it essentially entails creating and/or connecting to a design repository and adding design project files to that repository.

Design repositories are based on a database structure, and internally store information in a hierarchy of files and directories, referred to as a file tree. The actual repository that you connect can be a central SVN repository, a Git working repository (that is associated with a remote Git repository), or one you have created in an accessible location such as on the local PC or a shared network location.

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.

File indcated by link icon and the cooresponding Properties panel that contains information on the latest VCS revision

The Properties dialog provides the following information (the information is for viewing purposes only; no edits are allowed): 

• Path - the path to the local document in your working folder).
• URL - the URL for the document's location in the VCS repository.
• Repository Root - the repository root.
• Repository UUID - the repository UUID.
• Revision - the current revision of the document in your local working folder.
• Last Change Author - the author of the last change.
• Last Change Revision - the revision of the last change
• Last Change Time - the date and time of the last change.
• Conflicted - whether or not the document is conflicted.

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 Designer, the version control system will change the status of the local file to Modified () and Altium Designer 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 Designer, 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 or select the Project » History & Version Control » Commit command from the main menus.

When committing a change to a file, the Edit Comment dialog will open. Use this dialog to add a comment stating the reason for the commit, which can help others see what change(s) have been made. If you have added previous comments, you can quickly select to use one of these.

The Commit command

The Commit Whole Project command could also be used, which will commit all modified files in the project. When committing the whole project, the Commit to Version Control dialog will open.

The Commit to Version Control dialog

• 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 the current revision of the selected file, or in version control terms, the Head revision.

The VCS Revisions section of the Storage Manager panel

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 Designer from the project's local folder, and the changes are 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 Clone (Git) or Check Out (SVN) process to obtain their own copy of the files from the VCS repository that hosts the project. All users that wish to collaborate on the project design will need to connect to that common design repository, which is typically arranged to be accessible via the local network or from a server.

The selected repository project folder and its constituent files will be checked out to the specified local folder and opened in Altium Designer. 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 VCS 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 Designer, 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 Designer 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 or opening the local version, 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 process, but it will be removed from the Project by an Open Project command.

Version Control Revisions

During the course of working with design documents in Altium Designer 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.

File that is labeled Out of fate

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.

Different revision states in the Storage Manager

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.

The Central Repository and Local revision in the Storage Manager

You can also select the Update Whole Project command to access the Update from Version Control dialog that allows you to select files to be checked out from a shared repository. All documents in the project that are out of date or contain conflicts are displayed in the dialog. You can select specific documents to update or choose to update all of them at once. Selected documents are updated from the repository and all out of date documents are selected by default. All selected documents will be updated to the latest version in the repository.

The Update from Version Control dialog

The Path column displays the file directory. The Status column displays the current status of the file. If a file's status is displayed as Conflict, clicking OK to update the files will prompt a confirmation dialog. Click OK to update to the latest version in the repository or Cancel to exit and save changes to the version currently in the repository.

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 Designer 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.

Revision Conflict example

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.

Git VCS Revisions in the Storage Manager panel

There are several command options accessed from the History & Version Control right-click menu of the Projects panel, the Project » History & Version Control main menu and the Storage Manager panel 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 will discard changes committed to the repository since you last updated. After launching the command, a confirmation dialog will appear - click Yes to proceed. The project file in your working folder will be updated to the latest revision checked into the repository by the other user, but the editor will retain the changes you have made to the previous revision. The local file, therefore, acquires a state of Modified, allowing you to commit those changes to a new revision in the repository - using the Commit command, or the Commit Whole Project command. Once you have committed the project file, the other user will see the file(s) as Out of date, since you have created a newer revision in the repository.

  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 Designer'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.

The Compare command in the Storage Manager panel

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.

Locating and viewing the comparison differences is in the Differences panel

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

• For schematic or PCB (design or library) documents, a graphical comparison is made and the differences detected listed in the Differences panel. With the two versions of the document open side by side in the design editor window, you can peruse the differences graphically. Clicking on a top-level folder for a detected difference will highlight that difference on both documents simultaneously.
• For text-based ASCII documents, the CompareForm dialog will appear, showing a graphical 'diff' of the two versions of the document. The chosen documents are displayed side by side. The dialog is for comparison only - no modifications to a loaded document can be made. Through color-coding, the dialog highlights the various differences between the two document versions - lines added (pink), lines modified (green) and lines deleted (blue). A summary of changes and color-code legend is presented at the bottom-left of the dialog.

The Compare functionality

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.

Local revision is indicated in the Storage Manager panel as Out of date

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 – throu gh resaving the local file and resolving the conflict in favor of your local version.

Version Control Terminology

References

• SVN website: http://subversion.apache.org/
• SVN online manual: http://svnbook.red-bean.com/
• SharpSVN project home: https://sharpsvn.open.collab.net
• Git website: https://git-scm.com/
• Git online documentation: https://git-scm.com/doc
• The Tortoise Clients: http://tortoisesvn.net and https://tortoisegit.org/
• Source Control How-to, by Eric Sink: http://www.ericsink.com/scm/source_control.html