Summary

nf-diff is a Nextflow plugin that adds a diff CLI verb. Point it at two runs from your local run history — or just say --last — and it reconstructs both entirely from Nextflow's own history and cache (no re-execution) and renders a self-contained HTML report of everything that changed between them.

The plugin compares multiple layers including metadata, parameters, configuration, processes, software versions, task status, failures, performance, efficiency, outputs, published outputs, logs, and DAG wiring. By default the report highlights meaningful changes and treats always-differing fields (run name, session id, launch time, cache hash, wall time, resource usage) as context. Use --verbose to flag everything.

Output is a single, standalone HTML document with inline CSS/JS/SVG, no network access, and light/dark theme support. For CI and scripting, --format=json and --format=md emit the same comparison, and --fail-on-change turns any difference into a non-zero exit code.

Get Started

Use the published plugin directly with Nextflow, or configure the local repository when testing an unpublished build.

Requirements:

• Nextflow >= 25.04.0
• Java 17+
• Two runs present in the local .nextflow/history of the project you're inspecting

Installation: For local/unpublished builds, run:

make dev-repo
export NXF_PLUGINS_TEST_REPOSITORY="file://$PWD/build/plugin-repo/plugins.json"

Then invoke the bare id nf-diff:diff (not a pinned version).

Examples

# Compare the two most recent runs
nextflow plugin nf-diff:diff --last

# Compare two runs by name (or session-id prefix)
nextflow plugin nf-diff:diff tender_euler happy_curie

# Emit Markdown for a PR comment
nextflow plugin nf-diff:diff --last --format=md --output=diff.md

# CI gate: fail if anything meaningful changed
nextflow plugin nf-diff:diff --last --fail-on-change

GitHub Action for CI:

- name: Compare PR run with baseline
  uses: mribeirodantas/nf-diff@main
  with:
    last: 'true'
    format: md
    comment-pr: 'true'

The GitHub Action enables diff-all by default, so it compares task outputs, logs, and DAG wiring when the required work directories are available. Set diff-all: 'false' to disable this behavior.

License

nf-diff is licensed under the Apache License 2.0.