Troubleshooting
Fixing an HMI Project That Fails After a Git Clone
Short answer
The clone is broken because a referenced bitmap .PLK was never committed, not because of an ignore rule. Read the HMI Output tab for the exact filename, prove the file is untracked with git check-ignore followed by git ls-files, then restore and commit it and re-test from a clean clone. Track the .tgt and .def files for the HMI BIOS version as well.
On this page
- What the two tabs are telling you
- Ignored and untracked are different failures
- Restore the asset, then prove it on a clean clone
- Worked example: count the gap, then close it
- What belongs in the repository
- Target and definition files across a BIOS update
- The RSM file: test it, do not weigh it
- From clean clone to running panel
- Questions asked
You cloned the repository, opened it in EcoStruxure Machine Expert - HVAC, and the Display tab shows no project details at all. In the reported case, an M172 HMI project, the cause was one bitmap .PLK file that no ignore rule excluded and nobody had ever staged; restoring that single file made the project load. So run the two-command check below before you touch one pattern in .gitignore. The same empty Display tab also appears when the .tgt and .def files for a newer HMI BIOS are missing from the commit, and that failure needs a different repair.
What the two tabs are telling you #
The Display tab reports the symptom; the Output tab names the cause. An empty Display view means the HMI project did not load completely, and it never tells you which file is absent. On load, the HMI Output tab prints a missing-file message with the exact path, so work from that filename in this order:
- No project details in Display after a clone: the project loaded partially or not at all. Read the HMI Output tab and record the exact path it names.
- Output names a bitmap
.PLK: a referenced image asset is unavailable. Check whether it is ignored, then whether it is tracked. git check-ignorefinds no rule andgit ls-filesfinds no entry: the file was never committed. Retrieve it and commit it; editing ignore patterns will not help.- The repository downloads to an updated system but the project will not open there: the
.tgtand.deffiles for that HMI BIOS version are missing. Track the versioned files.
Ignored and untracked are different failures #
Git leaves a file out of a clone for exactly two reasons: an ignore rule kept it out of the index, or nobody ever staged it. Two commands separate the cases, run with the exact path from the Output message.
git check-ignore -v -- path/to/file.PLK
Documented behavior: exit status 0 with one line naming the matching pattern and its source file when a rule matches; exit status 1 with no output when nothing matches.
git ls-files --error-unmatch -- path/to/file.PLK
Documented behavior: the path prints and the command succeeds when Git tracks the file; it fails with an error when the path is not in the index.
The decision: edit .gitignore only when check-ignore returns a match. When check-ignore is silent and ls-files errors, the file is untracked, the repair is retrieval plus commit, and no ignore edit changes that. That silent-and-error state was the exact condition of the missing bitmap, which is why a carefully built ignore list looked guilty and was not.
Restore the asset, then prove it on a clean clone #
- Recover the named file from the source project or a known-good repository copy. The committed path and filename must match the reference character for character.
git addthe file, commit, and push.- Clone that commit into a brand-new directory. The broken working copy can mask the result; a fresh clone is the honest test.
- Open the project. The pass condition is an Output tab with no missing-file message and a Display tab showing project details again.
Worked example: count the gap, then close it #
Illustrative numbers, with the method as the deliverable. Suppose the Display project imports 34 images, and a fresh clone reports git ls-files -- *.PLK returning 33 tracked files. Counted imports minus tracked assets: 34 - 33 = 1 file missing from the commit. The Output tab names it — call it Images/pump_icon.PLK for this example, an illustrative name. After git add Images/pump_icon.PLK and a commit, the same count returns 34, and 34 - 34 = 0: a clone of that commit loads. Run the count whenever images change. Counted imports must equal tracked .PLK files, and every unit of difference is one file to recover from the source project.
What belongs in the repository #
The reported project runs with this ignore set, and none of its patterns matches a .PLK:
| Pattern | Commit it? | What it covers |
|---|---|---|
**/Build, **/*.bin, **/*.a, **/*.CFN |
No | Regenerated build outputs |
**/Download |
No | Generated download packages |
*/HMI/docImages |
No | Documentation images |
**/PreviousVersions |
No | The tool's own version snapshots |
**/*.wkpx |
No | Workspace file |
USBCWDXHybrid_28IO, USBCWDXHybrid_42IO |
No | Named USB export files |
**/Backup, **/ChangeTargetBackup |
No | Backup directories |
**/*.imgx.simul, **/*.WKSX |
No | Simulation files |
Three asset groups must stay tracked regardless:
- Every
.PLKthe project references. The Display editor stores each imported image as a separate.PLKin its internal image format, and the project will not load without the ones it points to. - The
.tgtand.deffiles for each HMI BIOS version the project must open against. - The
.RSMfile, until the test in the next section clears it.
Decision on the ignore set: keep it. It covers build, backup, workspace and simulation artifacts — bulky binaries that regenerate — and it leaves referenced assets alone. Never add *.PLK to it on the assumption that images are disposable; a referenced bitmap is a load-bearing file.
Target and definition files across a BIOS update #
The second way a clone fails has nothing to do with images. An EcoStruxure update ships new HMI files for a new BIOS version, and the naming carries the version: FreeAdvance_HMI_596p9.def beside a newer FreeAdvance_HMI_596p11.def, with matching .tgt files. If the pair the project needs is not in the commit, the repository still downloads to the alternate system, but the project will not open there. A completed download is not the pass condition; the project opening functionally is.
Decision: when the engineering software updates, add the new .tgt and .def pair in the same commit that records the update, keep the older pair while any system still builds against it, and re-run the clean-clone test on the alternate system before calling the repository portable.
The RSM file: test it, do not weigh it #
The .RSM file is large and Git stores it as a binary blob, so every change lands in history as a whole new file. That is a repository-housekeeping complaint, not evidence the file is disposable, and the failure report does not identify its role. Decision: keep it tracked. Exclude it only after a test passes — remove it on a branch, clone that commit into a clean directory, open the project, watch the Output tab, then repeat on the alternate system with the workflow you actually run. Any missing-file message and the file goes back in and stays.
From clean clone to running panel #
Once a fresh clone opens with a clean Output tab, the repository is whole and what remains is transfer, not source control. Run the restored project through testing HMI simulation against a live PLC before pushing it to hardware. If the panel answers but the transfer aborts, you have left repository territory; the next layer is why an HMI is detected but the project download fails. A repository that opens on any workstation is also what makes how one spare HMI panel covers seven machines workable, because the spare takes whichever complete project the machine needs. One care point: load a rebuilt project to a panel only when the machine is in a state where changed screens cannot surprise an operator mid-cycle, and agree that timing with whoever runs the line.
Questions asked
Where does the missing .PLK come from if the clone is the only copy I have?
The workstation that last built the project still has the file in its working tree, because the editor wrote it there when the image was imported, whether or not anyone staged it. If that machine is gone, re-import the original image in the Display editor, which writes a new .PLK, and commit it at the exact referenced path. An older repository copy or a project backup are the remaining sources.
Does git check-ignore also tell me whether a file is tracked?
No. It answers one question: whether an ignore rule matches the path, exiting 0 with the matching pattern or 1 with nothing. Tracking is a separate question for git ls-files --error-unmatch, which errors when the path is absent from the index. Running only one of the two commands is how teams end up blaming the ignore file for a file that was simply never staged.
The project opens on my updated workstation but not on the older one. Same cause?
Yes, that is the same gap in the other direction. The older system needs the older target and definition pair, for example FreeAdvance_HMI_596p9.def, while the updated workstation also carries FreeAdvance_HMI_596p11.def. Keep both pairs tracked and each system opens the project against the BIOS version it runs.
Are .PLK files binary, and does that matter for Git?
They are the Display editor's internal image format, so Git handles them as binary: no line-level diffs, and every change stored as a whole new file. That affects repository size, never whether the file is required. A referenced .PLK is a load-bearing asset, so commit it like any source file and spend your housekeeping effort on true build outputs.
How do I audit what the ignore set currently catches?
Run git status --ignored in the source working tree: it lists every file the current patterns catch, which is the fastest audit of what your ignore set really does. Then test each candidate pattern with git check-ignore against the paths the project references. A pattern is safe only when it matches regenerated outputs and never matches a referenced asset.