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 blogpost 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) headstart in understanding basic key concepts of Git.

Currently CODESYS Git usage requires a valid Professional Developer Edition or a Demo license (free). Please ask CODESYS to enable free usage in combination with cForge

General Terminology

1. Git: 'global information tracker' or more commonly 'git', is a 'container name' for a source code repository
2. Since 2020 'master' is being replaced with 'main', in this guide we will use 'main'
3. 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'
4. 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
5. Branch: A working branch or snapshot of 'Local Main' which acts as a point 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
6. Merge: the act of 'merging' changes from branch A into branch B. You should use this to update a local main with a development branch or to update working branches
7. Checkout: the act of selecting an active working branch, the ide will switch to this version so you can work in it
8. Stage: the act of preparing files and code changes on the current checkout.
9. Commit: Adds staged files and changes into the current checkout branch. A username, emailadres and a commit message are to provided onneach 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. Changes are always commited to the current checked out branch
10. 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.
11. 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).
12. Sync: The remote main and your local main should ideally stay synchronised (have the same content) and should be synced on a regular basis
13. 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 itself.

Currently I am not sure if cForge / CODESYS Git support pull requests yet but I am pretty sure 'Pull Requests' will be on the roadmap as will 'Squash'.

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

Initial setup

• initialise (create) remote main git
• 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

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

Repeated flow

• branch and checkout the local main into a new named branch for your first contribution
• 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
• push local main into remote main

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

Installing Git

1. Start the CODESYS installer,
2. Select the installation you wish to extend with git and press "Change",
3. In AddOns select the browse category,
4. Now enter Git in the search bar and start the search by pressing enter,
5. Select it and press install and follow the instructions,
6. Wait for the installation to complete,
7. Ready!

Add cForge Git repository

1. Add a new "Git" repository on a project where you are Admin via "Add New..." menu,
2. Once the Git repository has been added to cForge, you can use it to check in and out code

CODESYS svn to git migration

1. checkout from SVN
2. Disconnect from SVN
3. Git > Initialize Local repository
4. Git > Remote > Add the remote git location you made in the previous step
5. Git > stage/commit and push to the remote origin

Pull request vs Push

..

Squash

..