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 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.
► See Version Control and Design Repositories for an overview of Version Control and its implementation in Altium Designer.
There are a few preliminary steps that need to be completed before using Version Control for design projects. In essence, these are:
► See VCS Repositories for more information on creating and connecting to SVN repositories.
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.
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.
► See the Projects panel page for further information.
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.
► See the Storage Manager panel page for further information.
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 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 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 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 Designer user before you have committed your own edited and saved version of that file. Use the Update, Revert or Resolve VCS 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 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 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 –
► See Version Control Terminology for definitions of VCS functions such as Commit and Check Out, etc
The most advanced approach to using version control with Altium Designer is through an Altium Managed Content Server, such as an Altium 365 cloud-based Workspace or an Altium Concord Pro on-site server. The server products inherently support Version Control through their internal Git-based VCS repository, which integrates seamlessly with Altium Designer's project and file management interfaces.
Using version control is largely a transparent process when connected to an Altium server, where actions such as adding, checking out, and committing files to version control are automated or performed in the background. In practice, once a project has been added to a server (or created as a server-based project) you simply open, edit and save this now managed Project as you would a locally hosted 'unmanaged' project. The required Version Control processes are embodied in standard commands or presented as simple choices when necessary.
► See Workspace Projects for information on working with projects hosted in an Altium cloud-based server.
► See Concord Pro Projects for information about working with projects hosted in a self-managed Altium Concord Pro Server
To add an existing design project to an Altium server (and its VCS repository) that you have signed in to from Altium Designer, right-click on the project's name in the Projects panel and choose Make Project Available Online (when connected to an Altium 365 Workspace) or Make Project Available on Server (when connected to a self-managed Concord Pro server).
In a similar way, the process of updating design document changes to Version Control is handled by a conventional project save command – Save To Server – which will save edited documents to the local repository. Right-click on the project name to access this command, or the full range of available VCS commands from the History & Version Control option. The latter commands can be used for a less automated approach, such as using Commit Whole Project once the updated document has been saved locally.
► See Working with a Design Repository for more information on working with and managing server-based Version Control repositories.
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 is more convenient at hand, but it is worth noting that the Storage Manager panel provides more VCS detail and options.
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.
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 Designer'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 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.
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 Designer. In short, Git applies the transfer of data between multiple repositories, rather than focusing on the dependency of a single repository target.
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 Designer project in a Git system will depend on company infrastructure and practice and will involve tools and processes that are external to Altium Designer. 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 Designer is virtually the same as working with a SVN VCS.
By way of example, an existing Altium Designer 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:
*.*file spec adds files but not folders.
PCrepois a nominated local alias of the remote repository URL.
When the project is opened in Altium Designer, 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 Designer (), but are completed in individual steps here for explanation purposes.
The Altium Designer 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.
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 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.
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. The Commit Whole Project command could also be used, which will commit all modified files in the project,
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
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.
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.
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 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 Designer 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 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 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.
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:
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.
A local project that has been added to Git Version Control can be edited by Altium Designer from the project's local folder (the working repository), and the committed changes are 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 Designer, and ultimately pushed back to the remote Git repository.
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.
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.
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.
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
Revision 15) would overwrite the newer revision (
Revision 16) already committed by another user.
Revision 16), thereby losing any local changes you have made to
Revision 15. The revision conflict is therefore resolved, but the file will then be flagged as
Out of datesince a newer revision (
Revision 16) exists in the repository.
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.
► See the Differences panel page for more information on navigating differences.
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.
► See the Collaborate, Compare and Merge page for information on using advanced PCB collaboration features in Altium Designer.