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

# Git Integration

> Use Differens as your git diff tool

# Git Integration

Differens plugs into your normal `git diff` workflow. Instead of line hunks, it reports the semantic changes: renames, moves, added parameters.

## Install the driver

One command registers Differens as a git diff driver in your repo's local config, then prints the `.gitattributes` lines you need to opt files in:

<CodeGroup>
  ```bash Register the driver theme={null}
  differens install-git-driver
  ```

  ```text Output theme={null}
  git diff driver installed.
  add to .gitattributes:
    *.ts diff=differens
    *.tsx diff=differens
    *.js diff=differens
    *.jsx diff=differens
    *.py diff=differens
    *.rs diff=differens
    *.go diff=differens

  then `git diff` narrates those files instead of printing hunks.
  ```
</CodeGroup>

Add the `diff=differens` lines to `.gitattributes` (repo root or per-directory) for every extension you want covered. Files without the attribute keep normal `git diff` output.

Now `git diff` on a `.ts` file shows the change instead of a hunk:

<CodeGroup>
  ```text Before: git diff theme={null}
  - function computeTotal(items: Item[]): number {
  -   return items.reduce((acc, item) => acc + item.price, 0);
  + function calculateTotalAmount(items: Item[], discount: number): number {
  +   const base = items.reduce((acc, item) => acc + item.price, 0);
  +   return base - discount;
    }
  ```

  ```text After: differens driver theme={null}
    ~ renamed function `computeTotal` to `calculateTotalAmount`
    + added parameter `discount`

  1 modification, 1 addition
  ```
</CodeGroup>

The driver receives both versions of every changed file, so this works in `git diff`, `git diff --staged`, and `git difftool`. To remove the driver later, unset the config. See the note in the [git package reference](/reference/git).

## Standalone modes

No git driver required. `differens` reads git directly.

### Working tree

With no arguments, `differens` diffs the working tree against HEAD and correlates the changes across files:

```bash theme={null}
differens
```

This is `git diff HEAD` in semantic form. It picks up unstaged and staged changes. Untracked files are excluded.

### Commit ranges

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

Diffs every file that changed between two refs. Output is grouped per file, with cross-file moves reported at the end:

```text theme={null}
src/checkout.ts
  ~ renamed function `computeTotal` to `calculateTotalAmount`

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

3 modifications, 1 move
```

### Two commits

Both arguments resolve as git refs, so two SHAs or branch names diff like a range:

```bash theme={null}
differens 8f3a1c2 5b0e9d7
```

### Two directories

If both arguments are directories, Differens walks each one and diffs matching relative paths:

```bash theme={null}
differens release/1.0/ release/1.1/
```

Files present on only one side are whole-file additions or removals. Generated and vendor directories (`node_modules`, `dist`, `.git`, …) are skipped. Files over 2 MiB are treated as whole-file additions or removals.

## How it compares to git diff

|                      | `git diff`            | `differens`                                                   |
| -------------------- | --------------------- | ------------------------------------------------------------- |
| Unit                 | Lines                 | Logical changes                                               |
| A rename             | Delete + insert       | One `renamed` action                                          |
| A move between files | Delete + insert       | One `Move`, with the destination file                         |
| Reformatting         | Pure churn            | No changes reported                                           |
| Speed                | Instant on huge files | Parse + match per file (see [Benchmarks](/guides/benchmarks)) |