Skip to content

Generate a diff between versions

I've been generating diffs for AsciiDoc files for a while... here's the best solution that I've come up with.

  1. Render the original source as HTML
  2. Render the updated source as HTML
  3. Use node-htmldiff to generate a diff.

I had some early success with wdiff, but it had it's problems. node-htmldiff has provided the most consistent results.

For simple files, I just use the standard Ruby-based asciidoctor (which needs to be installed) to convert the *.adoc files to HTML. For more complex documents that include multiple files and many variables (like the EDP), I actually grab a previous rendering of it (already in HTML) and compare it against the result of running the Maven-based build on the current state of the repository.

But the security policy is pretty simple, so I just brute force it:

$ git show tags/v1.1:security-policy.adoc | asciidoctor - -a bylawsUrl=https://www.eclipse.org/org/documents/eclipse_foundation-bylaws.pdf -a edpUrl=https://www.eclipse.org/projects/dev_process/ > /tmp/security-policy-v1.1.html
$ cat security-policy.adoc | asciidoctor - -a bylawsUrl=https://www.eclipse.org/org/documents/eclipse_foundation-bylaws.pdf -a edpUrl=https://www.eclipse.org/projects/dev_process/ > /tmp/security-policy-current.html
$ npm i node-htmldiff
$ node ./node_modules/node-htmldiff/htmldiff-cli.js /tmp/security-policy-v1.1.html /tmp/security-policy-current.html /tmp/security-policy-diff.html

I've created releng/build.sh scripts based on this approach in a few different repositories.

/cc @mbarbero