Resolving Merge Conflicts in Archi's Model Repository Plugin

Introduction

The Model Repository plugin for Archi enables collaborative modeling by allowing multiple architects to work on the same ArchiMate model, version-controlled via Git. While this approach brings agility and transparency to architecture work, it also introduces the familiar challenge of merge conflicts—especially in larger teams or during rapid modeling sessions. Left unresolved, these conflicts can result in model corruption, loss of work, or inconsistencies.

This article provides a practical guide to understanding, detecting, and resolving merge conflicts when working with Archi's Git-based model repository plugin.

1. How Conflicts Occur in Archi

Archi stores models in a structured XML-based format within a Git repository. Each component (elements, views, folders) is saved as a separate XML file. Conflicts typically arise when:

• Two users modify the same view or element concurrently
• Structural changes (e.g., renaming or deleting folders) are made in parallel branches
• Auto-layout tools or bulk script edits touch many files simultaneously

2. Detecting a Merge Conflict

When merging a branch into main or pulling latest changes, Git will flag files that cannot be merged automatically. Archi will indicate this in the Repository window:

• Conflicted files appear with a red icon
• Git status shows “CONFLICT (content): Merge conflict in …”
• Archi prevents commit until all conflicts are resolved

3. Conflict Resolution Strategies

Manual XML Merge

• Use a diff/merge tool like Beyond Compare, WinMerge, or VS Code’s Git plugin
• Compare incoming vs local vs base version of the XML file
• Look for duplicated <element> or <relationship> nodes
• Remove duplicates and ensure UUIDs are intact

Use jArchi to Restore Clean Versions

• For complex model merges, jArchi can re-import known-good XML content
• Scripted validation can highlight missing references or inconsistencies

Fallback to Backup

• Always commit before merging to preserve your current state
• If a merge goes wrong, restore the pre-merge branch and retry using a rebase strategy

4. Recommended Merge Tools

These tools work well with Archi’s XML format:

• Beyond Compare: 3-way merges with clear visual diffs
• KDiff3: Free and scriptable for CI/CD environments
• VS Code + GitLens: Lightweight and intuitive for daily use

5. Preventing Conflicts

• Lock critical views during high-priority changes
• Split large models into separate logical repositories
• Encourage regular pulls and small commits
• Use feature branches and avoid direct commits to main/master
• Run jArchi validation scripts before pushing

6. Collaboration Workflow Recommendations

1. ✅ Pull changes before starting a modeling session
2. ✅ Use branches per feature or topic
3. ✅ Validate model consistency before pushing
4. ✅ Resolve merge conflicts outside of Archi (in Git tools)
5. ✅ Reopen Archi after merge to re-parse structure

Conclusion

Merge conflicts are a natural part of collaborative modeling in Archi, but with the right tooling, discipline, and backup strategies, they can be managed effectively. By understanding the structure of Archi’s XML files, using proper merge tools, and defining clear workflows, architects can maintain both speed and quality in distributed teams.

Keywords

Archi, Model Repository Plugin, Archi Git Conflicts, Archi Merge Conflict Resolution, Archi XML Format, jArchi Merge, Archi Collaborative Modeling, Git in Archi, Archi View Merge, ArchiMate Team Workflow