git-diff

What is git-diff?

The git-diff npm package is a utility that allows you to compute the difference between two strings or files, similar to the diff functionality in Git. It is useful for comparing text data and generating diffs in a format that can be easily read or processed.

What are git-diff's main functionalities?

String Diff

This feature allows you to compute the difference between two strings. The code sample demonstrates how to use git-diff to find the differences between two strings, 'Hello World' and 'Hello New World'. The output will highlight the changes made from the first string to the second.

const gitDiff = require('git-diff');
const diff = gitDiff('Hello World', 'Hello New World');
console.log(diff);

File Diff

This feature allows you to compute the difference between two files. The code sample shows how to read two files and use git-diff to find the differences between their contents. This is useful for comparing file versions or changes.

const fs = require('fs');
const gitDiff = require('git-diff');
const file1 = fs.readFileSync('file1.txt', 'utf8');
const file2 = fs.readFileSync('file2.txt', 'utf8');
const diff = gitDiff(file1, file2);
console.log(diff);

Other packages similar to git-diff

diff

The 'diff' package is a popular library for computing differences between two inputs, such as strings or arrays. It provides a variety of diff algorithms and output formats. Compared to git-diff, 'diff' offers more flexibility and options for customizing the diff output.

jsdiff

JSDiff is another library for computing differences between two pieces of text. It supports various diff formats and is known for its ease of use and performance. JSDiff is similar to git-diff but offers additional features like patch application and more detailed diff outputs.

README

git-diff

Returns the git diff of two strings

Introduction

git-diff will use git (if installed) and printf (if available) to get the real git diff of two strings, viz the actual diff output produced by git itself.

As a fallback, if either command is unavailable, git-diff will instead use the diff module to produce a very good fake git diff.

If desired, you may then console.log the returned git diff. An example of actual output:

Usage

npm install --save git-diff

git-diff takes 3 arguments, the old string to diff, the new string to diff and optionally an options object

git-diff returns the git difference or undefined where there is no difference.

String diff example usage:

var gitDiff = require('git-diff')
var oldStr = 'fred\nis\nfunny\n'
var newStr = 'paul\nis\nfunny\n'
var diff = gitDiff(oldStr, newStr)

var assert = require('assert')
assert.equal(diff, '@@ -1,3 +1,3 @@\n-fred\n+paul\n is\n funny\n')

File diff example usage:

var gitDiff = require('git-diff')
var readFileGo = require('readfile-go') // or your preferred file reader
var oldStr = readFileGo(__dirname + '/oldStr.txt')
var newStr = readFileGo(__dirname + '/newStr.txt')
var diff = gitDiff(oldStr, newStr)

Options object

Available options are:

color | flags | forceFake | noHeaders | save | wordDiff

Default options are:

var options = {
  color: false,      // Add color to the git diff returned?
  flags: null,       // A space separated string of git diff flags from https://git-scm.com/docs/git-diff#_options
  forceFake: false,  // Do not try and get a real git diff, just get me a fake? Faster but may not be 100% accurate
  noHeaders: false,  // Remove the ugly @@ -1,3 +1,3 @@ header?
  save: false,       // Remember the options for next time?
  wordDiff: false    // Get a word diff instead of a line diff?
}

Further assistance is given below for options that are not self explanatory.

flags (string | null)

The flags option allows you to use any git diff flags

This only applies to real git diffs and will not effect the output if it is fake.

An example to illustrate:

var gitDiff = require('git-diff')
var oldStr = 'fred\n   is   \nfunny\n'
var newStr = 'paul\nis\n   funny   \n'
var diff = gitDiff(oldStr, newStr, {flags: '--diff-algorithm=minimal --ignore-all-space'})

var assert = require('assert')
assert.equal(diff, '@@ -1,3 +1,3 @@\n-fred\n+paul\n is\n    funny   \n')

Here, the use of --ignore-all-space prevents a difference being reported on the 2nd and 3rd lines.

forceFake (boolean)

git-diff will initially attempt to use git and printf to get the real git diff.

If it cannot, it instead returns a very good fake git diff.

A fake git diff is faster to produce but may not be 100% representative of a real git diff.

The flags option is ignored when faking and fake diffs never have a header.

However, if a fake is good enough and speed is of the essence then you may want to force a fake git diff.

The forceFake option allows you to do exactly that:

var gitDiff = require('git-diff')
var oldStr = 'fred\nis\nfunny\n'
var newStr = 'paul\nis\nfunny\n'
var diff = gitDiff(oldStr, newStr, {forceFake: true})

var assert = require('assert')
assert.equal(diff, '-fred\n+paul\n is\n funny\n')

save (boolean)

Its annoying to keep passing the same options every time.

git-diff, if instructed to do so, will remember previously used options for you.

When the {save: true} option is used in a call to git-diff subsequent calls remember the options.

var gitDiff = require('git-diff')
var oldStr = 'fred\nis\nfunny\n'
var newStr = 'paul\nis\nfunny\n'
var diff1 = gitDiff(oldStr, newStr, {save: true, wordDiff: true})
var diff2 = gitDiff(oldStr, newStr)

var assert = require('assert')
assert.equal(diff1, '@@ -1,3 +1,3 @@\n[-fred-]{+paul+}\nis\nfunny\n')
assert.equal(diff2, '@@ -1,3 +1,3 @@\n[-fred-]{+paul+}\nis\nfunny\n')

Here, the second call remembers that the wordDiff option is on. {wordDiff: true} is now the default.

Async execution

git-diff offers a promise based async solution:

var gitDiff = require('git-diff/async')
var oldStr = 'fred\nis\nfunny\n'
var newStr = 'paul\nis\nfunny\n'
gitDiff(oldStr, newStr).then(function(diff) {
  var assert = require('assert')
  assert.equal(diff, '@@ -1,3 +1,3 @@\n-fred\n+paul\n is\n funny\n')
})

FAQs

How good is the fake git diff?
The diff module used for the fake diff does not use the same difference algorithm as git. As such, a line diff is likely to be identical to a git line diff whereas a word diff will have some variance.

How can I tell whether the returned git diff is real or fake?
If the @@ -1,3 +1,3 @@ header is present then the returned git diff is real.
If the header is absent then either the noHeaders option is on or the returned git diff is fake.

Will my environment produce a real or fake git diff?
Linux and mac have the coveted printf command available. On Windows git bash makes printf accessible.
Assuming that git is installed, any of these environments will produce a real git diff.

Author says

What's the difference between how God treats the righteous and the wicked?

And God saw that the light was good. And God separated the light from the darkness. Genesis 1:4 ESV

And He will do it again:

Let both grow together until the harvest, and at harvest time I will tell the reapers, “Gather the weeds first and bind them in bundles to be burned, but gather the wheat into my barn.” Matthew 13:30 ESV

Much love :D