rtfpessoa/diff2htmlPublic

NotificationsYou must be signed in to change notification settings
Fork295
Star3.3k

Pretty diff to html javascript library (diff2html)

License

MIT license

3.3k stars 295 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 782 Commits
.github		.github
.husky		.husky
.vscode		.vscode
scripts		scripts
src		src
terraform		terraform
typings		typings
website		website
.all-contributorsrc		.all-contributorsrc
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
CNAME		CNAME
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CREDITS.md		CREDITS.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json
webpack.bundles.ts		webpack.bundles.ts
webpack.website.ts		webpack.website.ts

Repository files navigation

diff2html

diff2html generates pretty HTML diffs from git diff or unified diff output.

Features

Supports git and unified diffs
Line by line and Side by side diff
New and old line numbers
Inserted and removed lines
GitHub like visual style
Code syntax highlight
Line similarity matching
Easy code selection

Online Example

Go todiff2html

Distributions

jsdelivr CDN
WebJar
Node Library
NPM CLI
Manually use from jsdelivr or build the project:
- Browser / Bundle
  - Parser and HTML Generator
    - bundles/js/diff2html.min.js - includes thediff parser and html generator
  - Wrapper and helper adding syntax highlight, synchronized scroll, and other nice features
    - bundles/js/diff2html-ui.min.js -includes the wrapper of diff2html with highlight for allhighlight.js supported languages
    - bundles/js/diff2html-ui-slim.min.js -includes the wrapper of diff2html with "the most common"highlight.js supported languages
    - bundles/js/diff2html-ui-base.min.js -includes the wrapper of diff2html without including ahighlight.js implementation. You can use it withoutsyntax highlight or by passing your own implementation with the languages you prefer
- NPM / Node.js library
  - ES5
    - lib/diff2html.js - includes the diff parser and htmlgenerator
    - lib/ui/js/diff2html-ui.js - includes thewrapper of diff2html with highlight for allhighlight.js supported languages
    - lib/ui/js/diff2html-ui-slim.js -includes the wrapper of diff2html with "the most common"highlight.js supported languages
    - lib/ui/js/diff2html-ui-base.js
  - ES6
    - lib-esm/diff2html.js - includes the diff parserand html generator
    - lib/ui/js/diff2html-ui.js - includes thewrapper of diff2html with highlight for allhighlight.js supported languages
    - lib/ui/js/diff2html-ui-slim.js -includes the wrapper of diff2html with "the most common"highlight.js supported languages
    - lib/ui/js/diff2html-ui-base.js -includes the wrapper of diff2html without including ahighlight.js implementation. You can use it withoutsyntax highlight or by passing your own implementation with the languages you prefer

Usage

Diff2Html can be used in various ways as listed in thedistributions section. The two main ways are:

Diff2HtmlUI: using this wrapper makes it easy to inject the html in the DOM and adds some nicefeatures to the diff, like syntax highlight.
Diff2Html: using the parser and html generator directly from the library gives you completecontrol about what you can do with the json or html generated.

Below you can find more details and examples about each option.

Diff Text Input

diff2html accepts the text contents of aunified diff or the superset format gitdiff (https://git-scm.com/docs/git-diff) (not combined or word diff). To provide multiples files as input justconcatenate the diffs (just like the output of git diff).

Diff2HtmlUI Usage

Simple wrapper to ease simple tasks in the browser such as: code highlight and js effects

Invoke Diff2html
Inject output in DOM element
Enable collapsible file summary list
Enable syntax highlight of the code in the diffs

Diff2HtmlUI API

Create a Diff2HtmlUI instance

constructor(target:HTMLElement,diffInput?: string|DiffFile[])// diff2html-ui, diff2html-ui-slimconstructor(target:HTMLElement,diffInput?: string|DiffFile[],config:Diff2HtmlUIConfig={},hljs?:HighlightJS)// diff2html-ui-base

Generate and inject in the document the Pretty HTML representation of the diff

draw():void

Enable extra features

synchronisedScroll():voidfileListToggle(startVisible: boolean):voidhighlightCode():voidstickyFileHeaders():void

Diff2HtmlUI Configuration

synchronisedScroll: scroll both panes in side-by-side mode:true orfalse, default istrue
highlight: syntax highlight the code on the diff:true orfalse, default istrue
fileListToggle: allow the file summary list to be toggled:true orfalse, default istrue
fileListStartVisible: choose if the file summary list starts visible:true orfalse, default isfalse
fileContentToggle: allow each file contents to be toggled:true orfalse, default istrue
stickyFileHeaders: make file headers sticky:true orfalse, default istrue
All the options from Diff2Html are also valid configurations in Diff2HtmlUI

Diff2HtmlUI Browser

Mandatory HTML resource imports

<!-- CSS --><linkrel="stylesheet"type="text/css"href="https://cdn.jsdelivr.net/npm/diff2html/bundles/css/diff2html.min.css"/><!-- Javascripts --><scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/diff2html/bundles/js/diff2html-ui.min.js"></script>

Init

consttargetElement=document.getElementById('destination-elem-id');constconfiguration={drawFileList:true,matching:'lines'};constdiff2htmlUi=newDiff2HtmlUI(targetElement,diffString,configuration);// orconstdiff2htmlUi=newDiff2HtmlUI(targetElement,diffJson,configuration);

Draw

diff2htmlUi.draw();

Syntax Highlight

NOTE: The highlight.js css should come before the diff2html css

<!-- Stylesheet --><linkrel="stylesheet"href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css"/><linkrel="stylesheet"type="text/css"href="https://cdn.jsdelivr.net/npm/diff2html/bundles/css/diff2html.min.css"/><!-- Javascripts --><scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/diff2html/bundles/js/diff2html-ui.min.js"></script>

Pass the optionhighlight with value true or invokediff2htmlUi.highlightCode() afterdiff2htmlUi.draw().

document.addEventListener('DOMContentLoaded',()=>{constdiffString=`diff --git a/sample.js b/sample.js  index 0000001..0ddf2ba  --- a/sample.js  +++ b/sample.js  @@ -1 +1 @@  -console.log("Hello World!")  +console.log("Hello from Diff2Html!")`;consttargetElement=document.getElementById('myDiffElement');constconfiguration={drawFileList:true,matching:'lines',highlight:true};constdiff2htmlUi=newDiff2HtmlUI(targetElement,diffString,configuration);diff2htmlUi.draw();diff2htmlUi.highlightCode();});

When using theauto color scheme, you will need to specify both the light and dark themes for highlight.js to use.

<linkrel="stylesheet"href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css"media="screen and (prefers-color-scheme: light)"/><linkrel="stylesheet"href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css"media="screen and (prefers-color-scheme: dark)"/>

Collapsable File Summary List

Add the dependencies.

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

Invoke the Diff2HtmlUI helper Pass the optionfileListToggle with value true or invokediff2htmlUi.fileListToggle() afterdiff2htmlUi.draw().

document.addEventListener('DOMContentLoaded',()=>{consttargetElement=document.getElementById('myDiffElement');vardiff2htmlUi=newDiff2HtmlUI(targetElement,lineDiffExample,{drawFileList:true,matching:'lines'});diff2htmlUi.draw();diff2htmlUi.fileListToggle(false);});

Diff2HtmlUI Examples

Example with plain HTML+CSS+JS

<!doctype html><htmllang="en-us"><head><metacharset="utf-8"/><!-- Make sure to load the highlight.js CSS file before the Diff2Html CSS file --><linkrel="stylesheet"href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.1/styles/github.min.css"/><linkrel="stylesheet"type="text/css"href="https://cdn.jsdelivr.net/npm/diff2html/bundles/css/diff2html.min.css"/><scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/diff2html/bundles/js/diff2html-ui.min.js"></script></head><script>constdiffString=`diff --git a/sample.js b/sample.jsindex 0000001..0ddf2ba--- a/sample.js+++ b/sample.js@@ -1 +1 @@-console.log("Hello World!")+console.log("Hello from Diff2Html!")`;document.addEventListener('DOMContentLoaded',function(){vartargetElement=document.getElementById('myDiffElement');varconfiguration={drawFileList:true,fileListToggle:false,fileListStartVisible:false,fileContentToggle:false,matching:'lines',outputFormat:'side-by-side',synchronisedScroll:true,highlight:true,renderNothingWhenEmpty:false,};vardiff2htmlUi=newDiff2HtmlUI(targetElement,diffString,configuration);diff2htmlUi.draw();diff2htmlUi.highlightCode();});</script><body><divid="myDiffElement"></div></body></html>

StimulusJS with TypeScript

import{Controller}from'@hotwired/stimulus';import{Diff2HtmlUI,Diff2HtmlUIConfig}from'diff2html/lib/ui/js/diff2html-ui-slim.js';// Requires `npm install highlight.js`import'highlight.js/styles/github.css';import'diff2html/bundles/css/diff2html.min.css';exportdefaultclassextendsController{connect():void{constdiff2htmlUi=newDiff2HtmlUI(this.diffElement,this.unifiedDiff,this.diffConfiguration);diff2htmlUi.draw();}getunifiedDiff():string{returnthis.data.get('unifiedDiff')||'';}getdiffElement():HTMLElement{returnthis.elementasHTMLElement;}getdiffConfiguration():Diff2HtmlUIConfig{return{drawFileList:true,matching:'lines',};}}

Diff2Html Usage

Diff2Html API

JSON representation of the diff

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

Pretty HTML representation of the diff

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

Diff2Html Configuration

The HTML output accepts a Javascript object with configuration. Possible options:

outputFormat: the format of the output data:'line-by-line' or'side-by-side', default is'line-by-line'
drawFileList: show a file list before the diff:true orfalse, default istrue
srcPrefix: add a prefix to all source (before changes) filepaths, default is''. Should match the prefix used whengenerating the diff.
dstPrefix: add a prefix to all destination (after changes) filepaths, default is''. Should match the prefix usedwhengenerating the diff
diffMaxChanges: number of changed lines after which a file diff is deemed as too big and not displayed, default isundefined
diffMaxLineLength: number of characters in a diff line after which a file diff is deemed as too big and notdisplayed, default isundefined
diffTooBigMessage: function allowing to customize the message in case of file diff too big (ifdiffMaxChanges ordiffMaxLineLength is set). Will be given a file index as a number and should return a string.
matching: matching level:'lines' for matching lines,'words' for matching lines and words or'none', defaultisnone
matchWordsThreshold: similarity threshold for word matching, default is0.25
maxLineLengthHighlight: only perform diff changes highlight if lines are smaller than this, default is10000
diffStyle: show differences level in each line:'word' or'char', default is'word'
renderNothingWhenEmpty: render nothing if the diff shows no change in its comparison:true orfalse, default isfalse
matchingMaxComparisons: perform at most this much comparisons for line matching a block of changes, default is2500
maxLineSizeInBlockForComparison: maximum number of characters of the bigger line in a block to apply comparison,default is200
compiledTemplates: object (Hogan.js template values) with previouslycompiled templates to replace parts of the html, default is{}. For example:{ "tag-file-changed": Hogan.compile("<span>MODIFIED</span>") }
rawTemplates: object (string values) with raw not compiled templates to replace parts of the html, default is{}.For example:{ "tag-file-changed": "<span>MODIFIED</span>" }
For more information regarding the possible templates look intosrc/templates
highlightLanguages: Map of extension to language name, used for highlighting. This overrides the default languagedetection based on file extensions.
colorScheme: color scheme to use for the diff, default islight. Possible values arelight,dark, andautowhich will use the browser's preferred color scheme.

Diff2Html Browser

Import the stylesheet and the library code.

To load correctly in the Browser you need to include the stylesheet in the final HTML.

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

It will now be available as a global variable namedDiff2Html.

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

Diff2Html NPM / Node.js Library

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

Diff2Html Examples

Example with Angular

Typescript

import*asDiff2Htmlfrom'diff2html';import{Component,OnInit}from'@angular/core';exportclassAppDiffComponentimplementsOnInit{outputHtml:string;constructor(){this.init();}ngOnInit(){}init(){letstrInput='--- a/server/vendor/golang.org/x/sys/unix/zsyscall_linux_mipsle.go\n+++ b/server/vendor/golang.org/x/sys/unix/zsyscall_linux_mipsle.go\n@@ -1035,6 +1035,17 @@ func Prctl(option int, arg2 uintptr, arg3 uintptr, arg4 uintptr, arg5 uintptr) (\n \n // THIS FILE IS GENERATED BY THE COMMAND AT THE TOP; DO NOT EDIT\n \n+func Pselect(nfd int, r *FdSet, w *FdSet, e *FdSet, timeout *Timespec, sigmask *Sigset_t) (n int, err error) {\n+\tr0, _, e1 := Syscall6(SYS_PSELECT6, uintptr(nfd), uintptr(unsafe.Pointer(r)), uintptr(unsafe.Pointer(w)), uintptr(unsafe.Pointer(e)), uintptr(unsafe.Pointer(timeout)), uintptr(unsafe.Pointer(sigmask)))\n+\tn = int(r0)\n+\tif e1 != 0 {\n+\t\terr = errnoErr(e1)\n+\t}\n+\treturn\n+}\n+\n+// THIS FILE IS GENERATED BY THE COMMAND AT THE TOP; DO NOT EDIT\n+\n func read(fd int, p []byte) (n int, err error) {\n \tvar _p0 unsafe.Pointer\n \tif len(p) > 0 {\n';letoutputHtml=Diff2Html.html(strInput,{drawFileList:true,matching:'lines'});this.outputHtml=outputHtml;}}

HTML

<!doctype html><html><head><title>diff2html</title></head><body><div[innerHtml]="outputHtml"></div></body></html>

.angular-cli.json - Add styles

"styles": ["diff2html.min.css"]

Example with Vue.js

<template>  <divv-html="prettyHtml" /></template><script>import*asDiff2Htmlfrom'diff2html';import'diff2html/bundles/css/diff2html.min.css';exportdefault {data() {return {      diffs:'--- a/server/vendor/golang.org/x/sys/unix/zsyscall_linux_mipsle.go\n+++ b/server/vendor/golang.org/x/sys/unix/zsyscall_linux_mipsle.go\n@@ -1035,6 +1035,17 @@ func Prctl(option int, arg2 uintptr, arg3 uintptr, arg4 uintptr, arg5 uintptr) (\n\n // THIS FILE IS GENERATED BY THE COMMAND AT THE TOP; DO NOT EDIT\n\n+func Pselect(nfd int, r *FdSet, w *FdSet, e *FdSet, timeout *Timespec, sigmask *Sigset_t) (n int, err error) {\n+\tr0, _, e1 := Syscall6(SYS_PSELECT6, uintptr(nfd), uintptr(unsafe.Pointer(r)), uintptr(unsafe.Pointer(w)), uintptr(unsafe.Pointer(e)), uintptr(unsafe.Pointer(timeout)), uintptr(unsafe.Pointer(sigmask)))\n+\tn = int(r0)\n+\tif e1 != 0 {\n+\t\terr = errnoErr(e1)\n+\t}\n+\treturn\n+}\n+\n+// THIS FILE IS GENERATED BY THE COMMAND AT THE TOP; DO NOT EDIT\n+\n func read(fd int, p []byte) (n int, err error) {\n\tvar _p0 unsafe.Pointer\n\tif len(p) > 0 {\n',    };  },  computed: {prettyHtml() {returnDiff2Html.html(this.diffs, {        drawFileList:true,        matching:'lines',        outputFormat:'side-by-side',      });    },  },};</script>

Troubleshooting

1. Out of memory or Slow execution

Causes:

Big files
Big lines

Fix:

Disable the line matching algorithm, by setting the option{"matching": "none"} when invoking diff2html

Contribute

This is a developer friendly project, all the contributions are welcome. To contribute just send a pull request withyour changes following the guidelines described inCONTRIBUTING.md. I will try to review them as soon as possible.

Contributors

Thanks goes to these wonderful people (emoji key):

_{Rodrigo Fernandes} 💻	_stockmind 💻	_{Ivan Vorontsov} 💻	_{Nick Brewer} 💻	_{Matt Wade} 🐛💻	_{Rafael Cortês} 💻	_{Nuno Teixeira} 💻
_{Koki Oyatsu} 🐛💻	_{James Monger} 📖	_{Wessel van der Pal} 🛡️💻	_jk-kim 💻	_{Sergey Semenov} 🐛💻	_{Nick Mitchell} 🐛💻	_{Samir Aguiar} 📖
_pubkey 📖💻	_Илья 📖	_{Mohamed Akram} 🐛📖💻	_{Eugene Marcotte} 💻	_{Dima Sabanin} 🚧💻	_{Ben Abbott} 📖	_{弘树@阿里} 🐛📖
_{Mikko Rantanen} 🐛	_Ann 📖	_escitalopram 💻	_{dependabot[bot]} 🛡️🚧	_{Josh Goldberg} 💻	_Aaron 📖	_{Pierre Grimaud} 📖
_{Adam Jones} 📖	_{Arthur Charguéraud} 📖	_{Pierric Cistac} 📖💻	_{Civan Yavuzşen} 💻	_{Tim Gates} 📖	_campersau 💻	_{dependabot-preview[bot]} 💻