.gitignore for TwinCAT

Doing version control is a natural part of any software engineers daily work. Doing version control for PLC software has historically mostly been hard, if not impossible. As many automation manufacturers store all software in binary blobs it has not been suitable for version control. Sometimes there have been proprietary solutions available, but it’s not until recently that a shift has started where source code is stored in plain text. For version control, Git has gained more and more popularity for over a decade.

From the perspective of TwinCAT and doing version control, there is nothing special about Git. Git is just one of many version control systems (VCS) out there. It’s created by this cool guy Linus Torvalds, who thought that the other version control software out there had their flaws. Doing version control with TwinCAT software there are many flavors, which of Git is one.

What all VCS have in common (other than doing, well, version control) is a way to specifically define which files should be untracked. How this is actually implemented differs in the different VCSs, but in git this is defined by a .gitignore-file, which is placed at the root of the project location which is to be tracked. Each line in this file specifies a pattern, which git uses to decide whether to ignore a specific path. This is necessary to avoid cluttering the VCS down with unnecessary files, which just take up space and make for unnecessary commits. Including a .gitignore-file is one of the items a TwinCAT developer doing version control should do.

TwinCAT3, just as most integrated development environments, produces software artifacts that you normally don’t want to include in version control. But which files should we have version control of, and which should we skip? Beckhoff have a PDF to provide some of the answers, unfortunately it’s quite outdated and not complete. More recently, new additions have been made to the documentation regarding the different file types within a TwinCAT project. With this information and some experimenting, we can make a up-to-date gitignore file for TwinCAT.

File extensionDescriptionRationale
*.tpyThis file contains located PLC variables and their addresses as well as generic project information. This file is a relic from TwinCAT2, although it can still be generated from a TwinCAT3 project (which needs to be explicitly configured). The replacement in TwinCAT3 is the *.tmc fileArtifact of the compilation process
*.tclrsLicense response fileUnique for each target device. License files (and more generally target configuration) should be archived separately
*.compiled-libraryPrecompiled TwinCAT library project.Should be supplied/installed separately as part of your build tool chain with the TwinCAT3 installation + user projects
*.compileinfoCompilation log file for the TwinCAT project. Also usable when analyzing core dumps.Artifact of the compilation process.
*.tmcTwinCAT Module Class. TwinCAT3 corresponding file to the TwinCAT2 tpy-file. Artifact of the (PLC project) compilation process. Don't include this rule if:
1. You've got TwinCAT C++ projects, as the information in the TMC-file is created manually for the C++ projects.
2. You've created a standalone PLC-project and added events to it, as these are stored in the TMC-file.
*.tmcRefacI've seen these popping up in the projects directories sometimes. Artifact of the compilation process
*.libraryTwinCAT library project with attached source.See rationale for *.compiled-library
*.project.~uTemporary fileOnly backup files
*.tsproj.bakTwinCAT project file backupOnly backup files
*.xti.bakThis is a backup of the *.xti-files.Only backup files
_Boot/The TwinCAT boot directory, containing the compiled applicationFiles used for the target/PLC
_CompileInfo/Directory containing the compileinfo-files.Artifact of the compilation process
_Libraries/Directory containing all libraries that the project depends of.The libraries (*.compiled-library and *.library) are supposed to be supplied separately as part of your build tool chain with the TwinCAT3 installation + user projects, from which this folder will be created

GitHub, worlds largest open source software repository, holds an excellent gitignore repository, with default gitignore files for various types of projects/IDE’s. I’ve submitted a pull request to GitHub to include a gitignore for TwinCAT3 projects in this “official” gitignore repository, so that the TwinCAT community can use it. It’s not been approved yet (and the developers at GitHub do not seem to be in a hurry), but until it’s been approved it can be accessed from the pull request.

The entries in the gitignore-file for TwinCAT3 are all specific for TwinCAT (possibly with the entry *.project.~u being the exception). However, as TwinCAT is integrated with Visual Studio it makes sense to also ignore the various files which should not be version controlled. GitHub hosts an excellent gitignore-file for this purpose. In your TwinCAT projects I recommend you to merge the TwinCAT3 gitignore-file with this VisualStudio gitignore into one common file, with one example being the gitignore-file for the TcUnit unit testing framework.

Full color Git logo for light backgrounds by Jason Long from https://git-scm.com/downloads/logos

  • Share on:

4 Comments, RSS

  1. Roald Ruiter 2019-12-03 @ 08:42

    There is a specific situation where TMC files can’t be ignored. When you use a stand alone PLC project _and_ added custom events to the event logger the custom events are only saved in the TMC file. So if you add a new event to your custom event class and don’t commit the TMC file, your colleague will not see the new event.

    If you don’t have a stand alone PLC project, the events are stored in the tsproj file and you don’t run into this issue. I’ve discussed this issue with the Beckhoff support and they are aware and will hopefully fix this in the future.

    On a side note, maybe it would be good to publish an article on the stand alone PLC projects (https://infosys.beckhoff.de/english.php?content=../content/1033/tc3_plc_intro/4702071179.html&id=135948604315208321). They are a relatively new option since TwinCAT 3.1.4022 and can be a real lifesaver. We’ve had the issue that several times some settings of our development machine were uploaded on the production machine and caused major issues. Ever since we use the stand alone PLC projects, this has not been an issue anymore.

    Also the TwinCAT 3 event logger can be really useful: https://download.beckhoff.com/download/Document/automation/twincat3/TC3_EventLogger_EN.pdf.

    There is not much info online on stand alone PLC projects/event logger, besides the official Beckhoff documentation. Do you have any experience with them? If not I can write up an article about it if you like and publish it here as a guest author.

    • Jakob Sagatowski 2019-12-05 @ 11:44

      Hi Roald! I’ve been using the standalone PLC projects, and the events as well, but never combined! This is a great catch from your side! I’ve clarified this post and updated the gitignore-file template at GitHub with this clarification.
      You are more than welcome to write about the standalone PLC projects/event logger as a guest author!

  2. David Hopkins 2019-12-05 @ 10:07

    *.tmc files in PLC projects should be ignored, but *.tmc files in TcCOM C++ projects definitely should not be ignored!

    The TMC file describes the interface of a TcCOM module. For PLC projects this is automatically generated from the data types and POUs contained in the PLC. So if you delete it, the compiler can create it again. (However it is possible to make manual customisations which might be lost if you don’t version control the file. Best advice here is to probably try to avoid customising a PLC TMC!)

    On the other hand, for TcCOM C++ projects, the TcCOM interface information is hand-crafted using the TMC editor to define object-oriented interfaces, method signatures, data types, etc. The contents of the TMC can then be used to code-generate scaffolding for the C++ classes (interface implementations, etc). If you delete the TMC file you will have recreate all of its contents by hand!

    So for PLC projects, *.tmc is an *output* of the compiler. For TcCOM projects, *.tmc is an input to the compiler. Ignoring all *.tmc can be a nasty trap!

    • Jakob Sagatowski 2019-12-05 @ 11:45

      Thanks for this invaluable response David! I don’t have so much experience with the C++ modules of TwinCAT so I had no idea about this. I’ve clarified this post with your information and updated the gitignore-file at the PR/GitHub as well.

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.