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 Designer. 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 Designer Preferences dialog.
- Select and/or create an SVN design Repository, and set up its connection with Altium Designer.
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.
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 Default Checkout Path is a local folder defined as a checkout folder for the selected repository and the checked out project is subsequently linked to its counterpart in the VCS repository. The VCS link instructs the version control system to monitor and detect any differences between the files in local checkout folder and their equivalents in the VCS repository folder.
- 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 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.
Currently, only Design Repositories with the file repository access method can be created directly from within Altium Designer. A Design Repository using a different access method (e.g. networked access over http or https) can be set up outside of Altium Designer 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 Designer.
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.
Options and Controls of the SVN Design Repository Dialog
Design Repository Properties
- Name - review and/or change the name of the design repository.
- Default Checkout Path - click the browse button in the text box to search for and select the design repository folder.
Repository
The Repository fields are displayed for information only.
- Method - the method (connection protocol) of design repository.
The options/controls will change based on the repository access Method. The svn and https access methods require additional information that relates to the host Workspace and its access, whereas the file access method does not.
- Server - the host Workspace for the repository.
- Server Port - view whether the repository uses a default or non-default Workspace port.
- Default - if selected, the repository uses a default Workspace port.
- Non Default - if selected, the repository uses a non-default Workspace port. The Workspace port's information also will be displayed.
- Repository Subfolder - the repository's designated subfolder. Click
on the right side of the Repository Subfolder field to access the ![]()
Browse Repository directories dialog and select the subfolder in the repository directory.
- User Name - the user name for the repository.
- Password - the password for the design repository.
- Test - click to test if the connection to your design repository works. A dialog box will pop up to confirm whether it does or does not. If the connection fails, double-check and correct the information.
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.
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 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.
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. Click the
Setup custom repository control at the bottom-left of the dialog to 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 (
).
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.
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.
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.
You cannot lock the file if it is out of date.
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.
If Subversion ever tells you that some part of your working copy is locked, try running this command to remedy the problem.
