Using Version Control

Altium Designer supports Subversion (SVN) and Concurrent Versions System (CVS). Because it has direct support for SVN, it provides access to the majority of the standard SVN commands, including the ability to create a repository, commit/update files, as well as being able to access (check out) file revisions from within Altium Designer. 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 Altium Designer's Collaboration capabilities.

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

• Install a Version Control application, or simply opt for the SVN application included in the Altium Design installation (recommended).
• Enable Version Control in Altium Designer.
• Select and/or create a design Repository, and set up its connection with Altium Designer.

These steps are outlined in the Version Control and Design Repositories page, with further detail available in thea Data Management Preferences and Version Control Reference sections.

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 it has been 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 » Workspace Panel » System 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 nominated repository. The VCS commands in the Projects panel are accessed from the Version Control entry 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 nominated repository.

The VCS commands in the Storage panel are directly 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 panel can also include VCS event entries, such as Commit etc, in the Time Line event stream contained in the lower section 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.

For VCS systems such as Subversion (SVN), the VCS essentially monitors and compares the files in the working folder to their counterparts in the design repository.  Altium Designer both commands 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 nature of the icon and description (in the case of the Storage Manager panel) associated with a file entry is dependent on which VCS system is being used. For Subversion and CVS version control installations, 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 (checked in) to the VCS repository.
	Modified	The local copy of the file has been modified in Altium Designer 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 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 Designer user before you have committed your own edited and saved version of that file. Use the Update or Resolve command to determine which version of the file will become the latest revision in the repository.
	Scheduled for Deletion	The project file has been removed from version control in Altium Designer, 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 the local working folder – it has been deleted, renamed or moved – which is resolved by repopulating the folder from the repository with the Update command.
	Locked	The file has been locked by yourself or by another user. A locked file cannot be updated to a new revision in the repository by another user (unless it is forced to be unlocked). This state can be associated with other icons, such as those for Modified  or No Modification , when these status conditions also apply.

Add to Version Control

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 approach is essentially the same for all version control systems, however the process detailed here assumes the Subversion (SVN) version control system and that the Storage Manager panel is used. Note that most VCS commands are also available from the Projects panel.

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 Storage Manager panel. Note that project needs to be open and active to populate the panel, and the file entries have the status of 'Not in Version Control'.

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. The dialog will then populate with files entries derived from the source folder, with the project's constituent files selected.

Select to confirm the selections – note that project file entries in the Storage Manager panel now have the status of 'Scheduled to 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 or Checked in. Following the steps outlined above, select the Commit Whole Project command from the Storage Manager panel's right click menu to complete the process.

The subsequent Commit 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 also be included in the forthcoming VCS revision.

Each project file has now been copied to the VCS repository and registered as a new revision. Select a file in the Storage Manager panel to see its history and revision number in the panel's lower Time line section, where in the example above, the files appear as 'Revision 2' – note that the first revision (Revision 1) corresponds to the creation of the VCS project folders.

Update changes to Version Control

When a project has been added to version control, its local 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 linked folder locations, note the pop up path information when the cursor is hovered over the folder name (local), and then the link icon (repository).

As a result, the version control system will monitor and detect any differences between the files in local project folder and their equivalents in the VCS repository folder. When a difference is detected, such as when a design file has been updated and saved in Altium Designer, the version control system will change the status of the local file (to say, 'modified') and Altium Designer will offer an appropriate set of VCS commands.

Commit changes

When a project document file has been edited and saved in Altium Designer, the VCS will detect that change and alter the file's status in the Storage Manager panel to 'Modified'. If wish to commit those changes as a new revision in the VCS, right click on the file entry in the Storage Manager 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,

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

The Storage Manager panel Time line will show updated the sequence of actions, including 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.

Note that the panel's Time line includes entries for both revision and history events, however these may be separated for clarity by switching to the Time line's 'Classic' view – right click in the panel section and select Switch to Classic View from the context menu, and select Switch to Combined View to return to the default event listing.

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 updated to the VCS repository. In this case 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 the other PC), can use the Check Out process to obtain their own copy of the files from the VCS repository. All users that wish collaborate on the project design will need to connect to a common or 'centralized' VCS design repository, such one that is accessible via the local network.

When connecting to that repository, a local repository Name and a local Checkout folder path are defined. The Checkout path defines where the VCS will copy the project folder and files from the repository to the local PC.

To check out a project from the repository, select File » Check Out from Altium Designer's main menu. Use the following Check Out dialog to select the 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 nominated 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 local checkout folder and their equivalents in the VCS repository folder.

The link can be noted in the Storage Manager panel by hovering the cursor over the folder name (local path), and then the associated link icon (repository path).

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 (File » Check Out) or opening the local version (Open Project), however there is only ever a 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.

Version Control Revisions

During the course of working with design documents in Altium Designer that are under Version Control, design files that have been checked out of the VCS repository will represent the latest revision of those files. When the local edits are complete and have been committed back to the VCS repository, these file versions then become the latest revisions.

As such, the normal sequence of check out, edit, save and commit progressively adds new file revisions to the VCS as the project design is developed. When a project is being collaboratively developed by a several designers however, new revisions can be committed to the central (common) 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 held 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 Storage Manager panel.

In this case another user has edited and committed that project to the repository since it was last edited locally. For example, you have previously worked on the project and committed say, Revision 18, but another user has committed Revision 19 after that time. Because the VCS detects the difference between a file in local working folder and its counterpart in the repository (which is newer), the system deems the newest local revision (indicated by the  icon) as out of date.

This situation is corrected by simply updating the local files to those in the VCS repository using the Update command from the Storage Manager panel's right click context menu. The two file versions are then synchronized, with the local version being updated to the latest revision version – in this example, Revision 19. Note that if you Save a file designated as 'Out of date' this will create a '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 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 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.

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 35) would overwrite the newer revision (Revision 36) already committed by another user.
• Update - This option will update the local file revision to the latest version from the repository (Revision 36), thereby losing any local changes you have made to Revision 35.
• Resolve Conflict - This option updates the file in the working folder to the latest revision (Revision 36) but allows the editor to retain the changes you have made (previously to Revision 35). The local file therefore acquires a state of 'Modified', allowing you to commit those changes to a new revision – which will be Revision 37. The other user will then see that file as 'Out of date' since you have created a newer revision.
• Revert - This option will lose (undo) local changes, reverting the local file back to its base revision – here, Revision 35. The revision conflict is therefore resolved, but the file will then be flagged as out of date since a newer revision (Revision 36) exists in the repository.

In essence, the panel's Conflict options allow you to either adopt the latest file revision (Update), create a new revision (Resolve Conflict) or simply lose your local edits (Revert).

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's Time line, and then select the Compare command from the panel's right click context menu.

Both file revisions will be opened in Altium Designer in split screen mode, where they can be visually compared. The differences that are shown are determined 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 component) to be graphically highlighted when selected.

The Compare functionality also applies to Schematic and text-based document revisions.

Note that 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 new 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 9 but another user has committed a new revision to the repository (Revision 10). Instigating a visual comparison between Revision 9 and Revision 10 allows you to make an informed decision about accepting the newer changes, 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.