III · Documents · Chapter 9
Version history and differences
How an office document's history is kept, how two versions are compared and why restoring does not delete.
A document's history is the quietest but most reassuring part of the system. The answer to "who changed this clause, and when?" is there the moment it is asked.
How it works
Every save produces a revision. The revision ledger cannot be changed: once a revision is written it is not overwritten. Each row holds who wrote it, when it was written and the file itself at that moment.
The panel opens next to the document and lists revisions from newest to oldest. Clicking a revision opens it; selecting two revisions compares them.
Two kinds of comparison
The system can show a difference in two separate ways, and their scope differs.
| Where it works | How it looks | |
|---|---|---|
| The editor's comparison | .docx only | Two revisions, as tracked changes |
| The difference panel | .docx, .xlsx, .pptx | A coloured, meaningful difference computed on the server |
Why does the difference panel exist? Because the editor's own highlighting cannot be coloured — it picks the colour per author itself — and it does not exist at all for spreadsheets and presentations. The difference computed on the server shows added, deleted and changed content separately: deleted text struck through, and in a spreadsheet the formula and the value separately.
When the content engines see no difference but the files do differ, the panel does not say "no difference": it reports at part level which component has changed (for example an embedded object).
The difference panel works with the document
The panel is not just a list; it talks to the open document:
- Show in document — each row knows its place in the new revision (cell, sheet, paragraph, slide, shape). Clicking takes the editor there; a cell is painted yellow for 1.5 seconds and then returns exactly to its old fill, and in Word and PowerPoint the changed place is marked in yellow.
- Restore the old value — a restorable change carries the old value exactly and writes it after checking that the place still holds the expected value. A formula cell whose result alone has changed cannot be restored; typing the old number by hand would delete the formula.
- Who changed this? — the person icon on a row searches the ledger backwards for the revision that first showed that value and tells you its label, date and author (at most 40 revisions). If it cannot be sure it does not invent a name: a wrong name on someone else's edit is worse than no name.
- Formatting and objects count as differences too — an added chart, a deleted picture, a cell painted yellow or a heading whose colour changed no longer pass as "no meaningful difference". Saving again still gives zero difference.
- Restoring a value or the whole document asks before writing; a back arrow clicked by mistake cannot silently write into the document.
Cowork uses the same panel as well: it reads versions, compares them and restores them on request (chapter 15).
Restoring
Restoring an old revision does not delete what came after it. The restore is added to the end of the ledger as a new revision. So "I went back three versions" becomes part of the history too, and can itself be undone if needed.
This is a deliberate choice: an undo that deletes history makes undoing itself risky.
The history of HTML fields
Besides office files, the free-text fields in the system carry versions too (chapter 4). The same idea in a different place: every revision stays with its author and time, and can be previewed, compared and restored.
The history travels with the file
An order sheet with 24 versions downloaded from a task and uploaded to a purchase order arrives in its new place with its history: the live office file carries its own history inside it, and it is preserved through opening, editing and saving in Word, Excel and PowerPoint. When the file is uploaded to another record its history comes back — original numbers, dates and sources; authors in the same database stay linked. Content edited outside PORTWARE becomes a new head version.
Files with tracked changes bring their history. When a Word file with Track Changes on, or a shared Excel workbook with a change log, is uploaded, the record is split into sessions and turned into versions (same author, gap shorter than 30 minutes). Version 1 is the state with every change rejected; the uploaded file is the head version. A log that cannot be safely rolled back (one that inserts rows or moves ranges) is not used — staying without history is right, rather than inventing a workbook.
The first edit of a document keeps its pre-edit state as version 1: a single edit is enough for a comparison.