DunneFlow · Tutorial

Compare two versions

Seal a snapshot of an older tree, analyse a newer one into the same program, and read which routines behave differently.

Available20 min· Intermediate· DunneFlow 0.2.0

A text diff tells you which lines moved. In this tutorial you make DunneFlow tell you which routines behave differently: what they call, touch, take or return. You analyse an older copy of a project, seal it, analyse the current copy into the same program, and read the comparison.

You'll need#

DunneFlow, from source or the application. Commands are shown as uv run dunneflow; with the application, use its command-line program instead (see The command line) and your maps folder instead of output/.
Two directories holding two versions of the same project. With git, a worktree is the cheapest way (step 1). They can also be two unrelated drops with no shared history.

Steps#

Get the older tree. From your git clone at ~/code/some-project, check out an older commit or tag into its own directory, named for what it is:
```
git -C ~/code/some-project worktree add ~/code/some-project-2026-09-08 <commit-or-tag>
```
DunneFlow records the directory's name, so a date or tag in it is how you will recognise this version later.

Analyse the older tree.

uv run dunneflow analyze ~/code/some-project-2026-09-08/src --name some-project

Seal it. Sealing keeps this snapshot so the next analysis lands beside it rather than replacing it.
```
uv run dunneflow revisions output/some-project \
    --seal --label "some-project - 2026-09-08"
```

Analyse the newer tree into the same program.

uv run dunneflow analyze ~/code/some-project/src --name some-project

Check what the program holds.
```
uv run dunneflow revisions output/some-project
```
You should see one WORKING snapshot and one FOR_COMPARISON snapshot carrying your label.
Open the dashboard.
```
uv run dunneflow serve output/some-project
```
A program with two versions opens comparing them. The version strip under the top bar names both.
Set the direction. DunneFlow does not know which version is newer; it only knows when it read each one. If both state comparable version numbers it uses them; otherwise the strip says assuming the compared version is newer. If that is wrong, click it to flip. This decides whether changed routines read as arrived or gone.
Open Changes. In the navigator, open Changes, then The whole comparison. Start with behave differently: these routines do something different now. Then look at edited only, whose text changed but whose behaviour did not.
Read one routine's difference in Code. Click a routine in behave differently and switch to Code. The line difference is drawn over the source, and above it a list says in what respect the routine behaves differently, for example its calls or its boundaries.
Colour the graph by change. Switch to Graph and set Colour by to what changed.

What you've learned#

That a program holds one working snapshot, and sealing is how you keep a second.
How to make a comparable pair from two directories, with or without shared history.
Why DunneFlow asks you which version is newer instead of guessing.
The difference between behave differently, edited only and explained only.

Next#

Gate CI with dunneflow check.
Reference: Comparing two versions.

Something unclear or out of date? Tell us.

You'll need#

DunneFlow, from source or the application. Commands are shown as uv run dunneflow; with the application, use its command-line program instead (see The command line) and your maps folder instead of output/.

Two directories holding two versions of the same project. With git, a worktree is the cheapest way (step 1). They can also be two unrelated drops with no shared history.

Steps#

Get the older tree. From your git clone at ~/code/some-project, check out an older commit or tag into its own directory, named for what it is:
```
git -C ~/code/some-project worktree add ~/code/some-project-2026-09-08 <commit-or-tag>
```
DunneFlow records the directory's name, so a date or tag in it is how you will recognise this version later.

Analyse the older tree.

uv run dunneflow analyze ~/code/some-project-2026-09-08/src --name some-project

Seal it. Sealing keeps this snapshot so the next analysis lands beside it rather than replacing it.
```
uv run dunneflow revisions output/some-project \
    --seal --label "some-project - 2026-09-08"
```

Analyse the newer tree into the same program.

uv run dunneflow analyze ~/code/some-project/src --name some-project

Check what the program holds.
```
uv run dunneflow revisions output/some-project
```
You should see one WORKING snapshot and one FOR_COMPARISON snapshot carrying your label.
Open the dashboard.
```
uv run dunneflow serve output/some-project
```
A program with two versions opens comparing them. The version strip under the top bar names both.
Set the direction. DunneFlow does not know which version is newer; it only knows when it read each one. If both state comparable version numbers it uses them; otherwise the strip says assuming the compared version is newer. If that is wrong, click it to flip. This decides whether changed routines read as arrived or gone.
Open Changes. In the navigator, open Changes, then The whole comparison. Start with behave differently: these routines do something different now. Then look at edited only, whose text changed but whose behaviour did not.
Read one routine's difference in Code. Click a routine in behave differently and switch to Code. The line difference is drawn over the source, and above it a list says in what respect the routine behaves differently, for example its calls or its boundaries.
Colour the graph by change. Switch to Graph and set Colour by to what changed.

What you've learned#

That a program holds one working snapshot, and sealing is how you keep a second.

How to make a comparable pair from two directories, with or without shared history.

Why DunneFlow asks you which version is newer instead of guessing.

The difference between behave differently, edited only and explained only.