Working with a Design Repository

This document is no longer available beyond version 21. Information can now be found here: Using External Version Control for version 24

 

Parent page: Version Control and Design Repositories

The best way of working from a known set of source files is to store the design project in a controlled environment, such as a Version Control repository. This is important because the only way of ensuring the outputs come from the correct source files is to:

  1. Confirm that the source file set is up-to-date.
  2. Take a snapshot of them.
  3. Generate outputs from that snapshot.

In Altium Designer, such a repository is referred to as a Design Repository. Owned by the design team, the Design Repository contains a high-resolution view of the history of the design process and is the primary collaboration tool used by the design team.

The Design Repository becomes the central repository from which multiple team members can check data in and out, all the while maintaining a complete revision history of all changes made to the design. A design is therefore stored as a series of versions of its constituent project and source documents, building a progressive picture of the intent of a designer over time. By using a version-controlled Design Repository, you have the integral assurance that no revision of a design is ever lost, allowing for safe collaboration on the same design between members of a team that can be geographically dispersed in their locations. The very nature of the version control system provides an audit trail for the design. Full accountability arises through transparency of whom changed what, in which source document, and when. The system can support multiple version-controlled Design Repositories with the link to a particular repository being established by the version control link within the project folder.

By connecting to a Design Repository you are, in effect, registering that repository with the system – telling Altium Designer of its existence as it were. Furthermore, there is no manual specification of paths to unofficial or 'rogue' repositories. Through Altium Designer, you can only interact with those VCS-based Design Repositories you have purposefully connected to the system.

Supported Version Control

Related pages: Version Control and Design Repositories, Using Version Control

The version control software – used to implement the repositories themselves – is supported in the following ways:

  • Through Altium Designer – using the software's built-in support for Subversion (SVN). Enabled for use by default, Subversion capabilities are delivered through the VCS Provider – SVN extension. This extension is installed by default, and delivers version control functionality, through the use of SharpSVN. This implementation has full support for Unicode (multi-byte) characters in file names. This, for example, allows you to add files to your SVN VCS repository that include Russian characters in their names. You are also able to hook up and use an existing Git repository, support for which is delivered through the VCS Provider – Git extension.
  • Through an Altium 365 Workspace – when you are connected to a Workspace you are provided with localized (and centralized) version control, courtesy of the Workspace's single Git-based design repository – Versioned Storage – for accommodating all of your managed design projects.
  • Through self-managed Altium Concord Pro – when you are signed into a self-managed instance of Altium Concord Pro you are provided with localized (and centralized) version control, courtesy of the server's Local Version Control Service. A new installation of self-managed Altium Concord Pro provides a single Git-based design repository – Versioned Storage – for accommodating all of your managed design projects.
If you upgraded to self-managed Altium Concord Pro from Altium NEXUS Server 1.0 (or Altium Vault 3.0), then use of SVN repositories will also be enabled, so that you can continue to use your previous (and established) design flow. In this case, you can continue to create repositories through the local Version Control service (SVN-only), or connect to external repositories (SVN or Git).
  • Through Altium NEXUS – using the software's built-in support for Subversion (SVN). Enabled for use by default, Subversion capabilities are delivered through the VCS Provider – SVN extension. This extension is installed by default, and delivers version control functionality, through the use of SharpSVN. This implementation has full support for Unicode (multi-byte) characters in file names. This, for example, allows you to add files to your SVN VCS repository that include Russian characters in their names. You are also able to hook up and use an existing Git repository, support for which is delivered through the VCS Provider – Git extension.
  • Through an Altium 365 NEXUS Workspace – when you are connected to a Workspace you are provided with localized (and centralized) version control, courtesy of the Workspace's single Git-based design repository – Versioned Storage – for accommodating all of your managed design projects.
  • Through the integral NEXUS Server – when you are signed into the NEXUS Server (an integral part of the Altium NEXUS solution) you are provided with localized (and centralized) version control, courtesy of the server's Local Version Control Service. The integral server in a newly-deployed instance of Altium NEXUS provides a single Git-based design repository – Versioned Storage – for accommodating all of your managed design projects.
If you have upgraded your NEXUS Server from Altium NEXUS Server 1.0 (or Altium Vault 3.0), then use of SVN repositories will also be enabled, so that you can continue to use your previous (and established) design flow. In this case, you can continue to create repositories through the local Version Control service (SVN-only), or connect to external repositories (SVN or Git).

Managing Design Repositories

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.
  • Browsing repositories shared for use through the local Version Control service of the managed content server to which you are actively signed in.
  • Controlling the active state of each defined repository.

The Data Management – Design Repositories page – command-central for managing VCS-based Design Repositories within Altium Designer. The image shows connection to the default Git-based repository (Versioned Storage) available when connected to an Altium 365 Workspace, or signed into a self-managed instance of Altium Concord Pro.
The Data Management – Design Repositories page – command-central for managing VCS-based Design Repositories within Altium Designer. The image shows connection to the default Git-based repository (Versioned Storage) available when connected to an Altium 365 Workspace, or signed into a self-managed instance of Altium Concord Pro.

The Data Management – Design Repositories page – command-central for managing VCS-based Design Repositories within Altium NEXUS. The image shows connection to the default Git-based repository (Versioned Storage) available when signed into the NEXUS Server (the server that is integral to your deployed Altium NEXUS solution).
The Data Management – Design Repositories page – command-central for managing VCS-based Design Repositories within Altium NEXUS. The image shows connection to the default Git-based repository (Versioned Storage) available when signed into the NEXUS Server (the server that is integral to your deployed Altium NEXUS solution).

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.
For the Git repository used for the integrated storage of managed projects – provided by your managed content server – this is named Versioned Storage.
  • 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 Repository through Altium Designer

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. Use this to give the repository a meaningful name, specify a default checkout path, and specify the location for the repository. If a folder is specified that does not currently exist, it will be created for you.

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

Creating a Repository through Altium Concord Pro – self-managed only

Related page: Altium Concord Pro – Local Version Control Service

A new installation of self-managed Altium Concord Pro provides a single Git-based design repository – Versioned Storage – for accommodating all of your managed design projects. If you have upgraded to Altium Concord Pro from Altium NEXUS Server 1.0 (or Altium Vault 3.0), then use of SVN repositories will also be enabled, so that you can continue to use your previous (and established) design flow. In this case, you can continue to create repositories through the local Version Control service (SVN-only), or connect to external repositories (SVN or Git).

Important: Note that otherwise, the  button will be grayed out, and the ability to create/add repositories is unavailable.

See additional information.

When using self-managed Altium Concord Pro as your managed content server, and if applicable, SVN repositories can be created through the server's local Version Control service, or external repositories (SVN or Git) can be connected to. Together, all repositories are centrally managed through the VCS page (Admin – VCS) of the server's browser interface.

The VCS page can only be accessed by an administrator for Concord Pro (a member of the Administrators role).

To add a Design Repository, click the  button, located at the top-right of the page. The Add Repository window will appear, use this to define the repository.

Only SVN-type repositories can be created through the local Version Control service. Existing (external) repositories can be linked to, and these can be either SVN or Git.

The properties required depend on whether you are creating a new repository using the local VCS service, or linking to an existing, external repository:

  • New – give the repository a name and a description.
  • Existing – in addition to a name and description, you need to supply the URL to the repository, and your credentials (User Name, Password) to access that repository (if required).
When creating a repository that is internal to Concord Pro, the name should start with, and can contain A-Z, a-z, or 0-9. Underscores, dashes, and spaces are allowed within the middle of the name. You can not use the following words: AUX, COM1-COM9, LPT1-LPT9, CON, NUL, and PRN. There are no naming restrictions for an external repository.

Create a new SVN-based Design Repository through Concord Pro's local Version Control service, or link to an existing repository (SVN or Git) that has been created external to the server.Create a new SVN-based Design Repository through Concord Pro's local Version Control service, or link to an existing repository (SVN or Git) that has been created external to the server.

A linked, external Design Repository is distinguished in the list of repositories by its External property being ticked ().

Design Repositories defined through Concord Pro are populated to the client automatically during sign-in, so users do not have to worry about URLs, protocols, passwords, etc. A repository is configured once, on the server, and shared with the intended users as required.

In Altium Designer, you may need to sign out of the server and sign in again, for the repository to appear on the Data Management – Design Repositories page of the Preferences dialog.

Centrally define access to your organization's Design Repositories. SVN-based repositories can be internal to the Concord Pro installation (defined using the local Version Control service), or external through use of Altium Designer's built-in SVN, or third party SVN or Git service. Access control is performed through the VCS page of Concord Pro's browser interface. When a user signs in to Concord Pro, the Design Repositories available to them will automatically be added to the Data Management – Design Repositories page of the Preferences dialog. In the image above, a user is accessing the server from a different PC, and so localhost is replaced with the name of the PC on which the server is installed (imp in this case).
Centrally define access to your organization's Design Repositories. SVN-based repositories can be internal to the Concord Pro installation (defined using the local Version Control service), or external through use of Altium Designer's built-in SVN, or third party SVN or Git service. Access control is performed through the VCS page of Concord Pro's browser interface. When a user signs in to Concord Pro, the Design Repositories available to them will automatically be added to the Data Management – Design Repositories page of the Preferences dialog. In the image above, a user is accessing the server from a different PC, and so localhost is replaced with the name of the PC on which the server is installed (imp in this case).

Creating a Repository through the Altium NEXUS Server

Related page: Altium NEXUS Server – Local Version Control Service

The integral server in a newly-deployed instance of Altium NEXUS provides a single Git-based design repository – Versioned Storage – for accommodating all of your managed design projects. If you have upgraded your server from Altium NEXUS Server 1.0 (or Altium Vault 3.0), then use of SVN repositories will also be enabled, so that you can continue to use your previous (and established) design flow. In this case, you can continue to create repositories through the local Version Control service (SVN-only), or connect to external repositories (SVN or Git).

Important: Note that otherwise, the  button will be grayed out, and the ability to create/add repositories is unavailable.

See additional information.

When using a NEXUS Server as your managed content server, and if applicable, SVN repositories can be created through the server's local Version Control service, or external repositories (SVN or Git) can be connected to. Together, all repositories are centrally managed through the VCS page (Admin – VCS) of the server's browser interface.

The VCS page can only be accessed by an administrator for the NEXUS Server (a member of the Administrators role).

To add a Design Repository, click the  button, located at the top-right of the page. The Add Repository window will appear, use this to define the repository.

Only SVN-type repositories can be created through the local Version Control service. Existing (external) repositories can be linked to, and these can be either SVN or Git.

The properties required depend on whether you are creating a new repository using the local VCS service, or linking to an existing, external repository:

  • New – give the repository a name and a description.
  • Existing – in addition to a name and description, you need to supply the URL to the repository, and your credentials (User Name, Password) to access that repository (if required).
When creating a repository that is internal to the NEXUS Server, the name should start with, and can contain A-Z, a-z, or 0-9. Underscores, dashes, and spaces are allowed within the middle of the name. You can not use the following words: AUX, COM1-COM9, LPT1-LPT9, CON, NUL, and PRN. There are no naming restrictions for an external repository.

Create a new SVN-based Design Repository through the NEXUS Server's local Version Control service, or link to an existing repository (SVN or Git) that has been created external to the NEXUS Server.Create a new SVN-based Design Repository through the NEXUS Server's local Version Control service, or link to an existing repository (SVN or Git) that has been created external to the NEXUS Server.

A linked, external Design Repository is distinguished in the list of repositories by its External property being ticked ().

Design Repositories defined through the Altium NEXUS Server are populated to the client automatically during sign-in, so users do not have to worry about URLs, protocols, passwords, etc. A repository is configured once, on the server, and shared with the intended users as required.

In Altium NEXUS, you may need to sign out of the server and sign in again, for the repository to appear on the Data Management – Design Repositories page of the Preferences dialog.

Centrally define access to your organization's Design Repositories. SVN-based repositories can be internal to the NEXUS Server installation (defined using the local Version Control service), or external through use of Altium NEXUS's built-in SVN, or third party SVN or Git service. Access control is performed through the VCS page of the NEXUS Server's browser interface. When a user signs in to the NEXUS Server, the Design Repositories available to them will automatically be added to the Data Management – Design Repositories page of the Preferences dialog. In the image above, a user is accessing the server from a different PC, and so localhost is replaced with the name of the PC on which the server is installed (sam in this case).

Connecting to an Existing SVN Repository through Altium Designer

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

Connecting to an Existing Git Repository through Altium Designer

The Data Management – Design Repositories page of the Preferences dialog offers no controls for creating a new Git repository, or connecting to an existing one. However, you can effectively connect to an existing repository of this type by other means (that are the traditional technique favored by the Git user-ship). To do so:

  1. Create your remote Git repository, or access your company's external repository – in which your Altium Designer projects are stored.
  2. Clone the repository to make your local working Git repository.
  3. Open an Altium Designer project from the local repository.

Altium Designer will recognize that the project is under version control in a Git-based repository, and provide VCS-related statuses, and commands/ functions to work with the files (including Commit (to local working Git repository) and Push (from local Git repository to remote Git repository)).

For more information, see Version Control and Design Repositories.

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.

Note that for an SVN Design Repository added through a managed content server's browser interface, only the Default Checkout Path can be modified. Any other required changes must be performed from the VCS page of the browser interface.
If you are signed in to a managed content server, the Git-based Design Repository (Versioned Storage) can also be renamed.

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 Design Repositories

Once defined, the connected nature of a VCS-based 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 connected to an Altium 365 Workspace, there is only a single design repository used – Versioned Storage. The following information, in respect of using a managed content server with multiple defined design repositories, relates to using a self-managed Concord Pro server. For more information on creating and opening a managed project in relation to a Workspace, see Altium 365 Workspace – Management of Projects from within Altium Designer.
When accessing a design repository for the first time, you will need to supply your login credentials – for example, your server login credentials for a design repository created internal to a managed content server, or login credentials for an external VCS server (e.g. for a design repository located on VisualSVN Server).

Adding a Local Project to a 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.

If you are signed in to a managed content server, the Git-based Versioned Storage repository is only used in relation to managed projects, and so will not be available from the menu.
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 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.

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 New Folder 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. Local design projects may be added to a design repository available through a managed content server in the same manner.Adding a Local design project to a local design repository. Local design projects may be added to a design repository available through a managed content server in the same manner.

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.

If you are signed in to a managed content server, the Git-based Versioned Storage repository is only used in relation to managed projects, and so will not be available from the menu.

Creating a new Version-controlled design project – all defined Design Repositories are available for use. Shown here is the situation when not signed into a managed content server.Creating a new Version-controlled design project – all defined Design Repositories are available for use. Shown here is the situation when not signed into a managed content server.

And shown here is the situation when signed into a managed content server – all of that server's Design Repositories are additionally available, with the exception of the Versioned Storage repository.

Adding a Managed Project to a Design Repository

Related page: Management of Projects

Whether creating a new managed project, or making an unmanaged project (Local or Version-controlled) available to a managed content server, the resulting project is stored in a Design Repository. As part of the respective interface used to create/make available, the repository can quickly be selected from a list of defined repositories.

To be able to create a managed project – through the Create Project dialog – or to make an unmanaged project (Local or Version-controlled) available to a server, you must be signed in to your managed content server.
To be able to create a managed project – through the Create Project dialog – or to make an unmanaged project (Local or Version-controlled) available to a server, you must be signed in to your managed content server. In addition, if at least one process definition for the Project Creations process theme is active – on the Project Creations tab of the Processes page of the NEXUS Server's browser interface – the ability to create a new managed project through the Create Project dialog is disabled. Instead, the active process definitions will be available to choose from, on the File » New » Project in <ServerName> sub-menu. The Make Project Available on Server command will also not be available. Rather the Convert to Managed Project sub-menu will display, presenting those active process definitions from which to choose. The corresponding workflow for the chosen process will then be invoked.
The Git-based Versioned Storage design repository, and any SVN-based or Git-based design repositories added through the server's local Version Control service, and which have been shared with you to use, will be listed. Note, however, that you cannot create a managed project in an external repository that is local, that is, one that is defined with path file:///.

Other Design Repositories that have been created directly through Altium Designer, on the Data Management – Design Repositories page of the Preferences dialog, will not be available for use as target repositories.

Creating a new managed design project directly within the managed content server to which you are actively signed in. Only design repositories provided by your managed content server (and that are shared with you where applicable) will be available for use.Creating a new managed design project directly within the managed content server to which you are actively signed in. Only design repositories provided by your managed content server (and that are shared with you where applicable) will be available for use.

If you are making a Version-controlled project available on the server that is already stored in a managed repository – one defined through the server's Version Control service – then this will be the repository used for the rsulting managed project. You will not be able to choose a different repository.
The newly-created/made available managed project will subsequently be available from the Projects page of the server's browser interface.

Opening a Version-controlled Project from a 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.

If you are signed in to a managed content server, the Git-based Versioned Storage repository is only used in relation to managed projects, and so will not be available from the menu.
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!

Opening a Managed Project from a Design Repository

To work on a managed project – essentially checking out as a local working copy – first ensure that you are signed into the managed content server in which the project resides. Then use the File » Open Project command. The Open Project dialog will appear. The server will appear in the Locations region of the dialog, distinguished by the  icon, and appearing with the name given to that server. Click on this entry to list the managed projects therein. Only those managed projects that have been shared with you (you have permission to access) will be listed, and from across all managed Design Repositories shared with you. Choose which managed project to open from the server and click . Once opened, the project will appear under an entry for your server, in the Projects panel.

Choose which managed project to open, from those currently shared with you.

You have the option to open the project to the default checkout path, or use the  drop down menu to specify a custom path. The default checkout path is taken from the Document Path field on the System – Default Locations page of the Preferences dialog.
If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
Note

The features available depend on your Altium product access level. Compare features included in the various levels of Altium Designer Software Subscription and functionality delivered through applications provided by the Altium 365 platform.

If you don’t see a discussed feature in your software, contact Altium Sales to find out more.

Content