Why Version Control?
If you’ve ever gone through a project archive, found something that looks like the following:
- Project_20180807
- Project_20180813
- Project_20180813_Final
- Project_20180813_FinalB
- Project_20180813_FinalFinal
- Project_20180813_Newest_I_SWEAR
…and been confused about what the most recent version of the project is, then you’ve experienced one of the many reasons to use version control systems!
From backing up code to tracking changes to concurrent multi-user development, version control systems (VCS) offer so many advantages that they should be an essential tool for any software engineer. Yet the automation industry has struggled to effectively use all the advantages that VCS offer.
Proprietary and binary file formats that are common in the automation industry prevent the full use of many VCS, which generally provide the most benefit when tracking text-based files.
Luckily, Beckhoff TwinCAT 3 stores project files and code in text-based file formats, making it a great candidate for use with version control software. This blog will discuss tips and tricks for optimizing the use of TwinCAT with version control and for development with multiple users.
I’ve also written a companion blog with an easy, step-by-step guide to setting up a TwinCAT project for use with version control, so be sure to check that out!
A couple quick disclaimers:
DMC leverages Git (specifically Gitlab) as a VCS to use with TwinCAT, but much of the information discussed in this blog will be applicable across many VCS.
This blog will discuss many of the things DMC has learned through the years that have made our lives easier. By no means is our workflow the only workflow; one of the many beauties of version control is that it is flexible – use it however works best for you, and take or leave as many of our tips as you like!
Alright, let’s get started.
Table of Contents:
- TwinCAT Project Settings
- Separating Project Components into Individual Files
- Keep Unrestored Links
- TwinCAT Version Management
- Pinning Library Effective Versions
- Standardizing Versions of TwinCAT and Add-On Modules
- Tips for using Git with TwinCAT
- Gitignore
- Merging
- General Workflow
- Conflicts
- Separating LineIDs
- Other Tips
- Further Reference
TwinCAT Project Settings
Back to Table of Contents
There are some settings you can configure when setting up your TwinCAT solution that will optimize your project for use with version control. Instructions for this setup are detailed in my companion blog Setting up a TwinCAT 3 Project for Version Control; however, I’ve included additional details here to give background on why these settings are helpful.
Separating Project Components into Individual Files
Back to Table of Contents
Many TwinCAT project components, such as hardware configuration or variable mapping, default to being grouped together into project files. In the context of version control, this means changes to these files will happen often.
The version control software will still track these changes, but it may be harder to follow the thread of changes to a specific component in the bulk project file. Furthermore, if every developer is making constant changes to the bulk project file, it increases the chances of merge conflicts and the headaches that may arise because of them.
Many of these elements can be separated out into their own individual files. Much like the creation of this article, it is DMC’s best practice to save as many elements as possible in separate files to better track and merge changes with them. Instructions for doing so can be found in Step 1 of the companion blog.
Keep Unrestored Links
Back to Table of Contents
TwinCAT automatically deletes variable links that are found to be invalid in the process image. This can cause problems when merging branches.
The process image is only updated when code is recompiled after a merge, not during the merge itself; therefore, although links might be valid after compilation occurs, they can be considered invalid just after a merge and then get deleted.
Instructions to prevent this from happening can be found in Step 2 of the Setup Blog. This step also includes a method of exporting variable mappings so that they can later be reimported if they are lost.
TwinCAT Version Management
Back to Table of Contents
Beckhoff often releases new versions of TwinCAT along with various additional modules. Sometimes this causes problems when developing on a team with multiple engineers.
- Accidental Project/Component Upgrades
Developers might work across several projects simultaneously, many of which could be on different TwinCAT versions. TwinCAT Remote Manager can be a great help in this situation – at least for PLC development – but developers with newer TwinCAT versions installed might inadvertently upgrade projects – causing problems for other developers.
Sometimes, new TwinCAT versions come with improvements to Beckhoff’s standard libraries. Generally, projects are configured to use the most recent library version by default; however, if two engineers have different most recent versions, it can prevent one of them from going online even with otherwise identical code.
- Supporting Legacy Machines
Legacy machines might use older versions of TwinCAT. In machine-down events or even less critical troubleshooting, dealing with project versioning/upgrades might eat up critical time. Some hardware may not even be compatible with upgraded versions. All around, it’s less of a headache to just have the proper versions available to get online and solve problems with these machines quickly.
The following are some actions you can take to ensure smooth support of many projects with varied TwinCAT versions by a team of multiple engineers.
Pinning Project Version
Back to Table of Contents
TwinCAT XAE Projects can be pinned to a certain version of TwinCAT. By doing this, you ensure that the Remote Manager will automatically load the proper TwinCAT build whenever you open the project (so long as that build is installed on your system).
This will prevent you from accidentally upgrading the project because you forgot to manually select the proper build in Remote Manager. Again, very helpful for a team of multiple engineers that might have many different TwinCAT versions installed on their computers.
Instructions for pinning project versions can be found in Step 3 of the Setup Blog.
Pinning Library Effective Versions
Back to Table of Contents
Libraries in TwinCAT projects are set to use the newest version available on a developer’s computer by default. This can be a problem, however, if one developer downloads to a PLC with one library version but another developer has a different library as their newest library version. The latter developer will not be able to log into the PLC without changes. At DMC we’ve encountered this problem several times when multiple developers are onsite supporting a line.
The solution to this is to pin the libraries’ versions. It generally doesn’t matter which library version is picked for each library (unless newer versions have bugfixes that are necessary), so we usually just pick the newest library version available at the time of project creation or deployment.
This can create a new problem (especially when supporting legacy machines) if some developers do not have the proper library versions available on their computers. These versions will need to be obtained and installed.
Instructions for obtaining, installing, and pinning library versions can be found in Step 4 of the Setup Blog.
Standardizing Versions of TwinCAT and Add-On Modules
Back to Table of Contents
Each of the above recommendations for keeping items in the project pinned rely on you having the proper TwinCAT/add-on module versions available on your computer in the first place.
You can generally determine the project version before opening it by opening the project file in a text editor. For example, the .tsproj file for the XAE project shows the project version at the top of the XML.
TE2000 TCHMI projects should also have version info in the .hmiproj file.
You can also determine what version of TwinCAT/add-on modules are installed through your control panel’s apps & features list.
I would definitely recommend downloading and using the most recent version of these tools from Beckhoff’s website when starting a project.
For TwinCAT, it’s generally not harmful to upgrade to the most recent minor revision of a build (ex: 4018.33 --> 4018.58) – though there are exceptions. It is not necessarily possible to upgrade between major revisions of builds (ex: 4018.33 --> 4024.22).
Beckhoff offers downloads for the TwinCAT Remote Manager of the most recent versions of major revisions for exactly this use, which is very handy.
The Remote Manager is not available for additional modules including:
- TE2000 TCHMI Engineering
- TF2000 TCHMI Runtime
- TF6100 OPC UA
- TE9000 Safety Editor
Upgrading usually works fairly well, so long as all developers install the same engineering version of each module (if applicable) on their development computers, but there may be situations (like legacy machines or multi-user projects) where upgrading is not practical or possible. For these situations, I recommend hanging onto the installers for the different components of a project and storing them in a central server or repository the whole team can access. This way developers can grab them and install them when necessary.
However, BE WARNED! You cannot install an older version of TwinCAT on a machine where a newer version is installed. If Remote Manager does not satisfy your needs, you will need to set up a new development environment with the proper build or uninstall the newer builds before you install the old one.
It is important to enforce that all developers have the same versions of the project components installed in their development environment. This will ensure the smoothest collaboration between multiple developers.
If you’d like to learn more about library/TwinCAT versioning, I’d recommend reading this excellent blog.
Tips for using Git with TwinCAT
Back to Table of Contents
DMC commonly uses Git as a VCS with TwinCAT for the many benefits Git offers for text-based version control. The following topics are by no means a thorough discussion of using Git (there are plenty of resources you can Google for that), but I’ve included some tips DMC has discovered along the way that might help you to use Git with TwinCAT.
Again, I’ll state the disclaimer: by no means are these tips the only or the best way to use Git with TwinCAT! Not even everyone here at DMC uses Git in the same way – if you’ve got suggestions or a workflow that works very well for you, we’d love to hear down in the comments!
Gitignore
Back to Table of Contents
The .gitignore file is used to tell Git which files it can ignore to prevent the repository from becoming bloated by tracking unnecessary changes. This can be very helpful with TwinCAT project folders which contain items like user-specific Visual Studio configuration files and builds that can be recompiled at will from the source code in the repository.
A basic TwinCAT 3 gitignore template created by Jakob Sagatowski has been added to Github’s gitignore collection. Of course, this is a basic template and may not cover everything you need to ignore in your project. Another good example, with more items included, is the gitignore for TcUnit, by the same creator.
The above gitignore examples include the *.tclrs file type, which holds license information. Oftentimes at DMC we store these license files in our repositories as a backup for our clients, so we opt not to include this in our gitignores. You can also remove any file types you’d like to track as you see fit from your gitignore.
After setting up a gitignore in your repository, you may still find that some temporary, user-specific, or unnecessary files are still tracked and not included in the gitignore. Feel free to add them to the gitignore file, but do so with caution. Make sure, if you’re going to add something to the gitignore, you have a good reason for doing so and know that a file doesn’t need to be tracked!
Some files in TwinCAT projects, like .xti files, might update often, even when it seems like you’ve made no changes to the project. However, some of these files also include crucial information that you don’t want to get lost (for example, IO links), so don’t ignore them unless you know you can do so without losing information.
In the event you do add a rule to your gitignore, you may find that files are still being tracked that match that rule. This is probably because these files were tracked before the change to the gitignore and need to be manually removed from tracking. Follow the instructions here to do so.
Merging
Back to Table of Contents
The ability to merge changes from different development branches into one project is one of the greatest strengths of using a VCS with TwinCAT. Other automation platforms may or may not have their own merge tools, but TwinCAT has an advantage with its plaintext file formats. This means we can leverage Git’s built-in merging functionalities to make our lives much easier.
Again, this is not an in-depth explanation of merging (which would require a much longer article), but it is just some tips and tricks DMC has found along the way.
General Workflow
Back to Table of Contents
Beckhoff recommends configuring TcProjectCompare, TwinCAT’s merge tool, to merge projects and deactivating automatic merging.
In general, DMC has not found this to be necessary. Although problems can occur, we often find that most merges done directly through Git are successful, especially when splitting the project into individual files.
Merges involving hardware linking or multiple developers making changes to the same aspects of project configuration can sometimes be more suspect. They might require a closer eye on the merge result. In general, it is good practice to ensure the project compiles properly after a merge and that changes to project configuration are preserved. But for typical changes to POUs, DUTs, and other code objects, the merging process is generally quite smooth.
If you’ve run into situations where you often find items are lost in merges or have configured TcProjectCompare as a merge tool and have some thoughts, please leave a comment below!
Conflicts
Back to Table of Contents
Inevitably during multi-user development, you will run into conflicts when two developers have edited the same piece of code. To manually resolve them, a mergetool is needed. Mergetools allow you to manually indicate which portions of conflicting code you’d like to keep.
DMC often uses VS Code as a mergetool for TwinCAT development. To configure VS Code as a mergetool, see these instructions. Of course, you can use whichever mergetool you prefer.
One common merge conflict that is specific to TwinCAT is conflicts in the “LineID” XML elements at the end of code files. POUs, DUTs, and other code objects are stored in an XML format. Sometimes, if extensive changes have been made in two separate branches to that code object, conflicts occur in these elements. Using VS Code as a mergetool, these conflicts look like this:
In this scenario, it generally doesn’t matter which change is accepted. Accept one of the two changes, then make sure to open the project/code object in TwinCAT and compile before committing the in-progress merge.
When opening the code object, TwinCAT should handle properly correcting the format of these XML elements. If there aren’t problems in the compilation, you should be good to go.
Separating LineIDs
Back to Table of Contents
Alternatively, to avoid these conflicts and LineIDs appearing in source control altogether, you can activate the Separate LineIDs option in your TwinCAT XAE environment.
LineIDs are required for breakpoint handling and to ensure code lines can be assigned to machine code instructions. But instead of storing them with the source code (as is done by default), this option separates them into a file called LineIDs.dbg - a binary file which is rebuilt when the project is modified/saved.
If you paid close attention to the aforementioned gitignore templates, you might have noticed that LineIDs.dbg can be safely ignored by source control since it is constantly being rebuilt. Comparing the same source code file generated with this setting deactivated and with it activated, we can see that the only difference is the removal of the LineIDs section - which should prevent us from tracking changes and running into merge conflicts in this section.
A word of caution - if you plan to use this setting with a multi-developer team, you'll need to make sure all developers have the same value for this setting in their development environments. Otherwise you may wreak havoc on your source control, with some developers constantly saving their files with separate LineIDs and others constantly saving their files with included LineIDs.
Instructions for setting the Separate LineIDs setting can be found in Step 5 of the Setup Blog.
Other Tips
Back to Table of Contents
It’s generally a good idea to close the project before switching branches/performing merges. TCXAE will sometimes detect if the project has been externally modified (ex: by Git), but sometimes it won’t. To make sure you’re not accidentally editing the wrong project version, close the project and re-open after you’re done performing Git operations.
Further Reference
Back to Table of Contents
For more information on version control in general and with TwinCAT, please see the following links:
If you’ve got any other suggestions for tips and tricks to use TwinCAT with version control and/or multiple users, please leave them in the comments below! DMC is always committed to improving our workflow, so we’d love to hear your thoughts.
Learn more about DMC's Beckhoff and TwinCAT 3 programming expertise and contact us for your next project.