Skip to content

Development Workflow

Jump to bottom
Dale Thomas edited this page Mar 16, 2026 · 1 revision

Development Workflow

This page covers how to set up your development machine for contributing to ArfBotOS, specifically the git workflow for tracking CODESYS project changes in a readable way.

Overview

The CODESYS project is stored as Codesys/ArfBot.project. This file is a binary-like format that git cannot meaningfully diff. To solve this, the repository maintains a companion file Codesys/ArfBot.xml — a PLCopen XML export of the same project — which git can diff cleanly. A normalizer script strips volatile metadata (timestamps, internal checksums, GUIDs) so that only real code changes appear in the diff.

A pre-commit hook enforces that both files are always committed together, so the XML always reflects the state of the project.

Prerequisites

One-Time Machine Setup

This only needs to be done once per development machine.

  1. Open a terminal and navigate to the codesys-git-diff folder inside the repo:
cd ArfBotOS\codesys-git-diff
  1. Run the setup script:
setup_codesys_git_diff.bat

This will:

  • Register the XML normalizer as a git diff driver in your global ~/.gitconfig
  • Activate the pre-commit hook that enforces .project and .xml are committed together
  • Verify that git and Python are available on your PATH

Note: The normalizer script must stay at the path where you ran setup. If you move the repo, re-run the setup script.

Daily Workflow

Making changes

  1. Open Codesys/ArfBot.project in CODESYS and make your changes.
  2. Build the project to verify there are no errors (Build → Generate Code).

Exporting the XML

Before committing, export the PLCopen XML using the built-in CODESYS menu:

  1. From the menu bar, click Project → Export PLCopenXML...
  2. In the export dialog, click Select > to select all objects, then click OK
  3. In the file save dialog, navigate to the Codesys/ folder, confirm the filename is ArfBot.xml, and click Save (overwriting the existing file)

Note: The XML is for readable diffs only — it is not a full backup. Always use the .project file for reverting changes (see Reverting Changes below).

Committing

Stage and commit both files together:

git add Codesys/ArfBot.project Codesys/ArfBot.xml
git commit -m "your message here"

If you try to commit ArfBot.project without ArfBot.xml, the pre-commit hook will block the commit and remind you to run the export script first:

✗ Commit blocked: Codesys/ArfBot.project is staged but Codesys/ArfBot.xml is not.

  Steps to fix:
    1. In CODESYS: Project → Export PLCopenXML... → OK
       → save as Codesys/ArfBot.xml
    2. git add Codesys/ArfBot.xml
    3. git commit

Viewing diffs

Once set up, git diff automatically shows clean, human-readable diffs of the PLC code:

git diff HEAD~1 HEAD -- Codesys/ArfBot.xml

Changes to variable declarations, ST code, task configuration, and data types all show as clear line-by-line diffs. Internal CODESYS metadata that changes on every save is automatically stripped.

Reverting Changes

To revert the CODESYS project to a previous commit, check out the .project file and reopen it in CODESYS:

git checkout <commit-hash> -- Codesys/ArfBot.project

Then open Codesys/ArfBot.project in CODESYS. The XML is not used for reverting — it is a diff artifact only.

Updating the Normalizer

If codesys_xml_normalize.py is updated (e.g. to strip new noise attributes), the git diff cache must be cleared so git re-processes existing files with the new script. Run this once from inside the repo:

git update-ref -d refs/notes/textconv/codesys-xml

Files Reference

File Purpose
Codesys/ArfBot.project CODESYS project — source of truth, use for reverting
Codesys/ArfBot.xml PLCopen XML export — use for readable git diffs
codesys-git-diff/codesys_xml_normalize.py Normalizer run by git before diffing
codesys-git-diff/setup_codesys_git_diff.bat One-time machine setup script
.githooks/pre-commit Enforces .project and .xml are committed together
.gitattributes Tells git to use the normalizer for .xml files

Clone this wiki locally