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 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 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
panel and Storage Manager panel. Projects
The key to how a version control system works is that it monitors the status of files that have 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.
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
.git system subfolder).
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 respository (Git).
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. 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 –
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.
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.
svn protocol to a server-based repository, using plain text or TCP/IP – or the secure
http method to a server-based repository, generally using
WebDAV over http – or the secure
Subversion (SVN) repositories are connected to, and created when necessary, in the
Data Management – Design Repositories page of the Preferences dialog. 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 from the associated menu - this opens the dialog. This provides SVN Design Repository 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.
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
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 dialog. Create SVN Design Repository
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
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
and Storage Manager 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. Projects
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
dialog – New Project File » New » Project » Project. Choose
VCS as the
Project Kind and select the target respository from the registered options in the Repository drop down menu.
The design files under version control in the repository can be subsequently checked out and loaded in Altium Designer using the
File » Check Out command, and ultimately Committed back to the repository (checked in) as new revisions when the edits are complete.
Once a compatible VCS repository is accessible in Altium Designer, design files can be added to and then checked out from the repository.
Using Version Control for a guide to applying version control to project design documents in Altium Designer.
Altium Managed Content Server VCS
Most advanced form of working with projects under version control is to harness the capabilities of an Altium
managed content server, such as an Altium NEXUS Server. The 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. In Altium Designer, projects are managed in the panel and the usual VCS commands are available in the Explorer Projects and Storage Manager panels.
For more information see:
► Managed Projects and Releasing a Design
► Working with a Managed Content Server Additional information
Version Control Terminology
Version Control System: A generic term applied to any tool that is capable of managing file version history and file retrieval.
The master storage of all the files under version (or source) control – can also be known as the database.
The master record of all the files under version (or source) control – also known as the Repository in practice.
To save your working copy of the file into the repository. Referred to as Commit in Altium Designer.
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).
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).
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.
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).
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.
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 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 are updated in the local working repository may be uploaded to the remote repository using the Push command.
The folder where files are checked out to from the repository, so they can be worked on – with Git, this is a local Working Repsitory. Files checked out from Altium Designer are automatically loaded.
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.
The 'local' copy of a file that changes are made to – normally resides in the Working Folder.
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.
The latest revision committed to the version control system.
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 which 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.