-
Notifications
You must be signed in to change notification settings - Fork 608
word revision
The revision API exposes Word's tracked-changes surface — individual edits to runs, paragraphs, table cells/rows/cols, and section properties — under a single canonical key.
v1.0.98 rename: the legacy
trackChange.*keys are gone (no alias). Userevision.*. PackageProperties' per-save counter was simultaneously renamedrevision→revisionNumberso therevisionnamespace is free for tracked changes.
| Key | Purpose | Verbs |
|---|---|---|
revision.type |
Create a tracked change |
ins / del / format / moveFrom / moveTo
|
revision.action |
Act on an existing tracked change |
accept / reject
|
Bare revision=... is rejected up-front. Mixing revision.action with any creation key is rejected as ambiguous intent.
| Key | Notes |
|---|---|
revision.author |
Author name (also acts as a trigger for paragraph mark / row inserts when paired with add — see below) |
revision.date |
ISO timestamp; defaults to now (UTC) |
revision.id |
Numeric revision id; allocated from the shared paraId pool when omitted |
# Wrap a run as an insertion
officecli set report.docx /body/p[1]/r[1] --prop revision.type=ins --prop revision.author=Alice --prop revision.date=2026-05-20T10:00:00Z
# Mark a paragraph's content + ¶ as inserted (add path)
officecli add report.docx /body --type paragraph --prop text="New section" --prop revision.author=Alice
# Mark a row as inserted (row scope only — no cell-content cascade)
officecli add report.docx /body/tbl[1] --type row --prop revision.author=Alice
# Capture an rPrChange / pPrChange diff on a set
officecli set report.docx /body/p[1]/r[1] --prop bold=true --prop revision.type=format --prop revision.author=Bob
# Paired move-range markers
officecli move report.docx /body/p[3] --to /body --index 8 --prop revision.author=Alice
# (move + revision auto-pairs moveFrom/moveTo internally)
# Delete with a tracked deletion wrapper
officecli remove report.docx /body/p[5] --prop revision.author=Aliceset + revision.type also extends to sectPrChange / tblPrChange / trPrChange / tcPrChange, and table-level set + revision captures tblGridChange when the parent grid mutates. Per-row tblPrExChange cascades so Mac Word renders table-level revisions.
set --find … --replace … --prop revision.author=… performs a Word-UI-style tracked Find&Replace: matched text is wrapped as <w:del> (original) + <w:ins> (replacement) with the supplied author/date attribution.
officecli set report.docx / --find draft --replace final \
--prop revision.author=Alice --prop revision.date=2026-05-25T10:00:00ZWhole-document accept/reject:
officecli set report.docx /revision --prop revision.action=accept
officecli set report.docx /revision --prop revision.action=rejectPer-target via selector:
# By author
officecli set report.docx '/revision[@author=Alice]' --prop revision.action=accept
# By type
officecli set report.docx '/revision[@type=ins]' --prop revision.action=reject
# Combined filter
officecli set report.docx '/revision[@author=Bob][@type=del]' --prop revision.action=accept
# By index
officecli set report.docx /revision[3] --prop revision.action=accept/revision is the canonical path. When a revision carries w:id, the path keys off it (stable across edits); otherwise [N] is the fallback. Get loud-fails on missing @id rather than silently misrouting.
# Enumerate all revisions
officecli query report.docx revision
# Filter
officecli query report.docx 'revision[@author=Alice]'
officecli query report.docx 'revision[@type=format]'Query covers the full revision type set: ins, del, format, moveFrom, moveTo, paraMarkIns, rPrChange, pPrChange, sectPrChange, tblPrChange, trPrChange, tcPrChange, tblGridChange. The nativePath sub-key carries the underlying OOXML path for tooling.
These read-only keys surface on get / query revision nodes for the property-change and paragraph-mark revision shapes. They are created implicitly via revision.author / revision.date / revision.id on the host element (or on dump→batch replay), not set directly.
| Key | Type | Description |
|---|---|---|
paraMarkIns.author |
string | Author of a paragraph-mark-only insertion (the ¶ mark itself tracked as inserted, distinct from a run-level w:ins). On dump→batch the emitter rewrites it to bare revision.author on the synthetic paragraph. |
paraMarkIns.date |
string | ISO-8601 timestamp companion to paraMarkIns.author. |
paraMarkIns.id |
int |
w:id of the paragraph-mark insertion. Get-only companion to paraMarkIns.author/.date. |
paraMarkDel.author |
string | Author of a paragraph-mark deletion (the ¶ join tracked as a deletion). Deletion counterpart of paraMarkIns.author. |
paraMarkDel.date |
string | ISO-8601 timestamp companion to paraMarkDel.author. |
paraMarkDel.id |
int |
w:id of the paragraph-mark deletion. Get-only. |
sectPrChange.author |
string | Author of a w:sectPrChange on a section (revision.type=format equivalent at section scope; snapshot lives in a different OOXML wrapper than rPrChange/pPrChange). |
sectPrChange.date |
string | ISO-8601 timestamp companion to sectPrChange.author. |
sectPrChange.id |
string | Stable w:id companion to sectPrChange.author; preserved across dump→batch so the marker's identity survives the round-trip. |
tblPrChange.author |
string | Author of a w:tblPrChange on a table (table-properties revision — borders/style/layout snapshot). |
tblPrChange.date |
string | ISO-8601 timestamp companion to tblPrChange.author. |
trPrChange.author |
string | Author of a w:trPrChange on a table row (row-properties revision — row height/header/cantSplit snapshot). Separate from w:trPr/w:ins (= row insertion). |
trPrChange.date |
string | ISO-8601 timestamp companion to trPrChange.author. |
tcPrChange.author |
string | Author of a w:tcPrChange on a table cell (cell-properties revision — borders/shading/width snapshot). Separate from w:tcPr/w:cellIns/w:cellDel. |
tcPrChange.date |
string | ISO-8601 timestamp companion to tcPrChange.author. |
revision.beforeLost |
bool | Get-only signal: true when a *PrChange 'before' snapshot cannot round-trip through dump→batch (the prior-formatting baseline is lost on replay), letting the batch emitter warn rather than silently drop it. |
dump → batch round-trips real tblPrChange / trPrChange / tcPrChange diffs (not lossy synthesizations). Contiguous moveFrom / moveTo wraps are coalesced into single ranges. Per-row tblPrExChange uses unique revision ids on cascade so Mac Word doesn't fold them together.
| Word | Meaning |
|---|---|
revision |
Data — a tracked edit (this page) |
revisionNumber |
Per-save counter on docProps/core.xml, surfaced in Word's File → Info → Properties → Revision number
|
trackChanges |
Reserved for a future settings toggle (Word's "Track Changes" on/off button) |
-
Word run set —
revision.type/revision.actionon a run - Word paragraph set — paragraph + cell + row + col scopes
- Word reference
Based on OfficeCLI v1.0.105