L11 Version Control Diagrams

title: "Version Control for Diagrams — Git Workflows for Visuals" weight: 11 description: "Learn version control strategies for diagram-as-code: storing sources in Git, diffing diagram changes, pull request workflows, merge conflict resolution, and branching strategies for visuals." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagram-as-code] }

Version control for diagrams means storing text-based diagram sources in Git alongside code, enabling diff review, pull request workflows, and automated rendering for visual documentation.

In this lesson, you will learn Git workflows for diagrams, how to diff diagram changes, handle merge conflicts, structure repositories, and review diagram changes in pull requests.

What You'll Learn

You will learn how to store diagrams in Git, review diagram changes in pull requests, handle merge conflicts in diagram files, structure diagram directories, and automate diagram workflows.

Why It Matters

The primary benefit of diagram-as-code is version control. Without proper Git workflows, you lose the advantages of diff review, change history, and collaborative editing.

Real-World Use

DodaTech requires all diagram source files to be in the same repository as code. Pull requests with architecture changes must include diagram updates. Reviewers verify both code and diagrams.

flowchart LR
  A[Edit Diagram Source] --> B[Git Add]
  B --> C[Git Commit]
  C --> D[Push to Branch]
  D --> E[Create PR]
  E --> F[Review Diff]
  F --> G{Approved?}
  G -->|Yes| H[Merge to Main]
  G -->|No| I[Request Changes]
  I --> A
  H --> J[CI Renders]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

def diagram_directory_structure(project_name):
    """Generate recommended directory structure for diagrams."""
    return {
        f"{project_name}/": {
            "docs/": {
                "diagrams/": {
                    "src/": "Source files (.mmd, .puml, .d2)",
                    "rendered/": "Generated output (.svg, .png)",
                    "README.md": "Diagram conventions guide",
                }
            }
        }
    }

structure = diagram_directory_structure("dodazip")
print(structure)

def create_diagram_commit_message(diagram_name, change_type):
    """Generate a structured commit message for diagram changes."""
    prefix = {
        "added": "docs(diagrams): add",
        "updated": "docs(diagrams): update",
        "removed": "docs(diagrams): remove",
        "fixed": "docs(diagrams): fix",
    }
    return f"{prefix.get(change_type, 'docs(diagrams)')} {diagram_name}"

print(create_diagram_commit_message("architecture-overview", "updated"))

def resolve_diagram_merge_conflict(base, ours, theirs):
    """Basic merge conflict resolution for diagram files."""
    if base == ours:
        return theirs
    if base == theirs:
        return ours
    return None  # Manual resolution required

Teacher Mindset

Think of diagram version control as the same discipline as code version control. You would not commit untested code. Do not commit unrendered diagrams. You would not merge a PR without reviewing code changes. Do not merge a PR without reviewing diagram changes. The same standards apply. Treat diagrams as first-class citizens in your repository.

Common Mistakes in Version Control for Diagrams

1. Committing Only Rendered Output

If you commit only PNG files, nobody can diff changes or edit the diagram later. Always commit source files. Generate rendered output during build.

2. Large Binary Diagram Files

Binary image files bloat repositories. Use .gitignore for large generated files. Store only source text files and small rendered images.

3. No Diagram Changes in Architecture PRs

A pull request that changes system architecture without updating diagrams breaks the documentation-review connection. Require diagram updates.

4. Merge Conflicts in Generated Files

Generated diagram images should not be committed to avoid merge conflicts. If they must be committed, resolve them last after source conflicts.

5. Inconsistent Directory Structure

Diagrams scattered across the repository are hard to find. Use a standard directory structure. Document it in a README.

Practice Questions

1. What should be committed to Git — source or rendered diagrams? Both. Commit source files for editing and diffing. Commit rendered output for documentation builds. Use .gitignore for intermediate build artifacts.

2. How do you review diagram changes in a pull request? GitHub renders Mermaid diff natively for .mmd files. For other formats, review the syntax diff. CI should generate a preview comment with before-after images.

3. How do you handle merge conflicts in diagram files? Mermaid and D2 files are plain text and merge like code. PlantUML files also merge as text. Understand what changed in each version. Manually resolve if automatic merge fails.

4. What directory structure works best for diagram sources? docs/diagrams/src/ for source files, docs/diagrams/rendered/ for build output. Name files descriptively: architecture-overview.mmd, auth-sequence.puml.

5. Challenge: Restructure your documentation repository to include a diagrams directory with source and rendered subdirectories. Move existing diagram files to the new structure. Update your CI pipeline to render from the new paths.

FAQ

Mini Project

Set up a Git repository with a proper diagram directory structure. Create a pre-commit hook that validates diagram syntax. Configure CI to render diagrams on push. Document the workflow in CONTRIBUTING.md.

What's Next

DiAC Project in the final lesson.