Manual

Source Control

TwinCAT 3

Version: 1.1
Date: 2016-11-10
 Table of Contents

Table of Contents
1 Foreword .................................................................................................................................................... 4
1.1 Notes on the documentation............................................................................................................. 4
1.2 Safety instructions ............................................................................................................................ 5

2 Integration of the Source Control Management ..................................................................................... 6

2.1 Project Files ...................................................................................................................................... 6
2.2 Project settings ................................................................................................................................. 7
2.3 Best Practice..................................................................................................................................... 9

3 Configuration of the source control client............................................................................................ 10

3.1 Selection of the Compare Tool ....................................................................................................... 11

4 Project Compare Tool ............................................................................................................................. 13

4.1 Using the TcProjectCompare tool................................................................................................... 13
4.2 Configuration of the TcProjectCompare ......................................................................................... 18
4.3 Further options................................................................................................................................ 19

Source Control Version: 1.1 3

Foreword

1 Foreword

1.1 Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who
are familiar with the applicable national standards.
It is essential that the documentation and the following notes and explanations are followed when installing
and commissioning the components.
It is the duty of the technical personnel to use the documentation published at the respective time of each
installation and commissioning.

The responsible staff must ensure that the application or use of the products described satisfy all the
requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer
The documentation has been prepared with care. The products described are, however, constantly under
development.
We reserve the right to revise and change the documentation at any time and without prior announcement.
No claims for the modification of products that have already been supplied may be made on the basis of the
data, diagrams and descriptions in this documentation.

Trademarks
Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE®, XFC® and XTS® are registered
trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own
purposes could violate the rights of the owners.

Patent Pending
The EtherCAT Technology is covered, including but not limited to the following patent applications and
patents:
EP1590927, EP1789857, DE102004044764, DE102007017835
with corresponding applications or registrations in various other countries.

The TwinCAT Technology is covered, including but not limited to the following patent applications and
patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

EtherCAT® is registered trademark and patented technology, licensed by Beckhoff Automation GmbH,
Germany

Copyright
© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to
others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a
patent, utility model or design.

4 Version: 1.1 Source Control

 Foreword

1.2 Safety instructions

Safety regulations
Please note the following safety instructions and explanations!
Product-specific safety instructions can be found on following pages or in the areas mounting, wiring,
commissioning etc.

Exclusion of liability
All the components are supplied in particular hardware and software configurations appropriate for the
application. Modifications to hardware or software configurations other than those described in the
documentation are not permitted, and nullify the liability of Beckhoff Automation GmbH & Co. KG.

Personnel qualification
This description is only intended for trained specialists in control, automation and drive engineering who are
familiar with the applicable national standards.

Description of symbols
In this documentation the following symbols are used with an accompanying safety instruction or note. The
safety instructions must be read carefully and followed without fail!

Serious risk of injury!

Failure to follow the safety instructions associated with this symbol directly endangers the
life and health of persons.
DANGER

Risk of injury!
Failure to follow the safety instructions associated with this symbol endangers the life and
health of persons.
WARNING

Personal injuries!
Failure to follow the safety instructions associated with this symbol can lead to injuries to
persons.
CAUTION

Damage to the environment or devices

Failure to follow the instructions associated with this symbol can lead to damage to the en-
vironment or equipment.
Attention

Tip or pointer
This symbol indicates information that contributes to better understanding.

Note

Source Control Version: 1.1 5

Integration of the Source Control Management

2 Integration of the Source Control Management

TwinCAT 3 uses the Visual Studio Framework as basis of the workbench. One of the advantages of this
concept is the simple access to the large selection of programming functions in Visual Studio.

Accordingly, TwinCAT also profits from the Source Control Management in Visual Studio.

This section describes how you can use this feature in TwinCAT 3.

2.1 Project Files

So that a TwinCAT project is compatible with Source Control Management systems and supports work in
teams, it is stored in several files. The following file extensions exist in the TwinCAT project:

File extension Source Con- Merging permissible Description

trol Manage-
ment
*.tsproj yes yes, use TwinCAT Project TwinCAT project file
Compare
*.plcproj yes yes, use TwinCAT Project TwinCAT PLC project file
Compare
*.tmc yes not permissible for PLC TwinCAT module class (description file for a
projects TcCom module)
*.tpy no - This file serves only for compatibility with
programs from other vendors.
*.xti yes yes, use TwinCAT Project In case of multiple file support, parts of the
Compare TwinCAT project file are stored with this
extension.
*.TcTTO yes yes, use TwinCAT Project PLC task object
Compare
*.TcPOU yes yes, use TwinCAT Project PLC program organizational unit (POU)
Compare
*.TcDUT yes yes, use TwinCAT Project PLC data type
Compare
*.TcGVL yes yes, use TwinCAT Project PLC global variable list
Compare
*.TcVis yes Not currently supported PLC visualization
*.TcVMO yes Not currently supported PLC visualization manager
*.TcGTLO yes yes, use TwinCAT Project PLC global texts list
Compare
*.sln no - This file is the solution file from Visual Studio
(VS). It contains, among other data, a tag
indicating the VS version used. If this is checked
in, it makes working with different VS versions
more difficult.
*.suo no This is the user options file for the VS project. It
contains information on the selected platform,
breakpoints, etc. and is user-specific. It is
generated when a project is opened on a
computer for the first time.

NOTE! The description of the process image of a TcCom module is stored in the *.tmc file. If this is
to be available directly after the checkout (fetching) of a project, even if the project had not
previously been translated on one’s own computer, then the TMC file must be fetched with it (and

6 Version: 1.1 Source Control

 Integration of the Source Control Management

thus checked in with the project beforehand). The TMC file is automatically re-generated after
translating a PLC project. It is therefore NOT merged for PLC projects and from TwinCAT 3.1 version
4018 also no longer needs to be under Source Control administration!

NOTE! Manual merging of the files of a TwinCAT project is not generally recommended. The
TwinCAT Compare Tool should be always used for this!

2.2 Project settings

So that a TwinCAT project that is managed using a source code management system can be processed in a
team as independently as possible, various settings can be set. These are described below.

Independent Project File

It is possible in TwinCAT to save individual sub-projects, NC axes or IO devices explicitly in separate files.
These files then contain all the parameters, etc. of the respective TwinCAT object, so that the complete
project file does not have to be "checked out" when making changes to this object. The links of a PLC
project, for example, are thus no longer stored in the TwinCAT project file, but in the corresponding XTI file
of the PLC project.

So that this function can be used in TwinCAT it must be "globally" enabled once. This is done via the
TwinCAT – XAE Environment - File settings category in the TwinCAT engineering environment options.

The "Enable multiple files" option enables the use of this function for new projects. The options below it
define the elements in a new project for which this function is switched on by default.

NOTE! Changes to these options only become effective after restarting the development
environment!

Use of Independent Project Files in a project

If this option is not activated by default for a TwinCAT object, it can be done manually (or the option can be
reset) via the option "Independent Project File" in the context menu of the TwinCAT object.

Source Control Version: 1.1 7

Integration of the Source Control Management

Objects that are saved as Independent Project Files are marked in the TwinCAT tree with the aid of an
overlay icon in the form of a small floppy disk. A black floppy disk indicates that there are no unsaved
changes yet for this object, whereas this is the case with a red floppy disk.

8 Version: 1.1 Source Control

 Integration of the Source Control Management

Keep unrestored Links

Unless set differently, TwinCAT tries to avoid unnecessary loads on the project repository by no longer
storing information that is no longer required. In association with this, TwinCAT also checks whether links are
still valid. Any invalid links found are automatically deleted. This mechanism is obstructive when merging
projects, since only the code and the links can be merged, but the updated process image is only available
after recompiling the code that has now been merged. It is thus possible for the link information to be newer
than the process image and the automatic optimization function would delete all links to the new variables in
the process image. With the option "Keep unrestored links", the link information marked for deletion is
retained and automatically restored as soon as the variables show up in the process image.

2.3 Best Practice

The following points should be borne in mind when using TwinCAT 3.1 in co-operation with Source Control
Systems:
• Both the TwinCAT project tree view and the PLC project tree view contain TwinCAT objects whose
information is stored in separate files (i.e. not directly in the respective project file). These elements are
marked by a small floppy disk in the tree icon. Their contents therefore cannot be accessed in the case
of merging the respective project file (files with the extensions *.tsproj and *.plcproj). It is therefore only
possible, for example, to add a POU to a PLC project, but the changes inside a POU cannot be
accessed. The background to this is that the Source Control Clients do not “look inside” the files that
they check out for merging and then also automatically load all the dependencies listed inside them
from the Source Control System.
• Since TwinCAT objects in the project files are clearly identified with a GUID, it is always necessary to
confirm the deletion of an object with a “checkin”. For this reason the deletion of an object and the
creation of a new object with the same name and the same contents is always a change!
• Some objects in the TwinCAT tree require that they are also loaded in the background in order to
display them in the tree. Thus all methods, actions, etc. of a POU are also stored in it. For this reason it
is a good idea to close a project in TwinCAT first before fetching it again from the Source Control
System.

Source Control Version: 1.1 9

Configuration of the source control client

3 Configuration of the source control client

Selection of the Source Control Clients
1. select Tools -> Options menu in the Microsoft Visual Studio Shell

ð The dialogue window shows all the settings for the Microsoft Visual Studio Shell environment.
2. Select "Source Control"

Further settings may be required depending on the selected Source Control Management System. They
ensure that the Project Compare is called for comparing TwinCAT projects. These settings are generated
automatically from the TwinCAT Project Compare for clients of the Visual Studio Team Foundation Server
and the AnkhSVN client for subversion.

10 Version: 1.1 Source Control

 Configuration of the source control client

3.1 Selection of the Compare Tool

Following the selection of the Source Control Client to be used in the project, the client must also be
configured so that the TwinCAT Project Compare Tool is used to compare and merge TwinCAT files. The
configuration of the individual clients can significantly differ.

Whereas clients such as TFS or PlasticsSCM allow different Compare Tools to be defined for the various
types of file, there are also clients that only permit a general Compare Tool to be set (e.g. AnkhSVN).
Beyond that, Source Control Systems such as GIT also allow a distinction to be made between local (project
settings) and global settings.

For the source control clients used most frequently with TwinCAT (TFS, GIT and AnkhSVN), the
configuration of the Compare tool can be automated from the TwinCAT project Compare-Tool.

Since not all features of the different clients can be discussed here, please refer to section TwinCAT Project
Compare tool transfer parameters [} 13] of the Project Compare tool for further details.

NOTE! Note: Some clients only allow a general compare/merge tool for all file extensions. For this
reason the TwinCAT Project Compare tool offers the option to define further compare tools for special
file extensions (see Configuration of the TcProjectCompare [} 18]).

Configuration of the TcProjectCompare

In order to call the TwinCAT Project Compare Tool from the TwinCAT development environment, the
selected Source Control Plugins must be configured accordingly in Visual Studio.

Setting TwinCAT Project Compare as standard tool for "Compare and Merge" functions for subversion
AnkhSVN, Microsoft Team Foundation Server or GIT clients:
1. open TwinCAT Compare
2. select the Tools -> "Configure User Tools..." menu

3. in the following dialogue, select a standard tool "Merge". This is used for all areas outside of the PLC
(e.g. for the comparison of configurations for tasks).
4. Click on "Export configuration"

Source Control Version: 1.1 11

Configuration of the source control client

5. If the required Source Control Plugin has already been selected in Visual Studio Shell, you can export
the configuration for this plugin if you are using a Microsoft Team Foundation Server or an AnkhSVN
Client.

12 Version: 1.1 Source Control

 Project Compare Tool

4 Project Compare Tool

The TwinCAT Project Compare tool is an application program, which can be used for comparing or merging
TwinCAT projects. The tool can be integrated in Visual Studio or used in stand-alone mode. If the source
control client is configured accordingly, the tool may be called automatically for compare or merge. Further
information on the configuration of Source Control Management clients can be found under Configuration of
Project Compare [} 18].

4.1 Using the TcProjectCompare tool

TwinCAT Project Compare tool transfer parameters
Since not all special features of the various clients can be dealt with here, the transfer parameters of the
TwinCAT Project Compare Tools are briefly described below:

Transfer parameters for TwinCAT version 4020 or higher:

/filel File path, left side

/filer File path, right side
/filem File path for the merged file
/dl Display name, left side
/dr Display name, right side
/sc Call via source control client

Transfer parameters for TwinCAT versions 4018 or lower:

File path, left side

File path, right side
File path of merged file
/dl Display name, left side
/dr Display name, right side
/sc Call via source control client

In Project Compare tool version or lower 4018 the file paths for the left, right and merged file were
determined based on the order in which they are called. The order was always left, right, merged file.

Samples:

Compare (Compare/Diff):

Version 4018 for PlasticSCM:

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe
"@destinationfile" "@sourcefile" /sc

Version 4018 for TFS:

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe %2 %1 /dl %7 /dr

%6 /sc

Version 4020 for TFS:

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe /filel %2 /filer

%1 /dl %7 /dr %6 /sc

Merge:

Version 4018 for PlasticSCM:

Source Control Version: 1.1 13

Project Compare Tool

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe /dl
"@destinationsymbolic" /dr "@sourcesymbolic" "@destinationfile" "@sourcefile"
"@output" /sc

Version 4018 for TFS

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe %2 %1 %4 /dl
%7 /dr %6 /sc

Version 4020 for TFS

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe /filel %2 /filer

%1 /filem %4 /dl %7 /dr %6 /sc

Starting the Project Compare tool via the command line

The handover/command line parameters of the Project Compare tool are available in the transfer parameters
section of the TwinCAT Project Compare tool:

Sample: A call of the Compare tool version 4020 or higher via the command line has the following structure:

C:\TwinCAT\3.1\Components\TcProjectCompare\TcProjectCompare.exe /filel <Datei

linke Seite> filer <Datei rechte Seite>

Using the Compare tool after starting the exe file:

Note: If encryption is used in the TwinCAT project, you can only use the TcProjectCompare version that is
integrated in Visual Studio (see Starting the TcProjectCompare plugin in Visual Studio [} 16]).

The following dialog appears after starting the TCProjectCompare tool:

With this dialogue you can select the two TwinCAT projects that are to be compared. The right-hand project
is the original project, the left-hand project is the project to be compared.

14 Version: 1.1 Source Control

 Project Compare Tool

In order to display the changes in a TwinCAT object (e.g. a POU), open the comparison for this element with
a double click.

Source Control Version: 1.1 15

Project Compare Tool

Starting the TcProjectCompare plugin in Visual Studio

To start TcProjectCompares in Visual Studio please select the menu item View -> Other windows ->
TcProjectCompare.

16 Version: 1.1 Source Control

 Project Compare Tool

XML comparison of TwinCAT objects

All TwinCAT files are stored as XML files on the hard disk. It may be helpful to not use the graphical editors
for a comparison. For this reason it is possible to carry out a comparison in the integrated XML Diff view.

To this end open the context menu of the TwinCAT object (right-click) and select the option "Compare in
Xml-Diff".

Source Control Version: 1.1 17

Project Compare Tool

4.2 Configuration of the TcProjectCompare

Some clients only allow a general compare/merge tool for all file extensions. For this reason the TwinCAT
Project Compare tool offers the option to define further compare tools for special file extensions.

Setting an external compare tool for file extensions:

1. Open TwinCAT Compare
2. Select the Tools -> "Configure User Tools..." menu

18 Version: 1.1 Source Control

 Project Compare Tool

3. Click on "Add"

4. In the following dialog describe which file extension is used, which tool is to be called (Command line)
and which transfer parameters are required for compare or merge. Confirm the settings with OK.

4.3 Further options

Further options for adapting the TcProjectCompare tool to your specific requirements are available under
Tools -> Options. These options are described below.

General tab
General settings for the TcProjectCompare tool can be found under the General tab.

Under "Automatic reload after modification" you can specify whether the file/project should be reloaded after
a change.

Under "LogFile" you can activate logging for the TcProjectCompare tool.

Source Control Version: 1.1 19

Project Compare Tool

Source Control tab

Under “Merge into” you can specify whether the local file or the server file is to be used for merging. Since
TcProjectCompare can only merge from right to left, this option is used to specify the direction in which the
files are displayed in TcProjectCompare.

Under "Visual Studio Integration" you can specify whether TcProjectCompare is to be used in stand-alone
mode or integrated in Visual Studio. The latter option is only available from TwinCAT version 3.1 build 4020
or higher.

20 Version: 1.1 Source Control

 Project Compare Tool

Project tab
Under “Expansion" you can specify whether the whole tree is expanded or only the parts containing
modifications when a project file is opened.

Under "Search" you can specify whether search queries within the TcProjectCompare tool apply only to the
modified elements or all elements.

PLC tab
Under this tab you can specify whether spaces or comments should be ignored when PLC POUs are
compared.

Source Control Version: 1.1 21

Project Compare Tool

XML tab
Under "Expansion" you can specify whether the whole tree is expanded or only the parts containing
modifications when an XML file is opened.

Under "Search" you can specify whether search queries within the TcProjectCompare tool apply only to the
modified elements or all elements, and whether the search should also include the values or comments of
the XML elements.

22 Version: 1.1 Source Control