Version Control for UML Models

Introduction: Why Version Control Your UML Models?

In Java development, version control with Git is second nature for code — but what about your UML diagrams? If you're collaborating on class diagrams, use case flows, or sequence logic, those visual artifacts need to evolve just like code does. That’s where version control for UML models becomes essential.

In this guide, we’ll explore how to manage UML models in Git, handle changes safely, collaborate across teams, and integrate diagram versioning into your development workflow. We’ll use examples from school management systems to keep it practical and relatable.

Understanding How UML Tools Store Models

Before diving into Git commands, it’s important to understand how different UML tools store their diagrams:

• StarUML – Saves projects as .mdj (JSON format)
• PlantUML – Stores diagrams in plain text (markdown-like syntax)
• Lucidchart/Draw.io – Uses XML or binary exports, best used with shared cloud links

Tip: Choose a UML tool with version-friendly output formats (JSON, text, XML) if you're committing diagrams to Git.

Step-by-Step: Using Git to Version UML Diagrams

Step 1: Set Up a Git Repo

git init uml-school-project
cd uml-school-project

Create folders for organization:

mkdir diagrams
mkdir docs

Step 2: Add UML Files

Assume you're using StarUML and saved your project as school-grading.mdj. Move it into your repo:

mv ~/Downloads/school-grading.mdj diagrams/
git add diagrams/school-grading.mdj
git commit -m "Initial UML model with student and teacher classes"

Step 3: Collaborate and Track Changes

Once in Git, any future edits to the model can be tracked like source code:

git status
git diff diagrams/school-grading.mdj
git commit -am "Updated class diagram to add Course and Enrollment"

Note: StarUML uses a JSON structure internally. Diffs will show property-level changes, making reviews possible but verbose.

PlantUML: The Best Fit for Git

If you want fully diffable, mergeable, and text-based UML, PlantUML is your best friend.

Example PlantUML Diagram

@startuml
class Student {
    name : String
    grades : List
}

class Grade {
    subject : String
    score : int
}

Student "1" -- "*" Grade
@enduml

Stored in a .puml file, this format is perfect for:

• Pull requests with readable diffs
• Code reviews
• Documentation versioning

git add diagrams/student-system.puml
git commit -m "Added Grade relationship to Student"

Using Branches to Manage Diagram Versions

Branching works just as well for diagrams as it does for Java code. You can use branches for:

• Feature Modeling: e.g., feature/payment-workflow
• Refactoring Diagrams: e.g., refactor/class-diagram-cleanup
• Parallel Exploration: Trying alternative architectures

Example

git checkout -b feature/enrollment-sequence

Make changes to a Sequence Diagram modeling how a student enrolls in a course, commit, then open a pull request for team review.

Diff and Merge: What’s Possible and What’s Not

StarUML Files

• Changes are JSON-based
• Diffs are visible but not always human-readable
• Manual merges may be risky — prefer branch per feature

PlantUML Files

• Diffs are clean and readable
• Standard Git merge tools work well
• Best for collaborative modeling

Best Practices for UML Version Control

• Commit frequently: Don’t wait to finish a whole diagram. Incremental saves improve visibility.
• Write clear commit messages: “Added login sequence diagram” is more helpful than “update.”
• Use README files: Document what each UML file represents and how it’s organized.
• Store exports separately: Export PNG/PDF versions into a /docs folder; don’t track them alongside source UML files.

Example Directory Structure

uml-school-project/
├── diagrams/
│   ├── student-system.puml
│   ├── school-grading.mdj
├── docs/
│   ├── class-diagram.png
│   └── login-sequence.pdf
├── README.md

When Not to Version UML Files

There are cases when version control isn't necessary for UML:

• If diagrams are throwaway sketches or drafts
• If you're working solo on a small project
• If the tool exports binary-only files (e.g., proprietary formats)

In those cases, use diagrams as documentation, not version-controlled artifacts.

Conclusion: Bring UML into Your Git Workflow

Version control is not just for code — it’s for collaboration, evolution, and clarity. When you treat your UML diagrams like any other asset in a Java project, you bring them into the heart of your development workflow. That means fewer surprises, better peer reviews, and a cleaner design history.

Start simple: version a single class diagram. Use branches for changes. Prefer text-based formats when you can. And above all, model with purpose — and version with confidence.