diff2html

diff2html is a tool that generates visually appealing HTML diffs from git diff or unified diff output.

Key features include:

• Support for both git and unified diff formats.
• Display modes: Line by line and Side by side.
• Visual indicators for new/old line numbers and inserted/removed lines.
• GitHub-like visual style.
• Integrated code syntax highlighting.
• Line similarity matching and easy code selection.

To use Diff2Html directly in a web browser, include the CSS and JavaScript bundles via CDN. The library will be available under the global Diff2Html variable.

Note: You must include the stylesheet in your HTML for the diff to render correctly.

<!-- CSS -->
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/diff2html/bundles/css/diff2html.min.css" />

<!-- Javascripts -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/diff2html/bundles/js/diff2html.min.js"></script>

<script>
document.addEventListener('DOMContentLoaded', () => {
  var diffHtml = Diff2Html.html('<Unified Diff String>', {
    drawFileList: true,
    matching: 'lines',
    outputFormat: 'side-by-side',
  });
  document.getElementById('destination-elem-id').innerHTML = diffHtml;
});
</script>

diff2html accepts the text content of a unified diff or the git diff format (specifically the superset format, excluding combined or word diffs).

To process multiple files in a single input, simply concatenate the diffs together, mimicking the standard output of the git diff command.

The Diff2HtmlUI constructor accepts a configuration object. Note that all standard Diff2Html options are also valid.

Diff2HtmlUI Specific Options

• synchronisedScroll: (boolean, default: true) Scrolls both panes simultaneously in side-by-side mode.
• highlight: (boolean, default: true) Enables syntax highlighting for the code in the diff.
• fileListToggle: (boolean, default: true) Allows the file summary list to be toggled.
• fileListStartVisible: (boolean, default: false) Determines if the file summary list is visible on load.
• fileContentToggle: (boolean, default: true) Allows individual file contents to be toggled.
• stickyFileHeaders: (boolean, default: true) Makes file headers sticky during scroll.

Install the package and require it to parse diff strings into JSON or render them directly to HTML.

const Diff2html = require('diff2html');
const diffJson = Diff2html.parse('<Unified Diff String>');
const diffHtml = Diff2html.html(diffJson, { drawFileList: true });
console.log(diffHtml);

To use diff2html-ui-slim in a Stimulus controller with TypeScript, ensure you install highlight.js via npm and import the necessary CSS files.

import { Controller } from '@hotwired/stimulus';
import { Diff2HtmlUI, Diff2HtmlUIConfig } from 'diff2html/lib/ui/js/diff2html-ui-slim.js';

import 'highlight.js/styles/github.css';
import 'diff2html/bundles/css/diff2html.min.css';

export default class extends Controller {
  connect(): void {
    const diff2htmlUi = new Diff2HtmlUI(this.diffElement, this.unifiedDiff, this.diffConfiguration);
    diff2htmlUi.draw();
  }

  get unifiedDiff(): string {
    return this.data.get('unifiedDiff') || '';
  }

  get diffElement(): HTMLElement {
    return this.element as HTMLElement;
  }

  get diffConfiguration(): Diff2HtmlUIConfig {
    return {
      drawFileList: true,
      matching: 'lines',
    };
  }
}

Constructor

new Diff2HtmlUI(target: HTMLElement, diffInput?: string | DiffFile[], config: Diff2HtmlUIConfig = {}, hljs?: HighlightJS)

Instance Methods

• draw(): void: Generates and injects the Pretty HTML representation of the diff into the target element.
• synchronisedScroll(): void: Enables synchronized scrolling for side-by-side mode.
• fileListToggle(startVisible: boolean): void: Toggles the visibility of the file summary list.
• highlightCode(): void: Manually triggers syntax highlighting on the rendered diff.
• stickyFileHeaders(): void: Enables sticky file headers.

The Diff2Html API provides two primary functions for processing diff data:

1. parse(diffInput, configuration): Converts a unified diff string into a JSON representation (DiffFile[]).
2. html(diffInput, configuration): Converts either a unified diff string or a DiffFile[] array into a pretty HTML string.

Both functions accept an optional Diff2HtmlConfig object.

function parse(diffInput: string, configuration: Diff2HtmlConfig = {}): DiffFile[];

function html(diffInput: string | DiffFile[], configuration: Diff2HtmlConfig = {}): string;