Using Git-Submodules in an AS-Project

Problem description

The open file system and the modularization options within Automation Studio make it possible to maintain project components such as programs, libraries or components of the configuration view in a base project and then use them in a machine project.

To distribute the project components, Git offers the system of Submoduls.

One of the main problems with the submodules is the fact that only complete repositories can be accessed. It is not possible to link individual files. A few possible solutions to the problems caused by this circumstance are shown here.

  • File references
  • Package references
  • Symnlink junctions

Solution 1 - File references

A Submodule-reository containing all files and folders of the logcial- as well as the physical-folder is included as submodule into the main project reprository.

Every file which is needed in the project, can now be referenced with a file rference in the Automation studio.

This mechanism is fully supported by the Automation studio and referenced files can be used and edited in Automation Studio in the same way as local files.

Advantages

  • Standard AS mechanism
  • Link is stored in the project
  • Perfect for a small amount of files
  • File references can be resolved when exporting the project

Disadvantages

  • Great effort with many files
  • Deleted, renamed and moved files in the submodule must be manually re-referenced

Solution 2 - Package references

A Submodule-reository containing all files and folders of the logcial- as well as the physical-folder is included as submodule into the main project reprository.

Instead of linking every single file, whole packages can be references as well. This mechanism is not offerd by the Automation studio toolbox, but can be achieved by manually editing the package (*.pkg) file

A reference in the package file can look as follows:

<Object Type="Package" Description="Submodule package">/Submodule/Logical/FolderXy</Object>

The logical- as well as the configuration-view can display this referenced package and contained files can also be edited.

Unfortunately, the Automation studio does not offer the possibility to change the file structure of referenced packages. It is therefore not possible to copy, move or rename files in this folder or to insert new files from the toolbox.

Automation Studio only allows these operations if they are local files of the project.

File changes within the referenced package can therefore only be made by manually adapting the package file.

A more or less tedious workaround for this problem is to store not only the necessary files but also the complete AS project in the submodule.

When making file changes, it is then possible to open the local project in the submodule, make the adjustments and then switch back to the machine project.

Advantages

  • Link is stored in the project
  • New, moved or deleted files in the submodule are transferred directly to the machine project

Disadvantages

  • The AS does not support file operations (Copy / Paste / Rename / Move / Insert from Toolbox)
  • Need to customize package files
  • Package references are not resolved when exporting the project

Solution 3 - Symlink

A Submodule-reository containing all files and folders of the logcial- as well as the physical-folder is included as submodule into the main project reprository.

Instead of referencing the files in the Automation studio project, a so called symlink can be made.

Symlinks are options offered by Windows to create links in the file system.
Links werden in verschiedenen Ausführungen angeboten:

  • Soft-Link (Most known mechanism top link files or folders (*.lnk))
  • Hard-Link (Kind of a synchronized file copy for files)
  • Junction (Hard-Link even for folders - kind of folder synchronization)

The mechanism of the junction can now be used to reference the packages of the submodule.
It can be linked in the command shell using the mkfile command.

mklink /J "\Logical\FolderXY" "\Submodule\Logical\FolderXY"

The difference of such a junction is mainly, that a tool does not see a difference between a normal directory and a directory linked as junction. So all AS-mechanisms work as if it were a local file.

Files can be copied, moved, deleted or added from the toolbox. Changes are directly synchronized to the folder in the submodule.

As it is a kind of a copy, changed in the file and the file structure are recognized in the main repository as well as in the submodule repository. To prevent this, the folder concerned must be entered in the .gitignore file. After that, changes are only committed and pushed to the submodule repository.

These links are not stored in the project. When copying or cloning the project, the link is lost and must be redefined by the command shell or a according script.

Advantages

  • New, moved or deleted files in the submodule are transferred directly to the machine project
  • The AS treats the files like local files
  • All AS mechanisms, including export, are supported

Disadvantages

  • Link is lost when copying or cloning the project
  • script needed which is called as git-hook or a pre-build script in the AS

PS: There would be more concept pictures available. However, the restrictions of the forum at my level do not allow me to post more pictures.

4 Likes

Great post!!

We use Symlinks also for mapp View package in Logical View where references aren’t allowed by B&R (e.g. in Media package). This is very useful if you want to manage your visualization components in modules.

To create the Symlinks after project path has changed we use prebuild scripts.