SVN-based Version Control

Applies to NEXUS Client version: 5

This documentation page references Altium NEXUS/NEXUS Client (part of the deployed NEXUS solution), which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace. Check out the FAQs page for more information.

 

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.

There are a few preliminary steps that need to be completed before using Version Control for design projects. In essence, these are:

  • Ensure that the VCS Provider – SVN Extension is installed in Altium NEXUS. These are installed by default but can be accessed in the software's Extensions and Updates view.
  • Check that SVN Version Control is enabled in the Data Management – Version Control page of the Altium NEXUS Preferences dialog.
  • Select and/or create an SVN design Repository, and set up its connection with Altium NEXUS.

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 NEXUS.
  • 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 NEXUS 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 NEXUS 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.

By default, the repository will be named Repository 1. Change this to a more meaningful name as required. There are no restrictions on naming.
The Repository Location can either be on your hard drive (for your own personal use) or in a network location (for collaborative use by a wider team).

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 NEXUS 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 NEXUS as Local Repository.
Example newly created SVN Design Repository, appearing within Altium NEXUS as Local Repository.

Currently, only Design Repositories with the file repository access method can be created directly from within Altium NEXUS. A Design Repository using a different access method (e.g. networked access over http or https) can be set up outside of Altium NEXUS using an external SVN interface tool, provided that tool bundles with it the Apache web server required to facilitate the http access method. Alternatively get the repository set up by your network administrator, or use one of the many providers of hosted Subversion repositories. You can then connect to that existing repository from within Altium NEXUS.

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 NEXUS, 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 local repository on the hard drive.

Connecting to an existing repository – in this case, a repository internal to a server installation.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 NEXUS. 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.

To disable use of a Design Repository, without removing it completely from the list, disable its associated Activated option.
If you remove a Design Repository that has been added through signing in to a managed content server, you can connect to it again. Alternatively, and far quicker, close out of the Preferences dialog, then sign out from the server and sign back in again. When you access the Data Management – Design Repositories page of the Preferences dialog again, the applicable repository(ies) will be present once again.

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.

When accessing a design repository for the first time, you will need to supply your login credentials – for example, login credentials for an external VCS server (e.g. for a design repository located on VisualSVN Server).

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. 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.
When Altium NEXUS 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.

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

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.

Inclusion of certain files added under version controlInclusion 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 NEXUS's panels is changed to No Modification ().

Once a project has been added to version control, further files can be added and committed to version control on an individual basis, using the singular Add to Version Control and Commit commands. Similarly, specific files can be individually removed from version control (but retained in the local working project) with the Remove from Version Control command.

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

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!
Check out an existing version-controlled design project from a nominated Design Repository with controlled ease!

Locking Files of an SVN Project

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.

Content