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

# Compare documents

`compareDocuments` does what Word's *Review › Compare* does. It takes an original and a revised file and returns the revised file with each difference written as a tracked change. *Accept All* then gives the revised file, and *Reject All* gives the original.

```ts theme={null}
import { readFile, writeFile } from "node:fs/promises";
import { compareDocuments } from "@reductoai/docx/node";

const original = await readFile("v1.docx");
const revised = await readFile("v2.docx");

const redline = await compareDocuments(original, revised, { author: "Compare" });
await writeFile("v1-vs-v2.docx", redline);
```

In a page, import `compareDocuments` from `@reductoai/docx/officejs`. It needs no fonts.

## Options

| Option | Default | Notes |
| - | - | - |
| `author` | — | Author of every revision the compare writes |
| `date` | now | Date of every revision |
| `formatting` | `true` | Also track formatting changes on kept text (Word's *Formatting* setting). Off, kept text takes the original's formatting |
| `whitespace` | `true` | Also track differences made only of spaces, tabs and line breaks inside a paragraph. Off, the revised file's whitespace stays, unmarked |

## How it marks changes

The compare follows Word's rules. It compares by word, so a changed number in a sentence is one small revision, not a rewritten paragraph:

```text theme={null}
Insert: 15 business
Delete: 30
Insert:  Time is of the essence.
Insert: 45
Delete: 60
```

Tables, lists, headers, footers and notes are compared too. Revisions that are already in either input are accepted first, as Word does.

Two rules decide which text matches, in compare and in combine:

* A long unchanged start of a paragraph fixes the match. Text added at the end of a paragraph stays in that paragraph, also when a removed list item after it has the same words.
* A field or an inline object counts as one character of a long shared stretch, whatever the size of its XML.

## Combine a returned copy

`combineDocuments` does what Word's *Review › Combine* does. Use it when you send a file that may hold your own tracked changes and get back a copy that the other side edited. The result is the returned copy. Its own tracked changes stay as written, by their authors and dates. Every untracked difference becomes a tracked change by `author`. Accept only that author's changes and you get the returned copy.

```ts theme={null}
import { combineDocuments } from "@reductoai/docx/node";

const merged = await combineDocuments(sent, returned, {
  author: "Untracked edits",
  originalRevisions: "reverse",
});
```

It takes the options above (`formatting` off keeps the returned copy's formatting, unmarked) and these:

| Option | Default | Notes |
| - | - | - |
| `originalRevisions` | `"keep"` | What happens to a tracked change of yours that the returned copy accepted or rejected |
| `pendingEdits` | `"ignore"` | Untracked edits inside an insertion that both copies still hold as a tracked change |

`originalRevisions`:

* `"keep"`: as Word, your tracked change stays as yours, also when the other side accepted or rejected it. Use this to combine the copies of several reviewers into one file.
* `"settle"`: your tracked change stays as the other side settled it. An accepted one is plain text, a rejected one is gone, and neither shows as a change.
* `"reverse"`: as `"settle"`, but each of your tracked changes that the returned copy no longer has counts as accepted. If the other side rejected it, it comes back as the opposite change by `author`: a rejected insertion is a deletion, a rejected deletion an insertion. Use this when the other side accepts everything and then edits. From the returned copy alone, a rejected change and an accepted change that was then undone by hand look the same. A change counts as still there when the returned copy has one of the same type and date. The author does not count, so a copy that renames its reviewers still matches.

When the returned copy turned off Different First Page, `"settle"` and `"reverse"` do this:

* The setting stays on, so the old first-page header and footer show as tracked changes. The setting itself is not a tracked change, also with `formatting` on.
* The first-page header and footer compare against the revised copy's default header and footer, also when the section inherits them. Accept All gives the revised first page, and Reject All gives the original first-page header and footer.
* Later sections keep the first-page header and footer they inherit, also when the sections between them are deleted.

Which one to use:

| You want | Use |
| - | - |
| What the other side changed since the copy you sent | `"reverse"` |
| One file with the tracked changes of several reviewers | `"keep"` |
| Only the tracked changes the other side still has, and you know they did not accept a change and then type its text again | `"settle"` |

`pendingEdits`:

* `"ignore"`: as Word, the edit is not marked. The insertion shows the returned copy's text, under its first author.
* `"deletions"`: deleted text is marked as a deletion by `author` inside that insertion. Text whose own tracked deletion the other side accepted stays gone.
* `"all"`: added text is marked too. A tracked insertion cannot hold another, so this splits the first author's insertion in two around it.

## Your own rule

`"reverse"` and `"settle"` are two rules for your tracked changes. To use a different rule, settle your tracked changes yourself before the combine, then use `"settle"`. Each revision has `type`, `author`, `date` and `text`, and `accept()` and `reject()`. A revision you do not accept or reject stays as a tracked change.

```ts theme={null}
import { combineDocuments, WordDocument } from "@reductoai/docx/node";

const mine = await WordDocument.fromBytes(sent);
const theirs = await WordDocument.fromBytes(returned);
const key = (r: { type: string; author: string; date: string }) => [r.type, r.author, r.date].join("|");
const held = new Set(theirs.revisions.items.map(key));

// This rule is "reverse": accept each change the returned copy no longer has
for (const rev of [...mine.revisions.items].reverse()) {
  if (!held.has(key(rev))) rev.accept();
}

const merged = await combineDocuments(await mine.toBytes(), returned, {
  author: "Untracked edits",
  originalRevisions: "settle",
});
```

Go through the revisions from last to first: when you accept or reject a revision, it leaves the list. Use `"settle"` here, not `"keep"`, so that the combine does not bring back the changes you settled.

You can also change the result. Open it with `WordDocument.fromBytes` and accept or reject its revisions by author before you show it.

## Try it

On the docs site, this block is a playground. Drop your own files on A and B, or use the sample pair: a contract sent with Alice's and Bob's tracked changes, and the copy Dana sent back. Change the options and the result C updates. *Accept* shows C with only the label's changes accepted, which reads as B.

```json theme={null}
{ "mode": "combine", "author": "Untracked edits", "originalRevisions": "reverse" }
```

Live example

## Read the result

The result is a normal document. Open it with OfficeJS to list, accept or reject the changes:

```ts theme={null}
import { WordDocument } from "@reductoai/docx/node";

const doc = await WordDocument.fromBytes(redline);
for (const rev of doc.revisions.items) console.log(rev.type, rev.text);
```

Or render it with markup: `npx docx pdf v1-vs-v2.docx --tracked-changes inline`.
