Unified Diff Parser

Common errors

• TypeError: parse is not a function

  cause Attempting to import `parse` as a named export (`import { parse } from 'parse-diff'`) in an ESM module or TypeScript, or destructuring `require('parse-diff')` in CommonJS. The `parse` function is the module's default export.
  fix For ESM/TypeScript, use `import parse from 'parse-diff';`. For CommonJS, use `const parse = require('parse-diff');`.

• Error: [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import() ...

  cause Using `require('parse-diff')` in a CommonJS module while `parse-diff` might have been resolved to an ESM-only version or an environment configured for ESM. While `parse-diff` supports CJS, conflicts can arise in mixed environments.
  fix If encountering this error, ensure your project's module resolution is consistent. If your project is primarily CommonJS, verify `parse-diff` is installed in a compatible version. If you are in an ESM context, always use `import parse from 'parse-diff';`.

• The parsed output array is empty or contains fewer files/chunks than expected, despite valid diff input.

  cause Subtle formatting issues in the input diff string (e.g., incorrect line endings, malformed headers, non-standard Git extensions) can cause the parser to fail silently or misinterpret sections, resulting in incomplete or empty output.
  fix Double-check the input diff for strict adherence to the unified diff format. Use a reliable source for diff strings (e.g., `git diff`). Consider adding pre-parsing validation or sanitization steps for user-provided diffs.

Warnings

• breaking As a 0.x.x version, `parse-diff` adheres to a relaxed Semantic Versioning where minor versions (e.g., 0.11.0 to 0.12.0) *can* introduce breaking changes to the API or the structure of the parsed output. Always review release notes when updating.
  Fix: Always pin `parse-diff` to an exact version (e.g., `"parse-diff": "0.12.0"`) or use a tilde (`~0.12.0`) in `package.json` to prevent unexpected breaking changes with minor updates. Thoroughly test your application after any upgrade.
• gotcha The parser expects input in a strict unified diff format. Malformed or non-standard diff strings may lead to unexpected results, such as empty arrays being returned or incomplete parsing, rather than explicit errors.
  Fix: Ensure the input `diffString` strictly adheres to the unified diff format. Pre-validate input if it comes from untrusted or variable sources. For Git-specific diffs, ensure `git diff --unified` output is used.
• gotcha For very large diff files (e.g., hundreds of thousands of lines), parsing can be memory-intensive due to the entire diff string being loaded into memory and the resulting object structure. This can lead to performance bottlenecks or out-of-memory errors in resource-constrained environments.
  Fix: Consider breaking down extremely large diffs into smaller, manageable chunks if possible, or explore streaming parsers if available for very large scale diff processing. Profile memory usage when dealing with large inputs.

Install

• npm install parse-diff npm
• yarn add parse-diff yarn
• pnpm add parse-diff pnpm

Imports

• parse
  wrong:

  import { parse } from 'parse-diff';

  correct:

  import parse from 'parse-diff';

  The primary parsing function `parse` is a default export. Attempting a named import will result in a TypeError. This applies to both ESM and TypeScript contexts.
• parse
  wrong:

  const { parse } = require('parse-diff');

  correct:

  const parse = require('parse-diff');

  In CommonJS environments, the `parse` function is exported as the module.exports object directly. Destructuring it (e.g., `{ parse }`) will cause a TypeError as `parse` won't be found as a property.
• File structure types

  import type { File, Chunk, Change } from 'parse-diff';

  TypeScript users can import type definitions for the parsed output structure (`File`, `Chunk`, `Change`) directly from the package for better type safety and autocompletion.

Quickstart

This example demonstrates how to parse a simple unified diff string and iterate through the resulting file, chunk, and change objects, logging their properties.

import parse from 'parse-diff';

const diffString = `diff --git a/README.md b/README.md
index c96dc36..0e564d2 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
 # parse-diff
 
 Simple unified diff parser for JavaScript
 
-## JavaScript Usage Example
+## Usage Example
+
 `;

const files = parse(diffString);

console.log(`Number of patched files: ${files.length}`);

files.forEach(file => {
  console.log(`\nFile: ${file.from} -> ${file.to}`);
  console.log(`  Additions: ${file.additions}, Deletions: ${file.deletions}`);
  file.chunks.forEach(chunk => {
    console.log(`  Chunk content: ${chunk.content}`);
    chunk.changes.forEach(change => {
      console.log(`    Line (${change.type}): ${change.content}`);
    });
  });
});