Part 13 - Version control (using Git)
Video: https://youtu.be/1g6eYnlzKtA
#PLC #TwinCAT3 #Beckhoff #IEC_61131-3 #Git #GitHub #Version_Control #Industrial_Automation
Table of Contents:
A) Objectives
Hey developers! We are now entering a new chapter in our journey of PLC programming in TwinCAT 3.
As we now will start the advanced series of this tutorial. Let me start by saying that even though the subject of this part is in the advanced part, it doesn't mean it should only be done by experts. Actually it's not even advanced.
The subject of today is version control. Version control is the practice of tracking and managing changes to software code.
Version control systems are software tools that help software teams manage changes to source code over time.
Doing version control is something that should be done by every single automation engineer. Not doing version control is unprofessional, no matter the project size.
The question is not whether to use version control but which version control system to use.
This part of the tutorial was one of the trickiest of all to create, as I felt it was hard to decide what I should focus on.
I've decided that in this part of the tutorial I will only give a brief introduction to version control and focus more on the specifics for TwinCAT 3.
Let's get started!
B) Introduction to Version Control
B.1) What happens when we don't use a VCS?
Historically and unfortunately still the traditional way to do revision of PLC software in the industry, is to have a folder with your program and name it something like this example "PackMachine_Version_0.8".
A little bit later someone makes a change to the project, but still wants to keep the old version just in case.
What could happen here is that the PLC software developer makes a copy of the entire folder and renames the new version to something like this.
Then a few weeks later the project decides to do a release of the software and the developer, or developers, create another copy, this time indicating that it is an release version.
Shortly after release, bugs are found and this is where it starts to get funny.
Now another copy of the project is created indicating that it's just a minor fix,
and this quickly spirals out of control...
Eventually the developers end up with a bunch of folders and most likely they will stop keeping track of what is installed on the machine.
And what if there is more than one developer on the project and code needs to be shared or code is to be maintained by someone else down the road?
I've seen this numerous times where there in best case is a shared folder on some shared resource, that all developers have access to. But more commonly the project is zipped and shared among developers.
While this method can work, it is inefficient as many near identical copies of the program have to be maintained.
This requires a lot of self-discipline on the part of developers and often leads to mistakes.
Stop this madness and start to use a system that handles this for you!
B.2) How can VCS help us?
A version control system does this and much more for you, and infinitely more efficient With a version control system you get software tools that help software teams to manage change over time.
Although this picture gives the impression that the version control systems are centrally handled, this is not always the case as we will soon discuss.
So, what are the benefits of using a version control system?
B.2.1) Long-Term Change History
First, a complete long-term change history of every file. This includes all changes made by every individual over the years. Changes include the creation and deletion of files as well as edits to their contents.
This history also includes the author, date and written notes on the purpose of each change.
Having the complete history enables going back to previous versions to help in root cause analysis for bugs, and it is crucial when needing to fix problems in older versions of software.
B.2.2) Branching and Merging
Branching and merging: It's not just about having team members working on a project at the same time but it's also beneficial for individuals working on their own in different branches of changes.
Creating a branch in a version control system tool keeps multiple streams of work independent from each other, while also providing the facility to merge that work back together enabling developers to verify that the changes on each branch do not conflict.
Many software teams adopt a practice of branching for each feature or perhaps branching for each release, or both. c
There are many different workflows that teams can choose from when they decide how to make use of branching and merging facilities in version control systems.
B.2.3) Traceability
Traceability: Being able to trace each change made to the software and connected to project management, and bug tracking software such as azure devops and being able to annotate each change with a message describing the purpose and intent of the change, can help when you need to go back in time to see what changes you have done.
There are several version control systems. The first ones dating all the way back to the 80s.
Some of the common version control systems used in the traditional software development field are:
- CVS, short for concurrent version system
- SVN, short for subversion.
- Git, short for...well it can mean various things if you ask the inventor of Git
- And proprietary version control systems, either created by the manufacturer of the PLC or some third-party vendor.
These version control systems can be either proprietary or be built on top of any of the popular version control systems, such as Git.
A common delimiter between the last category is that they are usually costly and provide little to no value over the ones that are free, open source, and traditionally used in the software industry.
If you are using Beckhoff's TwinCAT 3, you don't need to give your hard-earned money to these companies for the tools to do version control
B.3) VCS and the Automation Industry (rant 😤)
The automation industry is really underdeveloped regarding version control.
Most PLC vendors use their own proprietary way to store source code, which results in that the PLC vendors and third party suppliers charge you big money for something so basic as version control, making the barrier for people not doing version control even higher.
The vendors are either providing their own proprietary version control system and the tools that only works with their particular brand, or there are vendors that build a system on top of the popular version control systems but then it only works if you use their software to do the version control.
Not only are these tools expensive, but they are also add complexity and additional dependencies for external software.
So who are the losers in having it this way? Most of us. So all automation engineers and system integrators. Actually, everyone loses in having it this way except for the PLC vendors and the third-party suppliers of costly version control tools, that can cash in the sweet juicy cash by vendor locking people into their system.
I know I have a lot of traditional software developers amongst my viewers of this tutorial And yes, this is just one of the really sucky things about industrial automation.
Everyone tries to squeeze every single dollar out of you, even for something that you most likely have taken for granted is free for the last decades.
We as automation engineers have to stop this and tell our PLC vendors to get better. We have to tell them to start storing data in an open and human readable format, and not in some obscure proprietary binary blob, that you either have to reverse engineer to understand or be best friends with the provider in order to understand.
We have to require them to include proper tools for doing version control.
We have to require them to work together to use a common format for source code, either the one supplied from PLCopen that everyone just uses to export and import data to. Or something else but that's common.
If the manufacturers didn't do vendor lock-in and used a common format, I woiuld amongst many other would be quick on making a free and open source tool for version control for all the various PLC brands.
If we don't start to require this kind of tools and support from the vendors the industry will continue to have formats that are incompatible with each other.
They or third-party companies will continue to charge you big time for their tooling. It's already hard to get automation engineers to do version control. We don't have to accept that things be this way PLC vendors, please don't make it harder than it needs to be.
If you don't change it's just a matter of time before someone else does it and then your alternative won't look favorable anymore.
The good news is that with Beckhoff and TwinCAT 3, you don't need to spend a single cent for version control tools.
You can use all the tools that you are used to in the traditional software development industry.
Fact is, support for version control is already integrated into the development environment for TwinCAT, as it's based on visual studio which already is being used in the traditional software development industry.
The traditional software industry has been doing version control for decades already. It gets even more important to use traditional version control tools when you will start to look into concepts such as continuous integration and continuous delivery.
Which I will be talking about in a coming video. I'm not saying Beckhoff are the best.
Beckhoff at least store their code in a format that is human readable and that plays okay with version control systems, such as Git.
Doing version control with TwinCAT 3 is 100% free. Not only are all the tools that we will use in this tutorial free, but most of them are also open source I've been doing version control with numerous projects in various industries, ranging from the deep ocean to the universe, using TwinCAT 3 and Git for over 10 years, and never had to pay a single cent for the tooling. The storage space and repository is not included in this of course but the tools to do version control I've never had to pay anything for.
I think this is how it should be across the whole industry, not just TwinCAT. I'm not saying Beckhoff for perfect. They could improve here as well, and I made a video about that.
Video: https://youtu.be/dgEsib42WaA
Don't waste any money on the tooling for version control. Demand your automation provider to do better.
I wanted to point this out because, you know, I actually do...I just don't do version control with my software. I nowadays do version control with most of my stuff I develop, right?
If I do a website or if I do a text document in certain formats, I put under version control. Since I started using version control over 20 years ago now I just use it for everything.
That's the thing...and this is what I like with the whole software industry, and this is why I love working with traditional software is that...you know there's all these people just...creating all of this stuff like Git and everything and then there's people doing these nice open source projects so you can you can work with this.
You know it just drives the industry forward. While all these custom solutions that have popped up recently but also that have been around forever in the automation industry, they're just really bad, you know? It's a shame that this is the direction that the industry has gone to. Anyway I'm gonna stop ranting.
B.4) Introduction to Git
For the remainder of this tutorial we will be looking into and working with Git.
Git was created by Linus Torvalds, the creator of Linux. As he thought all the current version control systems were lacking in some aspects.
Like it wasn't enough to create an operating system kernel that is running on the vast majority of the servers and the vast majority of smartphones in the world, he has now also created the world's most popular version control system.
It's impossible not to be fascinated by his selfless contributions to the world.
Git is what is called a Distributed Version Control System.
What differs this from the more traditional Centralized Version Control Systems, such as SVN, is that Git uses multiple repositories including a centralized repository and server, as well as some local repositories
So Git does not necessarily rely on a central server to store all the versions of a project's files.
Instead every user clones a copy of a repository and has the full history of the project on their own hard drive.
This clone has all of the metadata of the original, while the original itself is stored on a self-hosted server or a third-party hosting service like GitHub.
B.4.1) How does Git work?
I'll give a very brief introduction to some concepts in Git, as it's necessary to have a basic understanding of how Git works before we start to use git in practice.
Let's first look at some of the main components of a Git project.
First you have the Working Directory, which essentially is your project folder where you store all your files and folders for the project.
Next you have the Stage which sometimes also is called the index. The stage contains the changes that you have marked to be included in the next commit. We'll get to the concept of commits soon.
The Local Repository tracks all the changes that you have made to files in your project, building a history over time.
The final component is the Remote Repository.
Remote repositories are versions of your project that are hosted on the internet or network somewhere. Note that you don't need to have a remote repository at all. You can have the full experience only with a local repository, though when working in a team also having a remote repository is preferable.
B.4.2) Example: Working with Git
Your basic Git workflow will normally look like this.
First you modify your files in the Working directory,
Next, you will stage the changes you want to include in the next commit, by doing a "git add"
Commit your changes by "git commit". Committing will take the files from the Stage and store them as a snapshot in the Local Repository.
Upload your Local Repository contents to a Remote Repository with "git push".
In your Working Directory every project file can be in three possible states,
- It can be staged, which means the files with the changes are marked to be committed to the local repository, but they are not yet committed.
- It can be modified which means the files with the changes are not yet stored in the local repository.
- It can also be committed which means that the changes you made to your files are safely stored in the local repository.
A "git pull" will incorporate changes that someone else might have done in the remote repository, into the current branch.
Now imagine that you have made changes in your code meanwhile the remote repository was changed, and this can result in something called a merge conflict.
Read more here
Everything between <<<<<<< and **======= ** are your local changes. These changes are not in the remote repository yet. All the lines between **======= ** and >>>>>>> are the changes from the remote repository (or another branch).
You need to look into these two sections and make a decision to solve the confilct.
B.4.3) Introduction to .gitignore
When you do version control you normally don't want to have all the software artifacts under version control.
With most programming languages and software development platforms, there is a lot of files that is generated from the source code, that you don't want to be tracked.
Typical examples of these are object files and executables that are generated from the source code. As long as you have the source code, you can always create these files by simply compiling the source code.
By using a .gitignore file in the root of your project directory, you can specify what type of files that you don't want to be under version control.
For TwinCAT 3 projects there is a starting template available on GitHub's repository for Git ignore files for different programming languages.
Link: https://github.com/github/gitignore/blob/main/TwinCAT3.gitignore
Ok, that was a lot of theory and still I've only scraped on the surface of what I would like to go through with you. But now I feel I don't want you to get tired of theory so let's get our hands dirty and do some practice.
C) Intro: Why Git and TortoiseGit?
Ok, it's time again for a little bit of live programming and I wanna start by mentioning that this isn't gonna cover everything you can do with Git. Actually it's just gonna briefly touch on what you can do with Git, because there's just so much stuff you can do with it.
The focus here will instead be how to work with Git in TwinCAT.
I'm gonna make more videos about Git, because this is a very important subject so I of course want to show all the capabilities and everything that's possible with version control in industrial automation. This is just gonna touch on the most important topics in Git.
And I also want to mention that there's much more material to review, so here are some recommendations:
- Roald Ruiter's "Source control tips for TwinCAT"
- Roald Ruiter's "Reduce formatting fights with pre-commits for TwinCAT"
- Chris Chung's "Let’s try Source-Control with Git"
With that said, let's get started. The first thing we have to do is to download Git itself.
Git is the open source and free software that you use to to do the versioning controlling.
It is available for:
- Windows
- Linux
- Mac
- and all kinds of platforms.
And we're of course going to download for Windows because our development platform is based on windows.
Then the second software which we're going to download is something called TortoiseGit
and this is just like a shell for Git itself. It's the client that makes it possible to use Git in an easy way.
Because with Git you only basically get the tools to do everything from the command line.
And I would recommend you to learn command line stuff because especially if you work on other platforms, like Linux and stuff where you mostly spend your time in the shell and it's really good to know.
But for a lot of my viewers I know you're coming from an industrial automation background. Maybe you're not used to using the shell and command prompt and stuff like this. Then for this we need an additional piece of software, so that we Git is more integrated into Windows, so you get this human machine interface GUI to work with Git.
And I want to mention that we actually don't need the TortoiseGit stuff because with Visual Studio, so with TcXaeShell, so the development environment for TwinCAT we have a very good Git integration so we can basically do most of the Git stuff that we need to do directly from Visual Studio, which I will also show.
Watch more here: https://www.youtube.com/watch?v=pgqEwmysxbM
But I just simply thought that I want to show you another alternative to just using Visual Studio for the version control, just to show on the concept that "Hey there's all these free and open source tools that you can use to do Git", and more push on the point that you don't need to pay anything to do version control with Git.
And that's what I want to point out here that these are just examples.
So Git we need, this is the tool we need. But the TortoiseGit is optional. There's many many other clients we can use instead of TortoiseGit. There's many many more of them and that's the nice thing. There's so many options and you don't have to pay for them.
C.1) How to install Git 🔍
But let's start with downloading Git. So just look for "git scm".
You get to this website https://git-scm.com/
And this is where you download Git itself, the binaries to do version control.
Download for Windows, so we're on a Windows platform, but if you actually go to downloads here you can see there's downloads for other platforms as well.
But we'll go with Windows. This is a 64-bit system I'm working on, so I'm gonna download the 64-bit version.
Then when it's downloaded, you start installing it.
Note: if you don't need any special adjustments, just press "Next" to everything and let it download.
Once it's installed I just want to show you that there is this "Git bash" where you can do command line stuff with Git.
So once this is installed you get this tool here
Where you can do stuff directly from the command prompt.
Note: you can even do Git directly from the normal windows command prompt.
Read more about:
Now we need to download TortoiseGit.
C.2) How to install TortoiseGit 🔍
TortoiseGit is again just one option. You have many others, or we can skip to use TortoiseGit and just use Visual Studio, but I just really really want to show you these two alternatives that you can work with to do Git because all of this software, for all of them it's still just Git. So all of them will use the same concepts.
Look for "TortoiseGit"
You get this website: https://tortoisegit.org/
The reason actually I use the TortoiseGit is because when I started using version control...back in the late 90s. One of the first softwares I started when I came into contact with version control was TortoiseSvn, so this was the same program but for subversion instead.
And then you know when I shifted when I realized that "Hey, Git is much much much better than subversion", then it was just natural for me to go to TortoiseGit.
Download 64-bit version,
But again I want to point out there's many many other options to TortoiseGit. But I have to show you something, right?
Okay run and just click "Next", then install,
Then, I would recommend you to run first start wizard because then you can choose the language.
Select English. Next.
This wants the path to the Git installer and this is already installed because when we did install Git it was installed into this folder.
That's why TortoiseGit just needs to know "Hey, where is Git itself?". Just press next.
Now, your name, so Just enter everything. Next.
Actually I can just mention the settings you're doing here are something called Git global config. This is a configuration that's used for all Git repositories. Then you can do custom configurations for every repository itself. I'm not going to cover that so much now because we're only going to use the global Git configuration that's going to be common for all repositories Just press next.
Now you actually need to reboot the computer, so I'm going to do that. You need to reboot it because of this integration into Windows.
Okay so now we have Git installed and we have TortoiseGit installed. What you'll notice now is if I right click here then you see we have a couple of new menus in Windows.
These two menus are the stuff that's coming from Git itself, and all these three is stuff, that's coming from TortoiseGit.
D) Git Hosting Solutions: Introduction to GitHub
But I first want to say that for this tutorial I'm going to use a program that we previously developed, and I will do version control of it, right? Because all the software we've developed so far we've only put it into a folder somewhere on the computer and not done any version control whatsoever of it, which is bad right? We should always already from the start of our project put the project under version control
But to do that we need somewhere to host our Git repositories, right? We can of course host them on a server that we have, on our hard drive, you can even do that actually, you can just put them on a network drive somewhere. But what you usually want to work with and especially once you get into...you know work with teams and colleagues and just bigger software projects, you need an external repository to store the code.
For this there's many different providers. There is GitHub, there is GitLab, there is Azure DevOps, you have Amazon, etc.
There's many that provide a place for you to store the repository and I generally recommend for beginners to just use GitHub because it...first yeah it's the biggest one but it's also very user friendly I would say. It's very easy to create an account. It doesn't cost anything. It has a lot of features that you generally want to use when you work in teams I have a GitHub account.
I recommend you to just go to GitHub and register here. Because then we can create all our repositories here. https://github.com
So again, GitHub is just a place to store the repositories. But on top of that it adds a lot of other services.
It adds services to for example create issues, you know?
There's all these services around Git itself. Like you can create an issue for the software, so you can have a ticket and follow it, you know. If you fix a bug you can close the ticket.
You have automation stuff for doing this thing called continuous integration, continuous delivery, which I'm not gonna cover here. I'm gonna cover that in separate videos. But that's basically to build pipelines for building your software, and do automatic testing and all this amazing stuff that I'm really pushing for everyone to do. But this is quite new in the field of industrial automation.
And GitHub provides lots and lots of other stuff like stuff for security. Who should have access to these repositories and everything. Just go to GitHub register
This is the difference between Git and GitHub Git, that's the version control system itself.
GitHub is a place to store Git repositories and provide services on top of that.
D.1) How to create a GitHub repository 🔍
First of all let's create a new repository and we do that here. Once we have the account on GitHub, new repository
and we're just going to call this guy "TestRepo". You can add a description
and Public or Private just says whether this repository should be available for everyone to see.
So especially when you work with open source projects like the TcUnit framework I've been working with, then you want it to be public because you want everyone to see this. You want everyone to be able to help you with coding For this one we can just create private. For private, then only you have access for it and this is typically, when you work with commercial projects like you work for a company or something you just store everything privately.
Then when it's private you can of course adjust which GitHub user should have access to this repository.
And there's some other stuff we can do here. GitIgnore, I'll get back to this soon.
But just for now just create repository.
Now you have a Git repository,
so first of all, congratulations you just created your first repository.
D.2) How to clone a GitHub repository 🔍
Now you just take this address.
This is the address of the repository and we are going to clone it.
So clone it means that we're going to take this whole repository that is this Git repository, and make a local repository out of it.
And you do that by you go into your computer.
Let's create a folder. Call it "Workspace".
We clone it here and you do that by using "Git Clone..."
Again you can do this by the command line but again I'm not gonna do anything today with the command line. I'm gonna do everything through the user interface.
And then you enter the the address from from the GitHub repository and You press ok.
Now it's cloning it and creating a local repository out of this.
If you go here you can actually see that there's a hidden folder here,
and this is kind of the folder that Git uses to to keep track of everything.
And this is the nice thing with Git. You're actually cloning the whole repository. It's not like subversion where you have to have a connection to the remote repository for it to work.
With Git you know, you can...I've been working in in places like far far far far away from internet connectivity but I have still been able to do my commits and work locally which is such a fantastic feature with Git.
Now we have a Git repository.
D.3) Using Version Control with Our TC3 Projects
What I'm going to do now is I'm going to put one of my programs that I developed before, so that we developed together in this tutorial under version control. It's this "PLC_Program_2", which yeah, we can just quickly look at it It's this program where we used a sensor. So this is the program we used for the distance sensor, the IFM sensor to do some IO-link, when we were talking about hardware, so I/O.
This is the program where we just had done distance sensor for my IFM.
So this one is not under version control, but we will put it on version control. I will close it.
We have a gitignore file here, I'll delete it for now, because I want to show how this works.
Don't worry we'll recreate this gitignore.
What we're gonna do now is...we're gonna take this complete solution and just copy it over to here.
What's gonna happen now is that now we put these files here. So they're not staged yet but we will stage them very soon.
D.3.1) Using Git with TcXaeShell (Visual Studio) 🔍
Let's start by opening the solution because what I want to show you now is the integration of Git in Visual Studio itself, so TcXaeShell in our case.
Now that the project is open, there's actually a tiny tiny tab here and that's called team explorer and this is the guy that's going to help us with the whole versioning control.
This is again...I just really want to point out here that everything we're watching, I haven't bought any license for any software. All of this is stuff that you get for free from Git.
GitHub as well actually for the repositories.
But also the integration into Visual Studio is just the default integration of Visual Studio for versioning control that Beckhoff have used which is just a huge strength with Beckhoff, that they haven't built their own solution on top of Git or their separate solution. They just use the vanilla Git that the rest of the software industry is using which is...it's just so good.
I just want to point out that this is something that Beckhoff have done tremendously well Thank you Beckhoff!
There's a couple of buttons here to go through. I thought i'll just briefly go through them.
Branches
Let's start with branches.
Branches is something...when you develop your software, you can add...for example...let's say you're in a situation where you're a team and you're...many people developing software in the same repository on the same project.
Then you want to add a feature, and the traditional way to develop software is that...then you create a branch and then you can add all your stuff in the branch, test it out and then merge it in.
Unfortunately to show all of this is going to take some time, so I'm not going to show anything more about branches. I'm going to create a separate video about this.
It's just important to know that there's this concept of about branching in Git where you can... it basically grows like a tree, right? You have the main branch and then out of that there's branches growing to left and right. You can you can add some features and then put them back into the main branch, so there's many use cases actually for branches, but i'm not going to cover it here. We're going to do that in a separate video.
Tags
Tags, is basically just a way to mark a commit.
When you do your software you're going to do commits, you're going to commit, you're going to add the features. And then at some point you're going to get to a level where for example you want to do a formal release, right?
You have a customer, you're going to do a release. Then you can put a tag on it and say that this is... The tag is just a label for a commit, so you can just say this is version 1.1.
The tag is version 1.1, you call it version 1.1. You can just put a label on your formal releases.
There's nothing magical about tags. It's actually just putting a label on a commit. I use this all the time when working with with projects, because at some point you end up in a situation where you have to do releases and then tags is the way to go.
We're not gonna do that here but it's important for you to know.
Settings
Then we have settings.
This is nothing special. Here we have our global settings which I briefly talked about.
Because we already did the global settings in TortoiseGit, it's stored...we can see them here as well.
So this is just what name, and what e-mail will be visible in all our commits.
Changes & Sync
Then the interesting guys are the "Changes" and the "Sync" which we're gonna work with today. With changes,
you see all the files that have been changed since the last time.
As you can see because we haven't done any version control yet, basically everything we've added is visible here.
So Git says "Hey you should add this file". You know all of this is marked with add,
so you can add these files into version control, and when we add them...just as I showed in the presentation we will stage them.
D.3.1.1) Using the .gitignore file
But what's interesting here if you notice is that we have all these weird files like ".suo",
And you have the compiled libraries here, you know?
And these are typical files that we don't want to version control, right?
I mentioned in the presentation about gitignore that there are certain software artifacts that you don't want to put under version control, because they are a result of a compilation stage and these you don't wanna...you just wanna version control the source codes that you will use to generate these guys, but you actually don't need these guys in the version control .
Luckily for you, there is a gitignore file default created already. It's in the GitHub official gitignore repository. So there is one for TwinCAT and I'm gonna show you how you add it for your project soon.
We only want the TcPOU, so this is the MAIN file, right?
We want our function blocks, so we only want the raw source code, so to speak.
What we need to do now is that we need to add a gitignore file to the root of this repository.
For this, you are very lucky because if you Google "TwinCAT gitignore".
Then you're going to end up either on my blog, number one.
**
Or just simply go directly to this GitHub. This is just a standard template.
This works for the vast majority of TwinCAT 3 projects.
Read more here: https://alltwincat.com/2019/12/02/gitignore-for-twincat/
There might be some tunings you need to do, especially if you work with C++, and if you do some special stuff you might need to tune this file, but default this works for most projects.
So just simply copy this guy. Create a new file. Call it ".gitignore"
Open it, and just put everything here. As soon as you save it...
If you go back here now to Visual Studio... You see how many of these files were removed from version control
So suddenly lots of files are not recommended to add, because that's what the gitignore file does. The gitignore file simply tells us that "Hey Git! You should just ignore all of this stuff, we don't want to put that under version control".
So suddenly we only have this stuff that's relevant for our TwinCAT project.
But you'll notice that there's actually one...I just noticed that there's actually one file here that we don't want to put under version control, and it's a .suo file.
And I've actually written that...
for TwinCAT use this but on top of TwinCAT you want also to use the Visual Studio gitignore file because that's for all the Visual Studio specific stuff.
This .suo file that's something that's not Beckhoff specific, it's Visual Studio specific. So we need that as well.
So just Google "Visual Studio gitignore". Then you end up here.
You go raw. Copy everything and just put it at the bottom of your gitignore and save it.
Immediately the .suo file was removed (from version control).
And now we have a very clean and nice project where we will only put the stuff that we should put under version control, which is very good.
D.3.1.2) Staging files
Now, what you can do is to stage these files, and you can either stage them one by one, so you can right click...and click on "Stage".
But before I do that, I actually want to show you that the Git client that we have here in Visual Studio is just one of the Git clients out of many.
So you have the one that Microsoft have done for Visual Studio, which luckily Beckoff have made no adjustments to. It's just using the raw stuff from Microsoft.
And you can also use...if you go to the workspace, to the test repo, you can also use stuff through TortoiseGit, so you can you can go here, to any file like the gitignore. Right-click on it, TortoiseGit, and add.
So this add does the staging. I just want to show you that... So there's different ways to do this, right? With this client we can only work with TwinCAT and Visual Studio projects. So specific stuff that only for...actually for TcXaeShell. With TortoiseGit you can do it for much more!
Ok, so what you wanna do now is to add.
One way is to simply stage one and one (as mentioned before).
Or you can just press this button and then it will stage all.
So we press that. Now all of these... You can see, state changes. All of them are staged.
D.3.1.3) Doing a Local Commit
The next step is of course to do the commit itself. So now they're in the staging area but they're not yet committed.
You can also see it here. If you go back again to Windows. If you use TortoiseGit, you can see that all of them have gotten this plus sign.
So you can't add them anymore because they're already added by Visual Studio. Because again, both of them are using Git.
The next thing is to do a commit. And for commit you need to add a commit message, and we can just write "initial commit". Press this "Commit staged".
This will commit all the staged files, okay.
And now Visual Studio is very nice because it tells us...this commit is created locally, sync to share your changes with the server.
And this is the important thing So far we've only committed locally into our local repository, by creating this local commit. So a commit...it's like a snapshot, and this snapshot is not yet available on the remote repository.
So the stuff we've done now you could just do this without any internet, but of course at some point or another you want to synchronize this with the remote repository so that all the other people that you're working with can see the changes as well.
I mean actually if we go to this test repo now, and I press...and I just go here. You know, there's nothing. Absolutely...it's just empty.
We haven't pushed anything yet here.
D.3.1.4) Pushing the Commit to the Remote Repository
The next step is to go back here, home.
You have the sync button,
and here with the sync you can push your local changes to the remote repository.
So you can push the stuff that you have in your local repository to the remote repository. By pressing push,it's going to do some stuff... Successfully pushed branch main to origin.
Now if you go back to the repo, you can see that the stuff we we committed are now also in the remote repository. Now someone else can can clone this project.
You know a colleague and work with the same repository and that colleague will also have a local repository. Work with the local repository and push.
Here you know, here it starts to get a little interesting, right? Because if you're more than one person then you're gonna end up situations where you do changes to the same place and these changes could create something called a conflict.
Unfortunately I'm not gonna cover it for...
This is also something I will push to another episode of this tutorial...not of this tutorial but a separate video.
Because it's just too much to cover and this video is already insanely long but it's...this is basically how we work in teams.
D.3.1.5) Git "diffs" (using Project Compare) // ------------------------------------------------------------------------------------------------
So now we have everything here. When you work over time, you're gonna of course edit files you're going to change files and at some point you're going to end up in a situation say...you know you delivered a machine and you want to know "hey how did the code...what's the difference between how the code looks now and how the code looked like a week ago?".
And for this you can do something called the diffs in Git, so you can compare a certain commit with another previous commit. I'm just going to show you this by simply...we will just create another function block to this code. So I'll just create...uh actually no let's not even create another function block. Let's just create another instance of this sensor that w
e're using. So we just create another instance. So let's say we have another...a second distance sensor. And we want to execute it as well. So we just simply add that. Or actually maybe let's just add another function block just for the fun of it, and call it "FB_TestFunctionBlock" It doesn't do anything special My counters that I always use as example, because you can never get enough of counters Now what you can do is...you can go back to team explorer.
Go to changes and for example you can click...first of all you will see that this file was completely added since the last commit But we can also see that this file is modified. We can go to "Compare with unmodified" And then we'll get this. And this is where we need to do a tiny change because what Visual Studio now does is that it's just looking at the files themselves And looking at them and seeing okay these are just some weird files and it's just presenting them as these raw XML files. And this is how Beckhoff are storing all source code. With
this weird XML annotation, but what we want to do now is that we want to tell Visual Studio to...instead of using your own compare tool use a compare tool from Beckhoff instead To do that we go to TwinCAT here. Then we go to "Tools", we go to "TwinCAT project compare" Which this tool is a tool to basically compare two complete projects, but we can also use this tool to compare individual files. Then we press "cancel", we go to "tools" and then "configure user tools"
"Export configuration". Select "Git". Press "Ok". And then what we want to do is that we want to...now we want to tell the Git global config file...the global Git config file to use TcProjectCompare for TwinCAT files and with this tool that Beckhoff have done, it does it automatically for you So if you just press "ok" here. Then press "ok".
Close this down and now if we do a compare It's using the TwinCAT tool instead. So the Beckhoff tool for this, so "TcProjectCompare" And of course this is much easier to read than the XML stuff that we just saw The nice thing about this is that this works for all kind of TwinCAT files. So it doesn't just work for structured text or anything.
It also works for I/O configuration, it works for everything that's TwinCAT. So you can use it for ladder and the graphical programming languages as well. Then it's going to show the differences in the graphical programming languages. This is just one of the strengths with Beckhoff. You know, they put t
his tool here and then they don't charge you for it. It's just...they basically have this thought that...of course version control is something you shouldn't pay for and I really wish the rest of the industry...it was it was the same way. So this is really good. So I recommend you to do exactly what I did because then you're going to use this tool for doing comparisons instead This is just so nice because now you can actually go in into any file and if you've worked anything and always do comparisons with anything previously.
D.3.1.6) Options: Using Separate LineIDs
I want to point out another thing There are some changes I would really recommend you to do in your development environment Because of the way that Beckhoff stores files. There's two changes I'm gonna go through with you, or maybe three. I don't remember. It's at least two. And the first one is actually...if we... I
f you look at these files...if you just look at the raw content of them, you see that they have this weird stuff here. You know, this LineId... From my understanding this is used when you do an online change and you're gonna...or you're gonna do an online login, then this information is somehow used. I'm not entirely sure how.
But it's not anything that we need to store under version control. So this is one of the stuff that we're gonna get rid of. Okay, so let's start by changing TwinCAT so it doesn't store this information. And you do that by going to "Tools", "Options" &
quot;Text editor"...no not text editor..."TwinCAT" actually. "XAE environment", "File settings"...no that's not the guy Right here, "TwinCAT", "PLC environment", "Write Options". This "Separate LineIDs" change it to true. What it's going to do now is that instead of saving all of these LineIDs, so this stuff inside each and one each and every source code file, it's going to store it all of this in a separate file Then we have that separate file in case we want to do these online changes, but we don't have to version control it, so we don't have the version control this information because this information
is really not necessary to version control. That's the first thing we're going to do. Actually let's do that now. Then I'm going to show you if we open the main file and we just re-save it Then we want to reload it. You saw the the LineIDs were gone. This is really nice because then we don't need the version control them.
I think to be absolutely honest if anyone from Beckhoff is watching this, especially from the headquarters and the software development department, I would really recommend you to set this one to true by default. Because for some reason this is not a default true and for all my other watchers that are not from Beckhoff this information is not stored in the project itself. This is something that's stored...the setting is stored in your development environment which means you know...I've been working with projects with many developers and then I've told them "Hey guys, please apply this setting", you know I
when I do code reviews...so I do lots of code reviews with TwinCAT code...then I always...if I see this then I just call the guy or girl and say "Hey you need to do this setting". Usually I actually put it in the wiki so that everyone knows about what common settings we should use in TwinCAT. But now you know so you don't have to make this mistake.
D.3.1.6) Options: Enable Multiple Project Files
The second change we're going to do is in the "XAE environment" and "File settings".
So the way that TwinCAT works is that it stores all these different types of configurations. So configurations about I/O boxes, EtherCAT drives The motion stuff and everything in one big mega blob file. I don't like this because you know if you have just one file that stores all of this then this file is obviously going to change a lot This file is going to get very big and I prefer to set all of this to true because then each and what one of these configurations is going to be stored in its separate file.
So if you have an I/O-box...let's say we add an I/O device here for an EtherCAT slave you know...we have an EL1008 or something then there's going to be a file created just for that guy. Which of course is much easier... which of course makes much more sense because you know when you do code review later or something then if you just change one file it's much easier to see the changes in that file than having this 10 000 lines of code file, which you know it makes it a real mess So my recommendation here is simply change all of this to true
And again for...if anyone from Beckhoff headquarters listens to me now I would recommend you to to change this to to true. I've actually not encountered a single project... and there's been a few now, where the settings I've shown you here have not been the default. Everyone changes this to these settings and I recommend all my watchers to change change this.
I mean if you're not doing version control then this doesn't matter but my firm belief is that there's not a single reason not to do version control. Even if you do the simplest of the simplest project and even if you're the only guy, you should do version control. There's no reason not to do version control. It's very unprofessional to not do version control.
Press "Ok" and that's the settings that we need.
D.3.1.7) Example: Doing a Second Commit and Push
Now we've done a few changes. We've done a change in the main file, and we've done a change by simply adding another function block. Now if you go to team explorer, and again if you go to... oops...if you go to "Changes", you'll now have three files that have been changed.
You have the test function block which we added So it says add here, so it's not staged. It's just in our folder, but it's not been staged yet So it says you should add this one and we have this guy which is just changed. So if we first look at this one you can't compare with the previous one, right? Because it's not been staged yet, so there's nothing to compare against.
But if you go to the main and you compare it with the previous one, then with the unmodified one. Then you see that, yeah, we've added another instance of the sensor. I mean, I think this is really really good and there's also another file here called plcproj, so if you do a compare with unmodified here as well then yeah W
hat Beckoff will show now...what TwinCAT will show now is that this plcproj is basically a file that stores the information about what files are included in this project. What we can see if we go to POUs here then...yeah aha okay yeah...we've added another function block. Super useful. What we'll do now is again, we might want to comment all of this. This is a second commit. Or actually let's make a better commit message.
Always make good commit messages Writing commit message And commit all. Oops I forgot... You have to stage this And you have...yeah...just select stage all. Then you put everything on stage for the commit And then commit the stage stuff. Now we have a separate commit created. And again this is only committed to the local repository.
If I go here, I still have only the initial commit, and we can actually see it here because we only have one commit here Then we have to push these changes, so go to home, sync, and push whenever you have Internet connectivity which we have now. Then it's gonna synchronize that. Successfully pushed to origin main. And if we go back here now we have two commits. 38 seconds ago.
So this is quite nice Actually just by looking at GitHub now I realized that there's lots of stuff I would want to cover just about GitHub, you know? About pull requests, issues, and everything but there's just so much to cover about version control that this really has to wait for the next video
D.3.1.8) View Commit History
Another thing I want to show is that if you go to solution explorer you can...for any file you can right click on it, and select this "View History". What it's going to show now is the Git commit history for this particular file, and we can see that this file has had two commits, right? It was part of the first commit where we just initially committed all files, but it's also part of a second commit where we added the second IFM sensor instance.
When you worked with TwinCAT projects for a while this Git commit history is going to be really really long, you know. I've been working in projects that have been going on for several years and, you know, when you're 10 developers working in a project and this Git history...it's really nice to be able to see what what has been happening in the last years.
Especially if you want to go back to an old commit because for example you had an older version of the software that was maybe more stable than a newer or whatever Then you can do this stuff like view commit details, you can compare with previous So again compare with previous, will again just show the difference to the previous commit. You c
an select two commits and compare these two. Which means you can select...if we had 10 commits here we could select this one and select another one down here compare these two. I mean the possibilities are just endless.
D.3.2) Comparison with TortoiseGit
So I just want to finish by showing that everything we've done here is also available in TortoiseGit, or any other Git client so if you go back here you see that you...if we open our repository we can track all the changes here as well.
So we can press this nice button "Show log" here for this repository, and see all the changes and all the commits we've done to this particular repository. Here you can for example click on this particular commit and see which files have been changed since the commit before that.
So you see that in this commit we added this file and we modified this one and you know, you can do the same thing as with Visual Studio that you can compare...do compares. The difference here is if we do compare...you remember with Visual Studio we got this nice...I can just quickly show. So in Visual Studio when we did a
compare... when you did a compare then you got the difference like this because it's using the TcProjectCompare Which is the TwinCAT tool. If you use TortoiseGit it's going to use TortoiseGit's built-in compare tool instead, so if you do compare with base, it's going to get... Now we're going to just get the raw content so...because TortoiseGit has no idea about TwinCAT files, it just shows the raw content of the files, the text content which is anyway the way that Git actually works.
It is basically just comparing the raw text Here we can see actually, you know that yeah...the LineIDs are gone here because we did the change in these settings of TwinCAT. And that we have also added another instance here of the sensor. But it's basically showing the same information. I of course prefer to use the TcProjectCompare in Visual Studio because this is done specifically for TwinCAT but I think it's very important for you to be aware of these other tools because you know, you're gonna work with other software than TwinCAT in the future. For example, if you're just gonna
use version control to version control text files or readme files or maybe you're gonna write some java or C++ or something else then you're gonna work with this more traditional tools. Then you're not gonna use TcProjectCompare because TcProjectCompare by definition is just for TwinCAT.
So it's important for you to know about this
D.3.3) Missing Topics and Conclusion
So yeah but I think that's what I wanted...well this is not what I wanted to cover. I want to cover much more, because I haven't talked about stuff like branches and about you know, if we're two developers so you know, if there was another developer here next to me let's say it was a "Jakobina", like "Hello" (pretending to use a girl voice) someone else here next to me and we were gonna work together and then how would that look like, you know? Because then we're gonna commit to and push to the same repository
We're gonna get conflicts, so we haven't been talking about that. But that's unfortunately just has to wait for another video, because this video is already getting quite big. So yeah...
This was a very very VERY short introduction to version control in TwinCAT 3 There are many concepts I had to skip.
Even many of the basic ones like branching, merging, handling of conflicts, rebase and cherry pick. These concepts are important to know when working in a team on a common project. Version control is such an important topic that I will get back to it in other videos of this channel. One of the things I want you to take with you is the fact that not doing version control is unprofessional, and it's going to bite you in your back in the future if you don't use it.
You should always put your projects under version control, no matter project size. Don't wait with it, but get yourself an account on any of the popular Git repositories, such as GitHub, GitLab or Azure DevOps, and start gaining experience. Thank you very much for listening to this first part of the advanced series.
I'll see you in the next part where we will look into how you work with several versions of TwinCAT at the same time. See you!
G) 💬 Summary (copy code 🖥️)
Z) 🗃️ Glossary
| File | Definition |
|---|