This is in no way a complete overview on what CODESYS Git offers. It is merely meant as a primer to get you up and running with git on forge quickly.
Git is a popular open source distributed version control system. Understanding and mastering the basics is easy. However, the best results are achieved via 'learning by doing'. This blog-post tries to condense the bare essentials for CODESYS Git so you can get started quickly.
Be aware that Git is a totally different beast from svn! If you have previous experience with svn you will have a (small) head start in understanding the basic key concepts of Git.
CODESYS Git usage requires a valid Professional Developer Edition or a Demo License (free).
If the entire community (you all) will ask politely, CODESYS will surely consider enabling free usage for use with CODESYS Forge
General Git terminology
Git: 'global information tracker' or more commonly 'git', is a 'container name' for a source code repository
Main: Since 2020 'master' is being replaced with 'main', in this guide we will use 'main'
Remote main: The remote 'main' repository, which is usually hosted somewhere online or somewhere in your network and it contains the entire project code and it's entire history. Also referred to as 'origin'
Local main: Usually a local clone from a remote main. The local clone is an exact copy of the remote main repository and acts a local starting point for your contributions
Branch: A working branch or snapshot of 'Local Main' which acts as a startingpoint for you to add contributions in. Once you have tested the contributions (and stage/commit them), you can merge them back into your local main branch
Merge : the act of 'merging' changes from source branch S into destination branch D. You should use this to update a local main with a development branch or to update working branches.
Checkout: the act of selecting a new active working branch, the IDE will switch to this version so you can work in it
Stage: the act of preparing files and code changes on the current checkout
Commit: Adds staged files and changes into the current checkout branch. A username, emailadres and a commit message are to provided on each commit. The more descriptive your commit message is, the better as this will help you search for mutations if you need to without digging into the history too much. A good commit message could contain a version number, a ticket or sprint number/ message. Changes are always commited to the current checked out branch
Push: commits from local branches are ultimatly merged into the local main.
When you are satisfied with the result, e.g some feature or ticket is completed, the local main needs to be synchronised with the remote main. In order to di this we must 'push' all changes into the remote main.
Pull or 'Pull request': A pull request can be sent to the admin of a remote main. This will notify the admin that a new code is ready to be merged into the remote main. After checking this new code the admin can decide if he merges it (partially or entirely).
Sync: The remote main and your local main should ideally stay synchronised (have the same content) and should be synced on a regular basis. This is achieved by 'pulling' the remote main into local main and pull these changes into a working branch. In general, a synced main and working branch will ensure that merging changes back into main will not cause conflicts
It is a good practice to update at least your local main after loading your project into the IDE, you can then decide to update your specific local workbranches if needed
Never commit and push untested code into a remote main (or even a local main), always test your work beforehand! This also a reason why pull requests are popular as they also provide a (in theory) 4 eyes principle
Flow: There are many ways or practices (flows) to use git, however there is no single best flow as this depends on many factors. In general a good flow mainly depends on group needs, group size and group growth. A good git flow will not cognitively drain you but helps you focus on development
'Pull Requests' and 'Squash' will be on the roadmap for an updated version
Installing CODESYS Git
Start the CODESYS Installer (Start > CODESYS > CODESYS Installer),
Select the installation you wish to extend with git and press "Change",
In AddOns select the browse category,
Now enter Git in the search bar and start the search by pressing enter,
Select it and press install and follow the instructions,
Wait for the installation to complete,
Typical git flow
Initial setup is done a few times in the development cycle, but usually significantly less then the repeated flow, unless you like to tinker around much or you have a need for many git's
Add cForge Git repository
Add a new "Git" repository on a project where you are Admin via "Add New..." menu,
Once the Git repository has been added to cForge, you can use it to check in and out code as your "remote main"
Initialise remote main git see [[## Add cForge Git repository]]