Tutorial - Using Version Control in Altium Designer

Modied by on 6-Nov-2013
Altium Designer supports Subversion (SVN) and Concurrent Versions System (CVS). Because it has
direct support for SVN it gives access to many of the standard SVN commands, including the ability to
create a repository, commit/update les, as well as being able to access le revisions from within
Altium Designer. This works well with the schematic and PCB comparison features, making it easy to
quickly compare and identify dierences between two revisions of a schematic or two revisions of a
PCB.
If you are new to version control systems and are wondering where to start, read the article Version
Control and Altium Designer.

Enabling Version Control

To work directly from within Altium Designer to a Version Control System you must rst enable the
appropriate options:
1. Select DXP Preferences to open the Preferences dialog,
2. on the Version Control - General page, select the appropriate provider.
Choose the CVS - Concurrent Versions System option if you are using the Concurrent
Versions System version control system.
Choose the SVN - Subversion option if you are using the Subversion version control
system.

Version Control - General preferences - choosing SVN as the Version Control provider

For Subversion you will need to additionally:

1. Specify the path to the main executable, usually svn.exe. This will then allow Altium Designer to
perform most of Subversions repository actions, such as commit and update.
2. Specify the path to the admin executable, usually svnadmin.exe.This will then allow Altium
Designer to create a repository. If you already have a repository you may skip this option.
Restart Altium Designer to conrm your choice of version control system.

Note that it is necessary to have Subversion 1.5.0 or later installed in order for the SVN
commands to work correctly from Altium Designer.

The Storage Manager panel

Main Article: Storage Manager
All VCS-related actions are performed through the Storage Manager panel, you can display it by
clicking the System button at the bottom right of the workspace and choosing the Storage Manager
entry from the menu. The basic approach is to select the le(s) of interest, then choose the required
command in the right-click menu.

All VCS related tasks can be performed through the Storage Manager panel. Note that in this gure the lower region of the panel is
congured to be in Timeline view.

The Projects Panel

Main Article: Projects Panel
The current VCS status of each le that is
under version control is displayed next to
the le's name in the Projects panel. The
status is dependent on which VCS method
you are using, and it can be one of the
following:

The Project panel also shows the VCS status, right-click for more options.

SCCI
[blank] Version control disabled le has not been added to the VCS.
[blank] Not in version control - le has not been added to the VCS.
No modication - The le is checked in to the repository, and your local copy is up to date.
Depending on the provider, your local copy may be marked read-only so that it cannot be
modied until you Check Out.
Out of date- The le is checked in to the repository, but your local copy is out of date. Use
Get Latest Version to update your local copy.
Checked out exclusively by me You have checked out the le exclusively, but there are no
changes to check in. Use Undo Check Out when you are nished with the le and want to allow
other people to check it out.
Modied exclusively by me You have checked out the le exclusively and modied it. Use
Check In to check your changes into the repository or Undo Check Out to discard them.
Locked exclusively Someone else has checked out the le exclusively. You cannot check
out the le until he or she selects Undo Check Out. Depending on the provider, your local copy
may be marked read-only so that it cannot be modied.
Locked exclusively by me - You have somehow managed to check out the le exclusively

somewhere else (perhaps in another directory). Refer to the documentation for your Source
Code Control plug-in on how to remove the lock.
CVS and Subversion
[blank] Version control disabled le has not been added to the VCS.
[blank] Not in version control - le has not been added to the VCS.
No modication The le is checked in to the repository, and your local copy is up to date.
Depending on the provider, your local copy may be marked read-only so that it cannot be
modied until you Check Out.
Out of date The le is checked in to the repository, but your local copy is out of date. Use
Get Latest Version to update your local copy.
Modied the checked out le is locally modied by you. Save the le and check in / commit
the le to the repository.
Conict - the le has been committed by some one else before you had a chance to commit
this le.
Missing the le is present in the repository but not in your working folder. Use Restore
menu item from the menu by right clicking to obtain a copy from the repository in your working
folder.
You can right click and select Refresh Status to refresh the current VCS status of each le on the
Projects panel. A document that is not in the version control database will not display an icon.

Using Subversion
Before using version control, the project les must be recognized by both the VCS and Altium
Designer as being under version control. This process can be dierent for the dierent VCS methods,
so we will demonstrate how to do this with Subversion.

Creating a Repository
Subversion saves its version control information in a central repository. The repository stores
information in a hierarchy of les and directories, referred to as a le tree. If you do not already have
a repository you will need to create one.
To create a repository:
1. Display the Storage Manager panel
2. Right-click and select Create Repository
3. Specify a directory to contain the Subversion repository in the dialog shown below. Note the
Repository Type option, unless you are familiar with Berkeley databases it is recommended to
use the Native Filesystem option.

Create the SVN repository from within Altium Designer.

Adding a directory to the Repository

Subversion monitors changes to the les in a specied directory. These changes are saved in the
repository. The next step is deciding which directory you would like to monitor with Subversion.
1. Open a free le or project
2. Display the Storage Manager panel.

All VCS actions can be performed through the Storage Manager panel, via the right-click menu.

3. You will see the directory structure of the project/le that you have selected in the Folders
section of the Storage Manager panel. Select a directory. Note that Altium Designer will not
automatically monitor sub-directories, you will need to specify each directory.
4. Select Link Folder to Repository folder from the right-click menu on the Storage Manager panel.

5. This will open the SVN Link Setup dialog which will allow you to link the directory to the
Subversion repository.

Congure the working directory and the repository location.

6. Conrm the Local Directory is the directory you have selected in Step 3 and that the Path To
Repository species which Subversion repository you want to use. Then click Ok.
This directory is now being monitored by Subversion. This is indicated by the chain icon next to the
directory name in the Storage Manager Panel, as shown in the gure below.

Note the chain icon, this indicates that this directory is under version control.

Adding les to the Repository

After adding a directory to the Subversion repository, you now need to specify which les in that
directory you want to add to the repository. All les in a directory that has just been added to the
repository will initially have the status Not in version control.

With Subversion you can add les to the repository by:

1. Select a directory which has been added to the repository
2. Select one or more les in the Storage Manager. The option Only Show Files in the current
Project controls which les are displayed in the directory.
3. Select Add to Version Control command from the right mouse menu
4. Add a comment to indicate the reason for adding the les, if desired, then click Ok.

Include a comment whenever you perform important commit actions.

After you have added the les to the repository, the status of the les are changed to No
Modication, as indicated in the gure below.

The Storage Manager shows the current status of each le.

The VCS Revisions section of the Storage Manager panel has a blue arrow that shows the revision
of the le that you currently checked out.
With this version of Altium Designer, les cannot be locked exclusively when being added to the
repository with Subversion.

Updating Files in and out of the VCS

Once the project and its les have been added to the VCS you can check them out when you wish to
work on them, and then check them back into the VCS when you have completed the work. Your dayto-day work VCS practices will depend on your company's requirements, and to some extent the
approach of the VCS. For example, if your VCS favors the lock-modify-unlock model, such as
Microsoft's Visual SourceSafe, then your company policy might be that you should always check your
work in at the end of the day so that the le is made available to others. On the other hand if you are
using CVS or SVN, which are built around the philosophy of multiple check-outs (the unreserved
check-out model), then your company policy might be that you can keep design les checked-out in
your working folder, and are only required to check-in at major le update points.

Updating a le from the Repository

When using the CVS or Subversion VCS systems you right-click on the selected le(s) and use
the Update command to "check out" a working copy of the le from the repository. You can
also use the Update command to ensure that your working copy includes any modications
made by other users who are working with the le.
When using an SCC interface-compliant version control system, check-out a le by right-clicking
on the le name in the Storage Manager panel and selecting Check Out from the context
menu.
The VCS keeps track of what is in the repository compared to what exists in your working folder, so
when you check-out a le the VCS copies the latest revision of the le from the repository to your
working folder (nothing will happen if they are the same revision). Altium Designer supports this
further, by disabling the Update command in the Storage Manager when the le in the repository is
identical to your working copy.
If the le was open in the Altium Designer environment when you executed the Update command
you should close and reopen the le in order to display and work on the checked-out version of the
le.

The Update Status

After updating a le its VCS status is shown in the Storage Manager panel as No Modication. This
indicates that the repository and working versions of the le are the same. The gure below shows
the status after updating the project les when using CVS or Subversion version control systems.

VCS le status for Subversion

The gure below shows the check-out status for various project les with SourceSafe as the VCS.
Since SourceSafe uses the lock-modify-unlock model then the le can be checked out exclusively, or

just checked out.

VCS le status for SourceSafe

For the le that is checked out exclusively, another designer will not be able to check-out this le. The
VCS will have a mechanism to allow them to get a copy of the le, but the only person that can checkin an updated version of the le is the designer that checked it out exclusively. With this version of
Altium Designer, les cannot be locked exclusively when being added to the repository with
Subversion.

Committing les into the Repository

When you have nished working on a le, you need to check it back in to the VCS. This process will
copy the le from your working folder back into the repository, incrementing the revision number.
Note that if the le you want to commit is active (open), it should be saved prior to committing, or
else the last saved version of the le will be checked in to the VCS and not the open le.
To commit the le(s):
1. Right-click on one ore more les you want to commit in the Storage Manager panel and select
Commit.
If you are using CVS or SVN you will not be allowed to perform a Commit if someone else has
committed an update since you checked out your copy of the le. In this case you will be required to
perform an Update rst. In CVS and SVN language, an Update is the act of applying changes that exist
in the repository copy to your working version of the le, once this is done you will be permitted to
Commit the le. Since it is not possible to apply the changes from the repository copy of the le onto
your copy of the le (because they schematic/PCB les are binary les), the result of an Update will
be that CVS/SVN will check-out a copy of the le to your working folder, with a hash (#) character at
the start of the lename. Use the dierence feature described in the following section to identify any
dierences and help you decide how the dierences should be resolved.

Showing Dierences Between Versions

Probably one of the most often used features in a VCS is the comparison, or dierence checking tool.
Typically the VCS will include an ASCII di tool, and there are also excellent 3 rd party ASCII di tools
available. As well as being able to compare ASCII les, Altium Designer also includes physical
compare tools for schematic les, and for PCB les. You can use this capability to show changes such
as a schematic component being moved, or the path of a route being altered.

Use the Dierence capabilities to quickly identify changes in your schematic and PCB design les

If you are using CVS or SVN as your version control system you can perform a compare directly in the
VCS Revisions section of the Storage Manager panel. To do this:
1. Ctrl+click to select each of the 2 revisions,
2. right-click and select Compare from the context menu,
3. the 2 les will be opened side-by-side, compared, and all dierences will be listed in the
Dierences panel,
4. double-click on an entry in the Dierences panel to examine it on the actual schematic or PCB.
Since the SCC software interface does not support passing a list of revisions to Altium Designer, for
any other version control system you will need to:
1.
2.
3.
4.
5.
6.
7.

manually check-out the revisions of the les you want to compare,

open them both in Altium Designer,
select Show Physical Dierences from the Projects menu,
enable the Advanced mode in the Choose Documents to Compare dialog,
select 1 document in the left list and 1 in the right list, and click OK,
the 2 les will be compared and all dierences will be listed in the Dierences panel,
double-click on an entry in the Dierences panel to examine it on the actual schematics or PCBs
(To view them side-by-side, right click on the document tab and select Split Vertical).

Removing les from the VCS

Some VCS systems allow you to remove directories/projects. By removing a directory/project from the
VCS, means it will no longer be associated with version control and the link between Altium Designer
and the VCS software will be removed. Removing the directory/project alone does not remove all
associated project les from your VCS however. They will appear again if the project is added back
into the VCS and a refresh is carried out to resynchronize the system (right-click on the project le
entry in the Storage Manager panel and choose the Refresh Status command). You will need to use
the VCS interface to permanently remove project les from the repository.

Removing a le from the VCS

To remove the selected les from your VCS:
1. Right-click on one or more les that you want to remove in the Storage Manager panel and
select Remove from Version Control.
2. The status for the removed le will change to an empty box [Not in version control] in the
Projects panel.

Removing a directory from the VCS

Directories cannot be removed from the VCS repository from within Altium Designer at this stage.

Refreshing the Status

Should you wish to make sure the status of your les is up to date, use the Refresh Status
command. This command can be used at any time, but is especially useful when you have performed
an action, such as checking in or out, directly in the VCS software.
1. Right-click on the project lename in the Files section of the Storage Manager panel and select
Refresh Status.
2. The link between the active project in Altium Designer and the project that resides in the VCS is
checked, and the status of the project and its related les is refreshed.
The corresponding status is updated both in the Storage Manager panel and in the right-hand box
next to each le's name in the Projects panel providing the Show VCS status option is enabled in
the associated options for the panel. Access these options on the System Projects Panel page of the
Preferences dialog (DXPPreferences). You can also use the F5 key on the Storage Manager panel
to refresh the VCS status.

Showing a File's VCS history

You can view the history of a le that is under version control. If you are using the CVS or Subversion
version control systems, the history of the selected le is shown directly in the VCS Revisions, or Time
line section of the Storage Manager panel (depending on which View you have opted for in the rightclick menu). To review any revision:
1. Select the le, then choose Open from the right-click menu. This will open the le in Altium
Designer.
If you are using a SCCI version control system, to view the history:
1. Right-click on the le whose VCS history you want in the Storage Manager panel and select
Show History.
2. Login to the VCS if required.
3. Depending on the VCS software, you may get a History Option dialog prior to seeing the history
of the le, such as the one shown below. Click OK and the history of the selected le inside the
VCS will be shown.

Click OK in the History Options dialog to select the revisions of interest from a list

The information shown will depend on the version control software you are using. Consult your VCS
software documentation for more information on these dialogs.

See Also
Version Control and Altium Designer
Version Control Terminology

References
SVN community website http://subversion.tigris.org/
SVN online manual http://svnbook.red-bean.com/
CVS community website https://www.cvshome.org/
CVS installation tips http://www.cvsnt.org/wiki/InstallationTips
CVS manual (known as the Cederqvist, after the author) https://www.cvshome.org/docs/manual/
Using and administering CVS http://cvsbook.red-bean.com/cvsbook.html
Alternate CVS download site http://www.cvsnt.com

Source URL:
http://techdocs.altium.com/display/ADOH/Tutorial+-+Using+Version+Control+in+Altium+Designer#comment-0