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, tasks, failures, performance, efficiency, outputs, published outputs, logs, and DAG wiring. By default it highlights meaningful changes and treats always-differing fields as context. Use --verbose to flag everything.

Output is a single, standalone HTML document with inline CSS/JS/SVG that requires no network access and supports light/dark themes. 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

Requirements

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

Installation

Use the published plugin directly with Nextflow:

nextflow plugin nf-diff:diff --last

For local or 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

nf-diff includes a composite GitHub Action to compare runs on Pull Requests and post rich Markdown summary comments:

- 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 to compare task outputs, logs, and DAG wiring when required work directories are available. Set diff-all: 'false' to disable this behavior.

License

nf-diff is licensed under the Apache License 2.0.