node-diff3

node-diff3

node-diff3 is a Javascript library to find differences between two buffers, generate and apply patches, and perform 3-way merging between an original and two changed buffers. It contains similar functionality to the GNU Diffutils tools.

The code originally came from project Synchrotron, created by Tony Garnock-Jones. For more detail please visit:

• https://leastfixedpoint.com/tonyg/kcbbs/projects/synchrotron.html
• https://github.com/tonyg/synchrotron

 

Usage

To install node-diff3 as a dependency in your project:

$  npm install --save node-diff3

node-diff3 is distributed in both UMD and ES6 module formats for maxmimum compatibility. (Read more about Javascript module formats)

• index.mjs - ES6 module
• dist/index.js - UMD module, ES6 syntax
• dist/index.es5.js - UMD module, ES5 syntax

Whether you require or import it, it should just work.

const Diff3 = require('node-diff3');                   // UMD import all
const diff3Merge = require('node-diff3').diff3Merge;   // UMD import named
// or
import * as Diff3 from 'node-diff3';                   // ES6 import all
import { diff3Merge } from 'node-diff3';               // ES6 import named

You can also use node-diff3 directly in a web browser. A good way to do this is to fetch the file from the jsDelivr CDN, which can even deliver minified versions.

The latest versions of many web browsers now support ES6 modules in script tags like this:

<script type="module" src="https://cdn.jsdelivr.net/npm/node-diff3@2/index.min.mjs"></script>

Older versions of modern ES6-capable browsers can still load the UMD build:

<script src="https://cdn.jsdelivr.net/npm/node-diff3@2/dist/index.min.js"></script>

Or if you need to support even older browsers like Internet Explorer, fetch the ES5 version:

<script src="https://cdn.jsdelivr.net/npm/node-diff3@2/dist/index.es5.min.js"></script>

 

API Reference

• 3-way diff and merging
  • diff3Merge
  • merge
  • mergeDiff3
  • mergeDigIn
  • diff3MergeRegions
• 2-way diff and patching
  • diffPatch
  • patch
  • stripPatch
  • invertPatch
  • diffComm
  • diffIndices
• Longest Common Sequence (LCS)
  • LCS

 

3-way diff and merging

 

# Diff3.diff3Merge(a, o, b, options)

Performs a 3-way diff on buffers o (original), and a and b (changed). The buffers may be arrays or strings. If strings, they will be split into arrays on whitespace /\s+/ by default. The returned result alternates between "ok" and "conflict" blocks.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diff3Merge.test.js

const o = ['AA', 'ZZ', '00', 'M', '99'];
const a = ['AA', 'a', 'b', 'c', 'ZZ', 'new', '00', 'a', 'a', 'M', '99'];
const b = ['AA', 'a', 'd', 'c', 'ZZ', '11', 'M', 'z', 'z', '99'];
const result = Diff3.diff3Merge(a, o, b);

Options may passed as an object:

{
  excludeFalseConflicts: true,
  stringSeparator: /\s+/
}

• excludeFalseConflicts - If both a and b contain an identical change from o, this is considered a "false" conflict.
• stringSeparator - If inputs buffers are strings, this controls how to split the strings into arrays. The separator value may be a string or a regular expression, as it is just passed to String.split().

 

# Diff3.merge(a, o, b, options)

Passes arguments to diff3Merge to generate a diff3-style merge result.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/merge.test.js

const r = Diff3.merge(a, o, b);
const result = r.result;
// [
//   'AA',
//   '\n<<<<<<<<<\n',
//   'a',
//   'b',
//   'c',
//   '\n=========\n',
//   'a',
//   'd',
//   'c',
//   '\n>>>>>>>>>\n',
//   'ZZ',
//   '\n<<<<<<<<<\n',
//   'new',
//   '00',
//   'a',
//   'a',
//   '\n=========\n',
//   '11',
//   '\n>>>>>>>>>\n',
//   'M',
//   'z',
//   'z',
//   '99'
//  ]

 

# Diff3.mergeDiff3(a, o, b, options)

Passes arguments to diff3Merge to generate a diff3-style merge result with original (similar to git-diff3).

See examples: https://github.com/bhousel/node-diff3/blob/main/test/mergeDiff3.test.js

const r = Diff3.mergeDiff3(a, o, b, { label: { a: 'a', o: 'o', b: 'b' } });
const result = r.result;
// [
//   'AA',
//   '<<<<<<< a',
//   'a',
//   'b',
//   'c',
//   '||||||| o',
//   '=======',
//   'a',
//   'd',
//   'c',
//   '>>>>>>> b',
//   'ZZ',
//   '<<<<<<< a',
//   'new',
//   '00',
//   'a',
//   'a',
//   '||||||| o',
//   '00',
//   '=======',
//   '11',
//   '>>>>>>> b',
//   'M',
//   'z',
//   'z',
//   '99'
//  ]

Extra options:

{
  // labels for conflict marker lines
  label: {
    a: 'a',
    o: 'o',
    b: 'b'
  },
}

 

# Diff3.mergeDigIn(a, o, b, options)

Passes arguments to diff3Merge to generate a digin-style merge result.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/mergeDigIn.test.js

 

# Diff3.diff3MergeRegions(a, o, b)

Low-level function used by diff3Merge to determine the stable and unstable regions between a, o, b.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diff3MergeRegions.test.js

 

2-way diff and patching

 

# Diff3.diffPatch(buffer1, buffer2)

Performs a diff between arrays buffer1 and buffer2. The returned patch result contains the information about the differing regions and can be applied to buffer1 to yield buffer2.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diffPatch.test.js

const buffer1 = ['AA', 'a', 'b', 'c', 'ZZ', 'new', '00', 'a', 'a', 'M', '99'];
const buffer2 = ['AA', 'a', 'd', 'c', 'ZZ', '11', 'M', 'z', 'z', '99'];
const patch = Diff3.diffPatch(buffer1, buffer2);
// `patch` contains the information needed to turn `buffer1` into `buffer2`

 

# Diff3.patch(buffer1, patch)

Applies a patch to a buffer, returning a new buffer without modifying the original.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diffPatch.test.js

const result = Diff3.patch(buffer1, patch);
// `result` contains a new arrray which is a copy of `buffer2`

 

# Diff3.stripPatch(patch)

Strips some extra information from the patch, returning a new patch without modifying the original. The "stripped" patch can still patch buffer1 -> buffer2, but can no longer be inverted.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diffPatch.test.js

const stripped = Diff3.stripPatch(patch);
// `stripped` contains a copy of a patch but with the extra information removed

 

# Diff3.invertPatch(patch)

Inverts the patch (for example to turn buffer2 back into buffer1), returning a new patch without modifying the original.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diffPatch.test.js

const inverted = Diff3.invertPatch(patch);
// `inverted` contains a copy of a patch to turn `buffer2` back into `buffer1`

 

# Diff3.diffComm(buffer1, buffer2)

Returns a comm-style result of the differences between buffer1 and buffer2.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diffComm.test.js

 

# Diff3.diffIndices(buffer1, buffer2)

Low-level function used by diff3MergeRegions to determine differing regions between buffer1 and buffer2.

See examples: https://github.com/bhousel/node-diff3/blob/main/test/diffIndices.test.js

 

Longest Common Sequence (LCS)

 

# Diff3.LCS(buffer1, buffer2)

Low-level function used by other functions to find the LCS between buffer1 and buffer2. Returns a result linked list chain containing the common sequence path.

See also:

• http://www.cs.dartmouth.edu/~doug/
• https://en.wikipedia.org/wiki/Longest_common_subsequence_problem

See examples: https://github.com/bhousel/node-diff3/blob/main/test/LCS.test.js

 

License

This project is available under the MIT License. See the LICENSE.md file for more details.