Using oasdiff for rich Git diffs of OpenAPI spec changes

I work with quite a few OpenAPI specs, and have found it useful to be able to keep an eye on what's changed over time.

Although I'm familiar with the YAML (or JSON) representation of a given OpenAPI spec, it's nicer to have a summary that's human-readable.

This especially is the case in my work maintaining rootly's Go SDK, where there's a lot of change!

I've recently been using oasdiff a lot more, and have found that it'd be useful to have it as a diff driver for Git, so git diff output shows a human-readable summary of changes in a commit.

Update 2026-05-28: This is available upstream as of oasdiff/oasdiff#954.

To set this up, you need .gitattributes:

# NOTE the diff name is anything you want, defined by your `.git/config` below
.vendored/rootly-api/swagger.json diff=oasdiff

In the repo's .git/config, or any global Git configuration you have:

[diff "oasdiff"]
	# I prefer to have colour always reported
	command = oasdiff git-diff-driver --color always

One of the problems with using an external diff driver is that it means you need to run i.e. git log --patch --ext-diff.

Setting it up manually

Update 2026-05-28: This post was updated as this functionality is now available upstream as of oasdiff/oasdiff#954. In the meantime, here's how I manually set it up, before support was added:

To do this, I've created this wrapper over oasdiff to implement the git diff driver:

#!/usr/bin/env bash

# Via https://www.jvt.me/posts/2026/04/11/oasdiff-driver/
# A diff driver for `git diff` to provide a human-readable changelog for a given OpenAPI spec

if [[ "$2" == "/dev/null" ]]; then
	echo "$1 was added"
	exit 0
elif [[ "$5" == "/dev/null" ]]; then
	echo "$1 was deleted"
	exit 0
fi

# I prefer to have colour always reported
oasdiff changelog "$2" "$5" --color always

To set this up, you also need .gitattributes:

# NOTE the diff name is anything you want, defined by your `.git/config` below
.vendored/rootly-api/swagger.json diff=oasdiff

In the repo's .git/config, or any global Git configuration you have:

[diff "oasdiff"]
	command = ~/bin/oasdiff-driver

One of the problems with using an external diff driver is that it means you need to run i.e. git log --patch --ext-diff.

We can see it in action:

Note that the filename that is used for output is the temporary filename Git provides to us.

I'll be looking at adding an option for a diff driver upstream in oasdiff, which will make it even easier to use, and mean that we don't reference the temporary filenames in our output.

Update 2026-05-28: This is available upstream as of oasdiff/oasdiff#954.