First steps with CODESYS Git

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,
• Ready!

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"

Initial setup

• Initialise remote main git see [[## Add cForge Git repository]]
• Load project into CODESYS

• Initialise (create) local main git
  

• Stage/commit loaded project into local main
  

• Add remote main as a location in local main
  

• Push local main to the remote main
  

Keywords: create remote, load project, create local, commit local, add remote, push remote

Repeated flow

• Branch (copy) and checkout the local main into a new named branch for your first contribution, give it a descriptive name (e.g the goal of this branch)
  

• After completion, stage and commit the changes onto your current working branch
  

• Checkout the local main
  

• Merge the previous working branch into the local main,

• Stage/commit,
• Push local main into remote main,
• Ready!

Keywords: branch/checkout, code, stage/commit, merge, push

History overview

• This Tab shows an in depth historical overview of you current checkout
  

  • working branch named "Dev_PrimaryHost" has been created from the local main
  • In this branch, "FB_Payload_Old" has been deleted, staged and committed into "Dev_PrimaryHost"
  • After this the branch has been merged with "Local Main"

CODESYS svn to git migration

• Checkout from SVN
• Disconnect from SVN
• Git > Initialize Local repository
• Git > Remote > Add the remote git location you made in the previous step
• Git > stage/commit and push to the remote origin

Messages pane

Since CODESYS Git is a WYSIWYG editor, typing commands in a console window is unnecessary. The Message pane provides some detail on what is going on (not 1:1 commandline, but at least similar).

Future CODESYS Git features

I am not familiar with the roadmap, but an educated guess will surely be support for the following features listed here as most of these counterparts have been implemented in CODESYS SVN allready

• Free usage with CODESYS Forge,
• CODESYS Git SCRIPT API support,
• Create Pull Requests,
• merge --squash,
• blame,
• prune,
• rebase,
• clean,
• cherry-pick,
• bisect,
• Support for Git submodules,

And more features for sure 😃