Altium Designer Documentation

Version Control & Design Repositories in Altium Designer

Created: September 9, 2021 | Updated: September 25, 2021

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.

Typically a version control system will also handle the situation where a file has been checked out and modified by multiple people, who could then check their changes in on top of each other, potentially losing a designer's work in the latest revision. Dealing with this requires tools to compare versions of the file to detect differences and an interactive tool to merge the differences back into a single version of the file, such as the PCB collaboration capabilities available in Altium Designer.

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

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 – for Altium Designer, this can be Subversion (SVN) or Git.

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.

Concept image showing how the files are managed by the Subversion Version Control System

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.

Concept image showing how the files are managed by the Git Version Control System

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

See Using Version Control for more information on working with SVN and Git version control systems in Altium Designer.

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

The Commit command registers the updated file in the repository, increments the revision number (stored internally in the VCS), logs a message that you can enter to describe the changes made to the file, and in the case of Subversion, stores the copy of the file in the central repository. In the Git arrangement, the updated file may be copied from the Working repository to the Remote repository at any time using the Push command.

Software with the Storage Manager panel open, where VCS-type features and commands can be accessed
The Altium Designer Version Control interface can be accessed directly from the Projects panel or from the Storage Manager panel, where more options are available.

Both the SVN and Git version control capabilities that are available in Altium Designer are enabled by their respective ExtensionsVCS Provider - SVN and VCS Provider - Git. These are installed by default and may be accessed through the software’s Extension & Updates view.

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 and Collaborate, Compare and Merge panels. Altium Designer offers sophisticated PCB design collaboration features that allow file merge differences to be viewed and resolved within the editor, to ultimately create a new Head revision in the VCS. The advanced PCB collaboration functionality also allows for live design collaboration between multiple users, with the ability to define and assign sections of a design as user Work Regions.

See Using Version Control for a guide to applying version control to project design in Altium Designer.

VCS Repositories

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.

Depending on the type of repository, it will be accessible via a range of protocols that include:

  • Conventional file access, which is usually for local or network-based repositories.
  • The svn protocol, using plain text or TCP/IP – or the secure svn+ssh equivalent.
  • The http method, generally using WebDAV over http – or the secure https equivalent.

Subversion (SVN) repositories are connected to, and created when necessary, in the Data Management – Design Repositories page of the Preferences dialog.

  • Git-type repositories are created outside of Altium Designer, and the content of a local working Git repository is accessed by opening files from its host folder.
  • The management of both remote and local working Git repositories is typically through company systems and external Git tools, while file-level operations (Commit, Push, Update, etc.) are handled in the Altium Designer editing environment.
  • The management of repositories is handled automatically when using projects in a connected Workspace.
See Working with a Design Repository for additional information.

Connect to an SVN Repository

To connect to an existing SVN design repository, from the Data Management – Design Repositories page of the Preferences dialog click the Connect To button, click to access the SVN Design Repository dialog button, then choose the SVN entry on the associated menu – this opens the SVN Design Repository dialog. This provides Design Repository Properties settings that allow you to define the local name of the repository connection and its target folder path for checked-out design files.

SVN Design Repository dialog where the connection details, such as repository location and connection method, are defined
When an existing SVN repository is registered in Altium Designer it allows design files to be included under Subversion version control.

The dialog's Repository options need to be configured to match the available repository's location, an optional subfolder target, and a compatible protocol method for the connection. Note that the svn and http access methods require additional information that relates to the host system and its access credentials.

This connection process is not required for the native Git repository of a Workspace. Altium Designer will automatically connect to the Workspace's Git repository when a user signs in to that Workspace. See Accessing Your Workspace.

Create an SVN Repository

To create a local SVN design repository, go to the Data Management – Design Repositories page of the Preferences dialog and use the Create New button, click to access the Create SVN Design Repository dialog button to open the Create SVN Design Repository dialog.

The dialog provides a range of configuration options that allow you to define the repository's folder location and method (connection protocol), and the local connection name and target folder path for checked-out design files. Note that the svn and http access methods require additional information that relates to the host system and its access. For more information, see the above links.

Create SVN Design Repository dialog, use to create a new repository, specifying location, connection method & working folderNominate or create a local folder that will be configured as a named VCS repository.

The installed VCS system will subsequently create the correct version control file structure and database in the nominated repository folder. Once created and registered, the new repository entry will be connected and listed in the Data Management – Design Repositories page of the Preferences dialog. Click Dialog OK button or Dialog Apply button to confirm the changes.

The process of creating a VCS repository – traditionally completed using an external (separate) VCS client – can be done directly in the Altium Designer Preferences dialog.
The process of creating a VCS repository – traditionally completed using an external (separate) VCS client – can be done directly in the Altium Designer Preferences dialog.

Use an SVN Repository

With the new or existing design repository available to Altium Designer, project design files can be added to and retrieved (checked-out) from the repository using the Storage Manager and Projects panels, and commands from the main menu. As the repository files exist under version control, all design revisions are tracked and accessible from within Altium Designer.

Use the project name right-click context menus in the Storage Manager or Projects panels to add then commit a complete project folder (and its constituent design files) to version control – by choosing the History & Version Control » Add Project Folder to Version Control command and using the subsequent Add to Version Control dialog then choosing the History & Version Control » Commit Whole Project command and using the subsequent Commit to Version Control dialog.

When Altium Designer is connected to an Altium 365 Workspace, the Add to Version Control dialog will suggest you make the chosen project available online, i.e. add it to the Workspace's native VCS. Select your connected SVN repository from the dialog's top drop-down menu to proceed with adding the project to this SVN repository.

Add to Version Control dialog, used to add documents to the VCS repository

Alternatively, a new project can be added to version control while being created through the Create Project dialog – File » New » Project. Choose Version Control in the Locations list on the left of the dialog, and select the target repository from the registered options in the Repository drop-down menu.

Create Project dialog, showing how a new version-controlled project can be created

The Local Storage option in the Create Project dialog defines where the working copy of the project is stored. It is these files that are opened and edited in Altium Designer and ultimately committed back to the repository (checked-in) as new revisions when the edits are complete. The working copy of the project can be re-opened for editing using the File » Open Project command, or the File » Recent Projects list.

If required, a fresh instance of the project can be checked out to a new working folder and loaded in Altium Designer using the File » Check Out command, as shown below.

Check Out dialog, used to check a project out from the repository
Once a compatible VCS repository is accessible in Altium Designer, design files can be added to and then checked out from the repository.

See Using Version Control for a guide to applying version control to project design documents in Altium Designer.

Connected Workspace VCS

The most advanced form of working with projects under version control is to harness the capabilities of a connected Workspace. A Workspace offers the advanced construct of a project, which offers a simplified workflow and storage, enhanced collaboration capabilities, and more.

The target VCS repository in a Workspace is tightly integrated with both the Workspace and Altium Designer (when signed in), which eliminates the need to set up and configure separate VCS repositories. User access, the repository content, and the status of projects can be managed through the Workspace browser interface.

Additional Information

VCS

Version Control System: A generic term applied to any tool that is capable of managing file version history and file retrieval.

Repository

The master storage of all the files under version (or source) control – can also be known as the database.

Database

The master record of all the files under version (or source) control – also known as the Repository in practice.

Check-in

To save your working copy of the file into the repository. Referred to as Commit in Altium Designer.

Check-out

To take a copy of a file from the VCS repository into a working folder. This is generally the latest revision of the file, but all earlier revisions can also be checked out. Depending on the VCS, the file can be flagged as simply checked-out, or checked-out exclusively (locked).

Commit

Save the working copy of the file back into the repository. Referred to as Check-in in some version control systems. In Altium Designer, the normal Save command saves an edited file to the working folder, whereas Commit saves that folder file to the repository as a new revision (version).

Push

To update a remote Git repository with the file(s) in its local working repository – to synchronize the local and remote repositories. This command is available when a file in the local Git repository is newer than its counterpart in the remote Git repository. Notionally the compliment of a Git Pull command.

Conflict

The situation when two Altium Designer users attempt to commit changes that affect the same region of the same file. These must be resolved, either using a Merge tool, manually, or by determining which version will dominate (become the new revision).

Update

The act of checking for and 'pulling in' changes from the repository version of a file to a working copy (the compliment of Commit, or Check-in). The process of merging in any differences requires a Merge tool or manual updating.

SVN

Subversion is an open-source version control system. Altium Designer incorporates SVN capabilities (through the VCS Provider - SVN extension), allowing revisions to be directly tracked and accessed from its Storage Manager and Projects panels.

Git

Git is an open-source version control system. Altium Designer incorporates Git capabilities (through the VCS Provider - Git extension), allowing revisions to be directly tracked and accessed from its Storage Manager and Projects panels.

Clone A Git command that copies (clones) a remote Git repository to a working Git repository in a local folder, while automatically checking out the HEAD (latest) version to the folder. The local repository includes the link reference to the remote repository (origin in this case), so files that are updated in the local working repository may be uploaded to the remote repository using the Push command.
Working folder

The folder to which files are checked out from the repository so they can be worked on – with Git, this is a local Working Repository. Files checked out from Altium Designer are automatically loaded.

Log message

A comment about changes made to a revision when it is checked back in (committed) to the repository. The log messages can be used as a summary of the progress of changes in a file.

Working copy

The 'local' copy of a file that changes are made to – normally resides in the Working Folder.

Revision

A committed change in the history of a file or set of files. This is the alpha-numerical reference supplied by the VCS to track the different editions (versions) it is holding of the file.

Head

The latest revision committed to the version control system.

Base

The revision in the repository that you checked out to be your local Working Copy. Also called the checked-out revision.

Project Many version control systems support the concept of a project. A VCS project is a set of related files that can be checked in/out as a set. The VCS may also support other project-type features, such as setting a version number on all files in a project. This is distinct from the concept of an Altium Designer project, which can be added to Version Control using the 'Add Project Folder to Version Control' command.
Found an issue with this document? Highlight the area, then use Ctrl+Enter to report it.

Contact Us

Contact our corporate or local offices directly.

We're sorry to hear the article wasn't helpful to you.
Could you take a moment to tell us why?
200 characters remaining
You are reporting an issue with the following selected text
and/or image within the active document: