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 extension | Description | Rationale |
|---|---|---|
| *.tpy | This 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 file | Artifact of the compilation process |
| *.tclrs | License response file | Unique for each target device. License files (and more generally target configuration) should be archived separately |
| *.compiled-library | Precompiled TwinCAT library project. | Should be supplied/installed separately as part of your build tool chain with the TwinCAT3 installation + user projects |
| *.compileinfo | Compilation log file for the TwinCAT project. Also usable when analyzing core dumps. | Artifact of the compilation process. |
| *.tmc | TwinCAT 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. |
| *.tmcRefac | I've seen these popping up in the projects directories sometimes. | Artifact of the compilation process |
| *.library | TwinCAT library project with attached source. | See rationale for *.compiled-library |
| *.project.~u | Temporary file | Only backup files |
| *.tsproj.bak | TwinCAT project file backup | Only backup files |
| *.xti.bak | This is a backup of the *.xti-files. | Only backup files |
| _Boot/ | The TwinCAT boot directory, containing the compiled application | Files 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
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.
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!
Cool. I’ll probably have some time during the Christmas holidays.
Are there any guidelines for an article?
No guidelines as you will be the first guest author 🙂 But drop me an e-mail through the contact form and we’ll take it from there.
*.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!
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.
I just noticed that when you create a standalone PLC project, the file extension is *.tspproj with a double p! So maybe you can also add *.tspproj.bak to the .gitignore file.
Hi,
Your .gitignore file is probably unrelated to the one found on this website?:
https://www.gitignore.io/?templates=twincat
Could cause confusion to which one is “official”.
Greetings,
Bart
Hi Bart & thanks for your message.
Neither of these two are official in the strict meaning (thus why I used quotes) as Beckhoff does not (yet) provide a default gitignore-file for Tc3 projects. The gitignore-file on the toptal repo seems to be a little outdated though, and it would make sense to update it (which seems to go much faster than GitHub’s gitignore-repo).
Hi. So I ran into two specifics while using the suggested file (Visual Studio + latest found in the github pull request for TwinCAT3.gitignore).
The first thing I noted that when using the HMI module, an extra folder “\.engineering_servers\” is added. These were automatically generated, so I assume they can be ignored.
The second is that it seems to constantly change server extension files. These are located in the
“\HmiProject\Servers\Extensions\”
Did you run into similar experiences when using git?
Hello Rudi
Regarding the HMI module – I found that its impossible to ‘git add .’ files, while the project is open in Visual Studio due to files in ‘.engineering_servers’ being used. Adding these 2 lines to .gitignore seems to solve the problem for me
# TwinCAT HMI TE2000
.engineering_servers/
“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”
Do you have any suggestions on how to set up a build tool chain for including the libraries?
Yes, this can be accomplished with a combination of the TwinCAT automation interface and Jenkins.
Hi,
thanks for the help. What a fight, to get git running.. :o) Your file helped a lot.
What about the
/.vs/[REPO-NAME]/v15/.suo ?
That is the last file that make trouble on my system.
Cheers
Jan
Hi Jan! This file should be combined with the VisualStudio.gitignore, which ignores all suo-files.
Thank you 🙂
If you use TwinCAT HMI TE2000+ I wanted to suggest the following extension in .gitignore:
# TwinCAT HMI files
.engineering_servers/
liveview_*
*.cache
*.db-shm
*.db-wal
*.pid
.hmiframework/
.hmipkgs/*-*-*-*/
tchmipublish.journal.json
This file is only for TwinCAT 3 projects, not for HMI. Maybe create a PR for TwinCAT HMI projects?
Hi!
A colleague of mine gave me a gitignore-list that his team uses and seems to be working for them. I was a little surprised that there was so many differences compared to what you have here. Do you have any comments on this? Here is ignores that they had which is not in the proposed file you have here:
*.bak
*.tszip
*.dbg
*.~u
#licence file
/IP lijst_FSOE_EtherCat.xlsx
/UpgradeLog.htm
The bak and ~u conditions are a bit more general in this one. Is there any risks to ignore too much in this case?
Regards Micael
I had an issue ignoring .tmc file while using a EL3443 module, where a datatype is generated for mapping inputs. It seems that this type is stored in the .tmc file.
Is there a workaround for this problem, or is this another exception, where you don’t want to exclude the .tmc file from source control?