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 source 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.
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 Add To Git Version Control and Clone a Git repository for more 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).
► 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.
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
Extensions –
VCS 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 server-based 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 server-based permissions, and a vehicle for collaborative project development from a single managed source.
In turn, the multiple access capabilities allows 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 centralized 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 to a server-based repository, using plain text or TCP/IP – or the secure svn+ssh equivalent.
- The
http method to a server-based repository, 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 Managed Projects in an Altium managed content server.
Connect to a SVN Repository
To connect to an existing SVN design repository, from the Data Management – Design Repositories page of the Preferences dialog click the 
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.
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 server and its access credentials.
For more information, see:
► The Data Management – Design Repositories page of the Preferences dialog.
► The SVN Design Repository dialog page.
Create a SVN Repository
To create a local SVN design repository, go to the Data Management – Design Repositories page of the Preferences dialog and use the 
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 server and its access. For more information, see the above links.
Nominate 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 
or 
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.
Use a 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 – Version Control » Add Project Folder to Version Control.
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.
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.
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.
Altium Managed Content Server VCS
The most advanced form of working with projects under version control is to harness the capabilities of an Altium Managed Content Server. A Managed Content Server offers the advanced construct of a Managed Project, which offers a simplified workflow, full lifecycle management, enhanced collaboration capabilities and more.
The target VCS repository in a managed content server is tightly integrated with both the server and Altium Designer (when signed in), which eliminates the need to setup and configure separate VCS repositories. User/Group access, the repository content and the status of projects can be managed through the server browser interface.
To learn more about managed projects, see:
► Managed Projects and Releasing a Design
► Working with a Managed Content Server
Additional information
Version Control Terminology
Version Control Terminology
|
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 where files are checked out to 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. |
References
References
