Quickstart

Create two TypeScript files to see how Differens reports a rename and body edits. Install the CLI before running the examples.

Create two files

Save this as before.ts:

type Item = { price: number };

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

export const TAX_RATE = 0.08;

Save this as after.ts:

type Item = { price: number };

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;

Compare them

differens before.ts after.ts

From a source checkout, use cargo run -p differens -- before.ts after.ts. The native CLI prints:

  ~ renamed function `computeTotal` to `calculateTotalAmount`
  ~ modified function `computeTotal` (1 removal)
  ~ modified function `calculateTotalAmount` (3 additions)

The rename appears on its own line. Body and parameter edits are grouped under the function that contains them. Removals use the old name; additions use the new name. The unchanged TAX_RATE declaration produces no output. Terminal and Markdown reports group related edits for reading. JSON keeps the individual actions, so its action count can be larger than the displayed summary.

Read the underlying actions

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

Each array entry has an action, a description, and a filePath. The action contains its type (Insert, Delete, Update, or Move), node metadata, and nearest-first context. To inspect the rename without printing its full tree:

differens before.ts after.ts --format=json | jq '.[0] | {description, filePath, type: .action.type, detail: .action.detail}'

{
  "description": "renamed function `computeTotal` to `calculateTotalAmount`",
  "filePath": "before.ts",
  "type": "Update",
  "detail": {
    "kind": "Renamed",
    "from": "computeTotal",
    "to": "calculateTotalAmount"
  }
}

For a compact report with source lines, use --format=llm:

differens/1 1 files 5 changes 3 named
# before.ts
~ function calculateTotalAmount :3 computeTotal -> calculateTotalAmount
~ modified function computeTotal (1 removal) :4
~ modified function calculateTotalAmount (3 additions) :5

See machine outputs for schemas, streaming records, and source-coordinate conventions.

Compare a repository or directories

Inside a Git repository, running differens without arguments compares the working tree against HEAD, including staged, unstaged, and untracked files.

differens
differens main..feature
differens HEAD~1 HEAD

To compare two directory snapshots:

differens old/ new/

Repository and directory comparisons can detect moves across files. Exact moves need matching content; modified declaration moves must keep the same name and meet the similarity threshold. A move combined with a rename or major rewrite may remain an addition and a removal. See the CLI reference for options and configuration, or Git integration to use Differens through git diff.

See the same edit in a working tree

If the original function is committed in src/checkout.ts and you make the edit above, run differens from the repository root. The report groups the edits and adds a changeset summary:

  ~ renamed function `computeTotal` to `calculateTotalAmount`
  ~ modified function `computeTotal` (1 removal)
  ~ modified function `calculateTotalAmount` (3 additions)

3 modifications

To compare committed work, use differens main..feature or differens HEAD~1 HEAD. Direct file comparisons do not need a Git repository.

Follow a move between directories

A directory comparison uses matching relative paths, then checks additions and removals for cross-file moves. For example, moving an unchanged formatPrice between two existing files produces:

differens old/ new/

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

1 cross-file move

The cross-file walkthrough includes every file needed to reproduce this example and then edits the moved function to show a modified move.

Getting Started

How It Works

Guides