Starting a new Repository

The repository is a location to store files and information about those files, including a history of the changes made. We use GitHub for our examples and SPT Libraries because it provides us with an online location that can be easily accessed from anywhere and by anyone. When starting a new repository for a project some simple planning should be done, and having a standard design for all your repositories can make them easier to interact with.

One of the first items to be added to the repo should be the .gitignore file. If the ignore file is added after a file(s) that is to be ignored, then that file(s) must be dealt with. The .gitignore file is used in order to not save files that change frequently in the background, and also files that you might want to save in a different repository such as libraries. There are also some files that are specific to the user environment and therefore each programmer should have their own local version of these files. The .gitignore file for the SPT_XPlanar_Demo is a good starter file: https://github.com/Beckhoff-USA-Community/SPT_XPlanar_Demo/blob/master/.gitignore or you can create your own at: https://www.toptal.com/developers/gitignore. Further details about the contents of the gitignore file can be found below in the Sample gitignore file.

The next point to consider is branches and how you will use them. Currently the default branch for a new repo on GitHub is main. Branches are a great way to make a copy of the existing repo and then try something, if it works then it can be merged back into the main branch, if not then it can be abandoned until later or deleted. Major branches can be made for Release, Development, and many other reasons. From the major branches it is also possible to create additional branches for specific tasks or features.

Possibility 1: If using some form of tracking for work items such as Azure DevOps the branches could be names based on the ID of the Work item. This makes searching for branches easier but is less human readable. However, it does create a consistent user interface and adds clarity between the work item and branch associated with it.

Possibility 2: Name the branches based on the task to be done. For smaller projects and teams this can work well, especially if the branches are merged back in and deleted afterwards. But this can be a bit challenging as projects and teams grow.

Possibility 3: Create folders under a branch, and then branch again as needed. It has been my preference to create a folder and name it after the work item, and then create branched under the folder for the task being done. A work item in Azure can have several child tasks assigned to it; therefore, the folder can be named for the work item number and the branch for the specific task.

For example, let’s assume there is a work item ‘123 JSON additional features’, and it has tasks ‘read struct’ and ‘write struct’. A folder on the development branch could be named 123, with a branch under it for each task. All of this design depends on personal preferences and how your project is managed, but having some consistency between your work log and your repository can really help.

Something that is nice to have would be a readme file that includes information about what the project is for and any dependencies on external resources that are needed. Also including what version of software was used in the development of the project can be helpful.

Sample gitignore file

Note

Below is a good starting point for creating a gitnore file. These files are simple text files that can be opened in any text editor.

# Any text following this symbol is a comment and will be ignored
## Multiple # are just used for formatting a comment

The starting location of the files to be ignored is the location of the .gitignore file Entire folders can be ignore by using the folder name followed by a /

folderName/

Note

Be careful with this as it is recursive and will ignore all folders and subfolders that match that name.

Specific files can be ignored by using the file name with its extension

Sample.txt

To ignore all files of a specific type you can use the wildcard. The below will ignore all backup files.

*.bak

There are times when we generally want to ignore all files of a type, except for some specific ones. The tmc files that we use for the Event Logger is an example of this. Most of the tmc files within the project folder are created and managed by TwinCAT so we could add *.tmc to the gitignore file. However this can cause some problems. Therefore we can specifically include certain tmc files after ignore them in general. By adding a ! to the front of the file name, git knows that that specific file should be included, even though the extension has been ignored.

*.tmc
!myEvents.tmc

Note

Don't include the tmc-file rule if either of the following is true:

1. You have TwinCAT C++ projects, as the information in the TMC-file is created manually for the C++ projects (in that case, only (manually) ignore the tmc-files for the PLC projects)

2. You have created a standalone PLC-project and added events to it, as these are stored in the TMC-file.

3. Shared tmc files are used to exchange data types that should be persisted in the project

As a place to start you can copy everything below into your .gitignore file. However it should be expected that this file will need to be customized to your specific situation and needs. For a more exhaustive list of possibilities www.toptal.io can be used to generate a file that includes both TwinCAT 3 and Visual Studio files.

# Visual Studio Files
*.bak
*.sln
*.suo
*.~u
.vs
UpgradeLog.htm

# TwinCAT Files
*.sln

## .tpy file can be ignored. They are a holdover from CoDeSys and aren't used much by beckhoff
### Source: https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_sourcecontrol/18014398915785483.html&id=
*.tpy

## Compilation Process Artifact
.tmcRefac

## TwinCAT Archive Formats
*.tnzip
*.tszip
*.tfzip

## Build Files
_CompileInfo
_Boot
_Libraries

## TwinCAT Licence Files (Machine Specific)
TrialLicense.tclrs

## Project Specific Files (Optional)
### Add folder or file path(s)