Guide / Share and move

Diagram diff

See what changed between two versions of a diagram as two pictures, instead of two blocks of XML.

Pro

What it is

When you compare two versions of a .bpmn file, Penstock shows the two diagrams side by side: Before on the left, After on the right. Both are read-only.

Steps

Take a .bpmn file that is under version control.
Compare it with an earlier version.
Two diagrams are shown instead of two blocks of XML.

Compare in your tool

JetBrains

Penstock registers a diff tool with the IDE. Any comparison where one side is a BPMN file shows two diagrams: Compare with Revision, a commit in the Git log, or a shelved change.

VS Code

Right-click a .bpmn file in the Explorer or in Source Control and choose Compare with…, or run Penstock: Compare with…. Pick the older version: the committed one, a branch, or another file. Both drawings open side by side in a Penstock Diagram Diff tab, with what was added, removed, changed and moved picked out. Pro. The git side goes through VS Code's own git extension.

Command line

penstock diff before.bpmn after.bpmn lists added, removed and changed elements by name. It says only the drawing moved when that is all.
penstock diff main compares the working tree against a commit, branch or tag.
penstock diff main --images renders before and after with the changes coloured. Needs Pro.

Why it is a picture

The XML of a diagram holds the position of every shape and every bend of every flow. Move one task and the diff shows a dozen changed lines, and none of them says what the process now does. Run auto layout and every line changes. Penstock compares the two files as diagrams: it matches elements by their id, decides which are new, gone or different in meaning, and treats a change of position or size as its own thing.

What is compared

BPMN diagrams, .bpmn and .bpmn20.xml. A decision or a form has no visual diff.
Elements by id. An element whose id changed shows as removed on the left and added on the right.
Both versions are read as they are. Nothing is written to either file.

On the command line

Command	What it does	Writes	Tier
`penstock diff before.bpmn after.bpmn`	Lists the added, removed and changed elements, one line each, with type, name and id, and for a changed one the names of the attributes that differ. When only shapes moved it says Only the drawing moved and how many elements.	Nothing	Free
`penstock diff [ref] [paths]`	Compares the diagrams under the paths, or every diagram that changed, with the same diagram at a commit, branch or tag. Without a ref it uses `HEAD~1`. A diagram that is new since the ref is listed as new.	Nothing	Free
`penstock diff [ref] --images`	The same, and draws the pictures.	One `.before.svg` and one `.after.svg` per changed diagram, and one `.svg` per new one, in `.penstock/images` or the folder of `--out`	Pro, and Team in a pipeline

In the pictures a removed element is marked on the Before side, an added one on the After side, and a changed one on both. A repository is needed for a ref; outside one the command says so. A ref that does not exist is reported with its name. The pull request report and the review bot draw the same pictures. See Pipelines, reports and the bot.

Example, after a commit that renamed one task and ran auto layout:

$ penstock diff HEAD~1
src/orders/order.bpmn
  changed  UserTask "Approve order" Activity_approve (name)
  and 14 elements only moved on the canvas

What you see

Every changed element is outlined in a colour. The comparison is by meaning, not by text. Penstock reads both versions and sorts each element into a bucket:

Bucket	Shown on
Removed	The Before side
Added	The After side
Changed	Both sides
Only moved or resized	The After side, in its own colour

The last bucket is the useful one. A commit that only ran auto layout reads as what it is: everything moved, nothing changed in meaning.

A pull request report and the review bot use the same comparison. See Pipelines, reports and the bot.

What it does not do

It does not merge. It only shows the difference.
It does not compare DMN tables or forms.

Common problems

I see XML, not two diagrams.: The visual diff is a Pro feature. Without Pro you get the normal text diff of your tool. See Plans and licence.
Everything is marked as changed.: Check whether the commit reformatted the file. penstock fmt makes the XML stable so later diffs stay small.

Diagram diff

See also