Quickstart

You will have your first semantic diff in under a minute. It takes two files and one command.

Step 1: Create two files

Create before.ts and after.ts. The example function is renamed and gains a parameter:

// before.ts
export function computeTotal(items: Item[]): number {
  return items.reduce((acc, item) => acc + item.price, 0);
}

export const TAX_RATE = 0.08;

// after.ts
export function calculateTotalAmount(items: Item[], discount: number): number {
  const base = items.reduce((acc, item) => acc + item.price, 0);
  return base - discount;
}

export const TAX_RATE = 0.08;

Step 2: Run the diff

differens before.ts after.ts

npx differens before.ts after.ts

Step 3: Read the output

  ~ renamed function `computeTotal` to `calculateTotalAmount`
  - removed return from function `computeTotal`
  + added return in function `calculateTotalAmount`
  + added variable `base` in function `calculateTotalAmount`
  + added required param in function `calculateTotalAmount`

Each line is a typed edit action prefixed with an icon: ~ update, + insert, - delete. The function rename is one action, not a delete and an insert. Compare that to a line diff of the same change:

- export function computeTotal(items: Item[]): number {
-   return items.reduce((acc, item) => acc + item.price, 0);
+ export function calculateTotalAmount(items: Item[], discount: number): number {
+   const base = items.reduce((acc, item) => acc + item.price, 0);
+   return base - discount;
  }

The line diff says the whole function was deleted and rewritten. Differens says: the function was renamed, a parameter was added, a variable was added, and the return was replaced.

Nodes that did not change (like TAX_RATE) produce no output. The diff core only emits actions for nodes that differ between the two trees.

Step 4: Try JSON output

Pass --format=json for machine-readable output:

differens before.ts after.ts --format=json

[
  {
    "type": "Update",
    "node": { "kind": "Function", "label": "calculateTotalAmount" },
    "detail": { "kind": "Renamed", "from": "computeTotal", "to": "calculateTotalAmount" },
    "context": [
      { "kind": "Export", "label": "" },
      { "kind": "file", "label": "" }
    ]
  },
  {
    "type": "Delete",
    "node": { "kind": "Return", "label": "" },
    "context": [
      { "kind": "Block", "label": "" },
      { "kind": "Function", "label": "computeTotal" }
    ]
  },
  {
    "type": "Insert",
    "node": { "kind": "Return", "label": "" },
    "context": [
      { "kind": "Block", "label": "" },
      { "kind": "Function", "label": "calculateTotalAmount" }
    ]
  }
]

Each entry is one typed edit action: Insert, Delete, Update, or Move. The context field gives the containment chain (nearest ancestor first) so you can reconstruct where every change happened. See Machine Outputs for the full schema and the compact --format=llm mode.

Step 5: Diff a git working tree

Run differens with no arguments inside a git repository. It diffs the working tree against HEAD:

cd your-project
differens

src/utils.ts
  ~ renamed function `computeTotal` to `calculateTotalAmount`
  + added variable `timeout` in module `utils`

src/app.ts
  ~ changed value of port from `3000` to `8080`

  cross-file moves:
  → function `formatPrice` from src/old/utils.ts to src/new/utils.ts

3 modifications, 1 move

You can also diff a commit range:

differens main..feature

Or two specific commits:

differens 8f3a1c2 5b0e9d7

Step 6: Diff two directories

Compare two directories. Files present in both are diffed; files only on one side show as additions or removals:

differens old/ new/

src/utils.ts
  ~ renamed function `parseConfig` to `loadConfig`

src/models.ts
  ~ renamed interface `CartItem` to `LineItem`

  cross-file moves:
  → renamed file src/helpers/math.ts to src/utils/math.ts

146 modifications, 1 move

What’s next

CLI reference: every command, flag, and format
Guides: git integration, machine outputs, and benchmarks
How it works: the matching algorithm, tier pipeline, and cross-file correlation

Getting Started

How It Works

Guides

Quickstart

Quickstart

Step 1: Create two files

Step 2: Run the diff

Step 3: Read the output

Step 4: Try JSON output

Step 5: Diff a git working tree

Step 6: Diff two directories

What’s next

​Quickstart

​Step 1: Create two files

​Step 2: Run the diff

​Step 3: Read the output

​Step 4: Try JSON output

​Step 5: Diff a git working tree

​Step 6: Diff two directories

​What’s next

Quickstart

Step 1: Create two files

Step 2: Run the diff

Step 3: Read the output

Step 4: Try JSON output

Step 5: Diff a git working tree

Step 6: Diff two directories

What’s next