word revision

Word: Revision (tracked changes)

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). Use revision.*. PackageProperties' per-save counter was simultaneously renamed revision → revisionNumber so the revision namespace is free for tracked changes.

Two namespaces

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.

Attribution sub-keys (used with revision.type)

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

Creating revisions

# 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=Alice

set + 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.

Tracked Find & Replace

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:00Z

Acting on revisions

Whole-document accept/reject:

officecli set report.docx /revision --prop revision.action=accept
officecli set report.docx /revision --prop revision.action=reject

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

Query

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

Round-trip

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.

Disambiguation

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)

See Also

• Word run set — revision.type / revision.action on a run
• Word paragraph set — paragraph + cell + row + col scopes
• Word reference

---

Based on OfficeCLI v1.0.105