> ## Documentation Index
> Fetch the complete documentation index at: https://differens.ossl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run your first semantic diff in under a minute

# 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:

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

export const TAX_RATE = 0.08;
```

```typescript theme={null}
// 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

<CodeGroup>
  ```bash Terminal theme={null}
  differens before.ts after.ts
  ```

  ```bash npx (no install) theme={null}
  npx differens before.ts after.ts
  ```
</CodeGroup>

## Step 3: Read the output

```text theme={null}
  ~ 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:

```diff theme={null}
- 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.

<Info>
  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.
</Info>

## Step 4: Try JSON output

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

<CodeGroup>
  ```bash Command theme={null}
  differens before.ts after.ts --format=json
  ```

  ```json Output theme={null}
  [
    {
      "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" }
      ]
    }
  ]
  ```
</CodeGroup>

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](/guides/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`:

<CodeGroup>
  ```bash Command theme={null}
  cd your-project
  differens
  ```

  ```text Output (excerpt) theme={null}
  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
  ```
</CodeGroup>

You can also diff a commit range:

```bash theme={null}
differens main..feature
```

Or two specific commits:

```bash theme={null}
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:

<CodeGroup>
  ```bash Command theme={null}
  differens old/ new/
  ```

  ```text Output (excerpt) theme={null}
  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
  ```
</CodeGroup>

## What's next

* [CLI reference](/reference/cli): every command, flag, and format
* [Guides](/guides/git-integration): git integration, machine outputs, and benchmarks
* [How it works](/how-it-works/architecture): the matching algorithm, tier pipeline, and cross-file correlation