Draw The Diff

Jan Stępień

Many of our customers use draw.io, a popular web-based tool for drawing diagrams. It comes built-in with certain commercial wikis and text editors. You can get it as an Electron desktop application and save resulting diagrams as XML files.

Those of you who checked your draw.io files into a Git repository might have noticed a problem. With compression enabled, the XML files that the diagramming tool produces are often a thin envelope around a binary blob. This is opaque to Git’s text-based diff algorithms and prevents us from quickly telling what has changed between two revisions of a diagram. Having failed to find a good text-based solution, we’ve decided to present differences graphically.

The solution involves compare from the ImageMagick suite and requires you to have draw.io installed locally. Scripts below assume macOS, but porting them to other systems shouldn’t pose a challenge.

#!/bin/bash

set -e -o pipefail

Let’s consider file doc/arch.drawio. We want to visualise how it changed between revisions 11111 and 22222.

path=doc/arch.drawio
old=11111
new=22222

We start by pulling the XML blobs out of the Git repository. Let’s use a temporary directory for all the files we create.

old_path=$(mktemp -t old)
new_path=$(mktemp -t new)
diff_path=$(mktemp -t diff)

git show "$old:$path" > $old_path
git show "$new:$path" > $new_path

Now we use draw.io to turn XML files into PNG images.

drawio=/Applications/draw.io.app/Contents/MacOS/draw.io

$drawio -x -f png -o $old_path.png $old_path
$drawio -x -f png -o $new_path.png $new_path

Then we invoke compare to render the difference. Notice that compare—similarly to diff—might return a non-zero code to signal that input files aren’t identical. We ignore that by conditionally invoking true.

compare $old_path.png $new_path.png -compose src $diff_path.png || true

We now can open all three files: both rendered diagrams and the difference between them.

open $old_path.png $new_path.png $diff_path.png

There’s a lot that we could improve here. We could account for the viewport of the input files changing. We could blur the diff and overlay it on top of the source files. We could create a web-based viewer with a slider. We could take an entirely different approach, decompress the binary blob, pretty print it, and compare it textually. But what we have is more than enough for our purposes.

We hope this helps.