{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreif62ha2x2kffcyaeier6rmswnktcwvs43iojadfvswlggm5w2sm5a",
    "uri": "at://did:plc:wszrgoqdwy3i2dfeub2mt3wf/app.bsky.feed.post/3mj7r5mlbys22"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreibiogpfo56ybgdo3cpp5muifesclfvcjepvpz5jvodc3shrsddmrm"
    },
    "mimeType": "image/png",
    "size": 35673
  },
  "description": "How to configure `git diff` to use `oasdiff`'s rich changelog on changes to OpenAPI specs.",
  "path": "/posts/2026/04/11/oasdiff-driver/",
  "publishedAt": "2026-04-11T11:32:10.000Z",
  "site": "https://www.jvt.me",
  "tags": [
    "blogumentation",
    "openapi",
    "rootly's Go SDK",
    "oasdiff",
    "have it as a diff driver for Git"
  ],
  "textContent": "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.\n\nAlthough 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_.\n\nThis especially is the case in my work maintaining rootly's Go SDK, where there's a lot of change!\n\nI'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.\n\nTo do this, I've created this wrapper over `oasdiff` to implement the `git diff` driver:\n\n\n    #!/usr/bin/env bash\n\n    # Via https://www.jvt.me/posts/2026/04/11/oasdiff-driver/\n    # A diff driver for `git diff` to provide a human-readable changelog for a given OpenAPI spec\n\n    if [[ \"$2\" == \"/dev/null\" ]]; then\n    \techo \"$1 was added\"\n    \texit 0\n    elif [[ \"$5\" == \"/dev/null\" ]]; then\n    \techo \"$1 was deleted\"\n    \texit 0\n    fi\n\n    # I prefer to have colour always reported\n    oasdiff changelog \"$2\" \"$5\" --color always\n\n\nTo set this up, you also need `.gitattributes`:\n\n\n    # NOTE the diff name is anything you want, defined by your `.git/config` below\n    .vendored/rootly-api/swagger.json diff=oasdiff\n\n\nIn the repo's `.git/config`, or any global Git configuration you have:\n\n\n    [diff \"oasdiff\"]\n    \tcommand = ~/bin/oasdiff-driver\n\n\nOne of the problems with using an external diff driver is that it means you need to run i.e. `git log --patch --ext-diff`.\n\nWe can see it in action:\n\nNote that the filename that is used for output is the temporary filename Git provides to us.\n\nI'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.",
  "title": "Using oasdiff for rich Git diffs of OpenAPI spec changes",
  "updatedAt": "2026-04-11T11:32:10.000Z"
}