.gitignore file for AS projects

Share Info & Ideas
1

Below the content for an AFAIK complete .gitignore file for AS projects.

ATTENTION: I updated the file, since in the mappSafety CPU folder the file GLOBAL_VARIABLESTranslation_SF.xml seems to be required!

## Automation Studio
# Ignore AR versions as those are not considered part of the project
/AS/System/

# Ignore build results
/Binaries/

# Ignore debugging configurations (Watch,...)
/Diagnosis/

# But save the watch windows and task trace configurations (if it should stay in the repository) - optional, uncomment if needed
#!/Diagnosis/**/
#!/Diagnosis/**/*.PVM
#!/Diagnosis/**/*.tc

# mappSafety
#------------------
# Ignore DLFiles
/Physical/*/*/mappSafety/*/DLFiles/*

# Ignore CPU folder in mappSafety - ..\{ASprojectName}\Physical\{ConfigName}\{PLCname}\mappSafety\{SafetyProjectName}\C\PLC\R\CPU
/Physical/*/*/mappSafety/*/C/PLC/R/CPU/*
!/Physical/*/*/mappSafety/*/C/PLC/R/CPU/*.xml

# But include the required binary files
!/Physical/*/*/mappSafety/*/C/PLC/R/CPU/src.st1
!/Physical/*/*/mappSafety/*/C/PLC/R/CPU/tmp.sto

# Include all the safety related .set files - all the .set files in the Physical folder
!/Physical/**/*.set

# Ignore standard temp folder
/Temp/

# Ignore upgrades as those are not considered part of the project source code
/Upgrades/

# Ignore user settings file
/*.set

# Ignore is open indication
/*.isopen

# Ignore debug logs
/*/debug.log

# Ignore Conversion logs (AS2 to AS3)
/ConvertLog.txt

# Ignore more stuff to your liking
# ...

Also please make sure to always use a .gitattributes file containing:

* -text

which will disable the eol feature of git (docs), so it won’t mess up DTM, safety or firmware files… You could also use your git settings for it, but that would require for every developer to always mind his settings… It’s way easier to just add the .gitattributes file. More details

Happy coding!

7 Likes
2

Hello Marcel, can you, please, expand on the .gitattributes file ? I don’t use it right now, would like to know more.

I think it would solve an issue I am having right now, when I add the DTM files to my computer, all works, but when I pull changes from the git - others have the files saved elsewhere, I get this warning:
Snag_148a1b3

Thanks Jan

3

@fikejja1 git has an eol feature (core.autocrlf) making cross OS development easier by adapting the line endings to the OS of the user checking out.

You can disable it per repo / user / machine according to the git settings structure, which I don’t recommend, since everyone always has to make sure the settings are correct.

git config --global core.autocrlf false

The easier and better solution is, just to create a file in your project root directory - same as .gitignore - called .gitattributes and you just put * -text in it, which basically tells git to disable autocrlf (-text) for all files (*).

The .gitattributes file can be used for a lot of other things too, feel free to check the docs.

Best regards,
Marcel

3 Likes
4

In the past we experienced some problems when sharing projects via git and ignoring the AR files in /AS/System/.
The better option is to not store the runtime files in the project at all by unchecking the option ‘Save Automation Runtime support files to project’ in Project - Settings.
image

1 Like
5

ATTENTION: I updated the file, since in the mappSafety CPU folder the file GLOBAL_VARIABLESTranslation_SF.xml seems to be required!

Any chance B&R has a perfect example? :slight_smile:
There is a help page somewhere initially made for SVN which states what should be ignored. as far as I remember the complete safety CPU folder was on it?!

1 Like
6

I would suggest adding the following lines to “.gitattributes”

# Merge always manual to avoid the references getting destroyed
*.uad -merge
*.mpalarmxcore -merge
# Do not touch the .ext files
*.ext binary
1 Like
7

Do you have bad experience with .uad and .mpalarmxcore file merges?

8

Exactly in .uad it messes up the limits. I don’t exactly remember what was the case with
.mpalarmxcore.

1 Like
9

I’ve noticed problems when sharing projects through GitHub with DLFiles ignored. When a customer downloads the source code from GitHub and transfers, a safety project is not tranfsered to the PLC due to the missing DLFiles. This was an issue for us because the installing technician did not want to learn how to open SafeDesigner, log in, and compile the project.

Committing DLFiles solved this for me so that the safety project would be transferred after a GitHub download, without requiring a SafeDesigner build. Does anyone know if this is problematic or why exactly DLFiles is recommended to be ignored?

1 Like
10

That is the screenshot from the help [b8c69e5e-7579-4e41-b853-13cf9ccbef53] (sorry, I only have the german help :stuck_out_tongue:):

The only thing regarding ignoring is: Ignore the DLFiles folder xD

image
image877×1015 295 KB

I’ve heard a lot of things:

  • Versioning safety projects is not allowed
  • The safety project is only allowed as .zip in version control (not documented anywhere like this!)
  • The …/R/CPU folder should be ignored
  • …

But you will never receive a full answer xD

In your case it would be interesting why the safety project isn’t transferred! What generation are you using? mappSafety?

Best regards,
Marcel

11

We were using Safety Release 1.10

12

With mappSafety it’s a little bit different: There is the *.sfapp file which contains the project, so you always can transfer it using the mappSafety web interfaces. (Same with commissioning files)

For AsSafety I still think, there is a file which has the SafetyProject, and you should be able to transfer it without using the SafeDESIGNER, using the AsSafety library. I don’t remember the precise name right now… Is that what is not “transfered” as you wrote? Perhaps the AS somehow thinks that file is not valid if the DLFiles are missing?! Did you verify adding the DLFiles makes the AS transfer it?

13

Hello Marcel, thanks for posting this! Hopefully this will help to prevent possible issues when versioning AS projects with Git :slight_smile:
I think the .gitignore sample you have posted is close, but as far as I am aware, the DLFiles shouldn’t be ignored, as Brian has written in his post. I think all the recommendations in the help are SVN specific.

Since the safety projects are stored in form of binaries, they are generally not designed to be versioned using any version control system at all and the usage of SafeDESIGNER with Git is not officially supported.
However, this doesn’t mean that an AS project with Safety couldn’t be versioned using Git. The users just have to be aware of certain behaviors and limitations. Not all the limitations can be really reflected in the .gitignore file itself, but have to be kept in mind by the user.

Limitations of managing SafeDESIGNER projects in Git

The main limitations are caused by the fact, that most of the files from the SafeDESIGNER projects are stored in form of binaries. Git is not meant to work with binary files, but with text files, so not all the functionality is available.

Comparing files

It is not possible to compare binary files and it is not possible to see changes made in them. However, binary files can still be versioned by Git, so it is possible for example to revert to a previous version. In this case, it is even more important to write proper commit messages explaining the changes, as they can’t be seen in the file.

Merging files

Because of the nature of binary files, it is also not possible to merge any changes. Furthermore, merging is not even allowed from the safety point of view.

Parallel work

The impossibility to merge also means, that there is no parallel work on the SafeDESIGNER project possible or allowed. This means that only one person at a time is permitted to work on Safety!

Special considerations for managing SafeDESIGNER projects in Git

Again, most of the special considerations are based on the fact, that the Safety project is stored in a form of binary files. As already mentioned, it is therefore not possible to see the changes and compare the versions of the file. Some of the considerations are reflected in the .gitignore file, some should be kept in mind by the user.

The following points have to be considered:

  1. The DLFiles folder should not be excluded when using Git.
  • Even though the Automation Help is mentioning, that this folder should be excluded from version control, it is only necessary to exclude it when using Subversion!
  • The DLFiles folder contains binary files for the SafeLOGIC. If these files are missing, it is not possible to build the AS project without also rebuilding the SafeDESIGNER project!
  • Path in mapp Safety: …{ASprojectName}\Physical{ConfigName}{PLCname}\mappSafety{SafetyProjectName}\DLFiles
  • Path in Legacy Safety: …{ASprojectName}\Physical{ConfigName}{PLCname}{SafetyProjectName}\DLFiles
  1. The following CPU folder must be excluded, since it contains debug files that change every time the SafeDESIGNER project is compiled.
  • Path in mapp Safety: …{ASprojectName}\Physical{ConfigName}{PLCname}\mappSafety{SafetyProjectName}\C\PLC\R\CPU
  • Path in Legacy Safety: …{ASprojectName}\Physical{ConfigName}{PLCname}{SafetyProjectName}\C\PLC\R\CPU
  1. Binary files src.st1 and tmp.sto from the CPU folder above (point #2) must be included!
  • The files change every time SafeDESIGNER is opened and closed. These changes should be manually discarded.
  1. All the .set files within the Safety project must be included.
  • There are also 2 .set files in within the CPU folder mentioned in the point #2 above!
  1. All the POUs must be included.
  • Path in mapp Safety: …{ASprojectName}\Physical{ConfigName}{PLCname}\mappSafety{SafetyProjectName}\POE
  • Path in Legacy Safety: …{ASprojectName}\Physical{ConfigName}{PLCname}{SafetyProjectName}\POE
  1. Merging changes in a SafeDESIGNER project is not possible. Only one person can work on the SafeDESIGNER project at a time.

Keep in mind, that these rules will only reduce the number of changed files after opening or compiling a SafeDESIGNER project, but they will not prevent them completely.

Committing

Special attention has to be taken when committing SafeDESIGNER project files. Some of the files in the Safety folder will change by just opening the SafeDESIGNER, without making any actual change in the project. These changes definitely shouldn’t be committed, but since it is not possible to see the difference between the files, the user has to be aware of what was actually done. Don’t commit files, when there was no intentional change made!

Committing complete SafeDESIGNER project

Even though it is not how Git is supposed to be used, it is also possible to simply include the complete Safety project in the versioning, without ignoring any of it’s files and committing all the changes instead. This could result in a cluttered history with many unnecessary changes, which can’t be compared, but as long as the previous guidelines about parallel work and merging are followed, the Safety project shouldn’t be affected.

This approach has it’s downsides, but since even following all the considerations mentioned in the previous chapter doesn’t fully solve all the issues and doesn’t get rid of all the changing files, this is a valid and probably the easiest option how to handle safety projects in Git.

These are all the guidelines which we were able to collect. Sorry for the wall of text, but maybe some of you will find the information interesting.

TL;DR For Safety projects, either use the .gitignore pattern from the initial post (apart from the DLFiles part), or don’t ignore the Safety part at all. And always be aware of what you are committing :slight_smile:

2 Likes
14

Ignoring files can’t be VC specific, can it? So is the help just outdated or plain wrong? :slight_smile:

Best regards!

15

When I ignored this folder completely, it broke my project. When I checked it out in a different folder and opened the SD Global Variables, I got a error message and it just closed. compiling also not possible anymore… So I think there might be an issue. I’ll create a ticket.

image

I think it was this one “GLOBAL_VARIABLESTranslation_SF.xml”, I just renamed it and I got the error!

16

See points 3. and 4.
It is not possible to simply ignore the complete CPU folder. Even in there are some files, which have to stay in.

It is possible that we are missing this “GLOBAL_VARIABLESTranslation_SF.xml” has to be included rule. I have heard about it the first time from you. But you might be totally right with that one.

But once again, even if we get all these rules together, I am afraid it still doesn’t completely solve the issue and there will still be some changes shown in git, even though there was no actual change in the safety project (for example when opening the SafeDESIGNER). So I guess that is the reason, why some users just choose to include the complete safety project, without ignoring any parts of it.

1 Like