Using External SVN Version Control with Altium Designer

Parent page: Using External Version Control

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.

Managing SVN Design Repositories

SVN design repositories are managed on the Data Management – Design Repositories page of the Preferences dialog. From this page, you can perform a number of actions, including:

• Creating new file-based SVN repositories using version control capabilities built-in to Altium Designer.
• Connecting to existing SVN repositories.
• Controlling the active state of each defined repository.

For each registered, or rather connected repository, the following information is presented:

• Name – a meaningful name for the repository. This could, for example, reflect the design projects that are stored in the repository. This name is used elsewhere in the software for quick selection of a Design Repository to be used, for example when opening a project from version control.
• Activated – whether the repository is available for use by the system (enabled) or not (disabled). A newly created or connected repository will be activated by default.
• Type – the type of repository; SVN or Git.
• Repository – the URL to the root folder of the repository.
• Status – whether the connection between Altium Designer and the repository is successful () or not (). If connection is unsuccessful a comment will be displayed, indicating the problem.

Creating a New SVN Repository

Creation of new Design Repositories from within Altium Designer is performed from the Data Management – Design Repositories page of the Preferences dialog. Click the  button and choose SVN from the associated drop-down menu. The Create SVN Design Repository dialog will appear.

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.

With all settings specified as required, click OK. The repository will be created at the nominated location and a connection to that repository from Altium Designer made. An entry will appear for it in the listing of Design Repositories back on the Data Management – Design Repositories page of the Preferences dialog.

Example newly created SVN Design Repository, appearing within Altium Designer as Local Repository.

Connecting to an Existing SVN Repository

In a collaborative environment, one or more Design Repositories may already have been created in a location accessible by multiple users. In this case, you do not need to create a new repository – re-inventing the wheel as it were – rather you simply need to connect to the required existing repository. This is also the case if you have removed a repository from your list of repositories, and want to add it back in again.

To connect to an existing repository, on the Data Management – Design Repositories page of the Preferences dialog click on the  button and choose SVN from the associated drop-down menu. The SVN Design Repository dialog will appear. Enter a name by which to refer to the repository from within Altium Designer, specify a default checkout path, and specify the repository access method and path to the root folder of the repository. You can also specify a particular sub-folder within the repository.

With all settings specified as required, click OK – a connection will be made and the repository will be ready for use.

Connecting to an existing repository – in this case, a local repository on the hard drive.

Connecting to an existing repository – in this case, a repository internal to a server installation.

Editing Repository Properties

You can also edit the properties of a Design Repository at any time. For example, you might want to change the name of the repository, as displayed and referenced within Altium Designer. Or you might want to edit the connection, perhaps to link to a different repository. To do this, select the entry for the repository in the listing of repositories (on the Data Management – Design Repositories page of the Preferences dialog), then click on the  button. The SVN Design Repository dialog (or Git Repository dialog) will appear, from where you can make changes as required.

Disconnecting from a Repository

To disconnect from a Design Repository, select its entry in the list and click the  button. The repository is removed from the list of connected Design Repositories. The repository itself is not deleted, it simply becomes disconnected from the system. To use a repository again, connect to it.

Using SVN Design Repositories

Once defined, the connected nature of an SVN Design Repository simplifies the ability to either add a project to that repository, or open an existing project from that repository. Instead of having to remember the path or drill down in a browse menu to select the repository, you simply choose the required repository from a convenient listing of all Design Repositories you are currently connected to, and that are activated for use.

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.

Adding a Local Project to an SVN Design Repository

Adding a local design project (not currently under version control) to a Design Repository is a straightforward process. With the project open, use the Add Project Folder To Version Control command from either the Projects panel or Storage Manager panel or from the Project » History & Version Control main menu. The Add to Version Control dialog will appear. The field at the top of this dialog presents a drop-down listing of all connected and activated Design Repositories. Select the repository required.

Click the  button to quickly access the Data Management – Design Repositories page of the Preferences dialog – if you need to connect a different SVN repository, or create a new one.

The folder hierarchy within the chosen Design Repository is presented to you in the Folders region of the dialog. Either specify an existing folder into which to add the design files, or create a new folder using the  button. In the latter case, a folder will be added at the specified position within the repository's folder hierarchy, named after the source folder containing the project.

Adding a Local design project to a local design repository.

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 Scheduled for addition

Committing a Project

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 Commit Whole Project command

The subsequent incarnation of the 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.

Inclusion of certain files added under version control

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

Creating a New Version-controlled Project

When creating a new Version-controlled project, the Repository field in the Create Project dialog presents a drop-down listing of all connected and activated Design Repositories. Select the repository required.

Creating a new Version-controlled design project – all defined Design Repositories are available for use.

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.

Opening a Version-controlled Project from an SVN Design Repository

Equally straightforward is the ability to open a Version-controlled design project that resides in a Design Repository. Use the File » Checkout command – the Check Out dialog will appear. Use the Check out from field to choose the required repository from a drop-down listing of all connected and activated design repositories available to you.

Click the  button to quickly access the Data Management – Design Repositories page of the Preferences dialog – if you need to connect a different repository.

The folder hierarchy within the chosen Design Repository is presented to you in the Folders region of the dialog. Use this region to specify the exact folder that is to be checked out from the repository.

Use the Check out to field to specify where the nominated folder content is to be checked out to. This is your local sandbox area.

Check out an existing version-controlled design project from a nominated Design Repository with controlled ease!

Locking Files of an SVN Project

The SVN VCS supports file locking so that no other user can commit changes to the locked files. To lock a project design file under SVN VCS, right-click it in the Projects panel and select the History & Version Control » Lock command (or select the Lock command from the right-click menu of a file in the Storage Manager panel). A locked file is shown with the  icon in the Projects and Storage Manager panels.

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 – Locked by me or Locked by someone else. The VCS text will also indicate combined conditions, for example; Modified and locked by me.

To unlock a document that is currently locked, right-click it in the Projects panel and select the History & Version Control » Unlock command (or select the Unlock command from the right-click menu of a file in the Storage Manager panel). After unlocking, any user can commit the document with any modifications to the version control repository.

Cleanup a Document

Before any changes are made to your local working copy of the project file, SVN creates a kind of 'to-do' list - actions it needs to do to perform the changes safely. As it performs these actions, it places a lock on the relevant part of the working copy while it works. This prevents other Subversion clients from accessing the working copy mid-change. Once finished, this lock is released and Subversion cleans up its private to-do list. If a Subversion operation is interrupted, however - for example, the process is interrupted, or if the computer crashes - the private to-do list remains on the disk. This allows SVN to return to that list later to complete any unfinished operations and return your working copy to a consistent state.

The cleanup command accessed by right-clicking on the entry for the project document and choosing the History & Version Control » Cleanup or by selecting the Project » Version Control » Cleanup command from the main menus searches your working copy and runs any leftover to-do items, removing working copy locks as it completes those operations, and ultimately returning your working copy of the project document to a consistent state.