On this page

Review: baseline, accept and reject, versions

Wymark’s review model rests on one idea: every edit is already saved in your file; the baseline is what you are comparing against until you accept.

When you open a file, Wymark remembers a baseline – the last state you explicitly acknowledged. From then on, every change reaches the file promptly and in order, whether you typed it, another app or script wrote it, or an assistant you asked for help edited it. Whenever the file differs from the baseline, the difference appears as a diff: highlighted changes, grouped into hunks, each with its own accept and reject controls.

There is nothing to turn on. No track-changes mode to remember, no staging, no commit. If the file changed and you have not signed off on the change, it is in front of you. The one case the diff cannot show, a write from outside that undoes an edit of yours, gets a card of its own.

Coming from Word or Google Docs

In Word, track changes is a mode: if the author forgot to turn it on, the edits are invisible. And the marked-up document is not the “real” document until changes are accepted. Wymark inverts both: review is always on, and the file on disk is always the real, current document. Accepting does not apply a change – the change is already in the file – it records that you have seen and approved it.

Writing markdown, not using git

If you write markdown without git, you may never have had review at all: the file just changes, and your safety net is undo. Wymark keeps that simplicity – the file still just changes, autosaved continuously – and adds a memory of what you last approved, so anything new (especially something an AI wrote while you were away) is highlighted until you have looked at it.

Using git

The baseline plays the role of HEAD in git diff: the diff is always diff(baseline, file). But there is no staging area and no commit object. Accepting a hunk advances the baseline for just those lines – as if that hunk alone were committed – while the working tree (the file) is untouched, because the file already contains the change. Rejecting a hunk is git checkout -- <path> scoped to that hunk: the file reverts, the baseline stays.

Accept and reject

Each hunk in the diff carries two controls:

  • Accept records the change into the baseline. The file is not touched – it already contains the change. The hunk disappears from the diff.
  • Reject reverts the file to the baseline’s content for that hunk. The baseline is not touched. The change is undone in your document.

The toolbar’s Accept all and Reject all apply the same actions to every remaining hunk at once. When everything is accepted or rejected, baseline and file are equal again and the diff is empty – until the next change.

Accept and reject are part of the same undo history as typing: one Cmd+Z stack covers text edits and review decisions, in order.

Working through the changes

The status chip at the foot of the comment cards counts the pending changes and the comments. Its arrows step to the next or previous change (⌥⌘→, ⌥⌘←) and bring it into view without moving your caret. While you step, the count reads as a position, change 3/11, and it wraps at either end. For the change it names, the chip shows a check and an x: accept (⌥⌘A) or reject (⌥⌘X), and on to the next one.

How much one change holds is a setting: Settings > Review & comments > Review changes by.

  • Paragraph, the default: usually one change per changed paragraph, heading, list item or code block.
  • Sentence: an edited paragraph is also split at sentence ends, wherever unchanged text separates two edits.

Text that arrives or goes whole is never split by sentence. An added section is one change per block, so you can keep three new paragraphs and reject the fourth. A deleted section is one change per heading inside it.

Your changes and incoming changes

Green and red show changes against the baseline. Blue shows your own changes since the last accept. Everything else came in from outside Wymark: another app, a script, a sync client, a connected assistant writing the file, or an edit you made while Wymark was closed.

That split is what lets you refine a change before you accept it. A paragraph arrives rewritten; it is close, but you would phrase one sentence differently. Edit it where it stands: your words turn blue, the rest stays green, and what arrived stays distinguishable from what you changed.

  • It is just colour. There is still one file, one diff. The colours are attribution painted on the diff – they never split your document or change what gets saved.
  • Word by word. Green and blue words coexist on the same line; refining one word does not repaint the green around it.
  • Nothing to switch. Everything you type or paste in Wymark is yours. To bring in text from elsewhere as an incoming change, use Edit > Paste as Incoming Change (Cmd+Shift+V) or the same item in the editor’s right-click menu; after an ordinary paste of outside text, Wymark offers to mark it as incoming.
  • Hover to see what you replaced. When your edit overwrites incoming text, the file keeps only the final words – but resting your pointer on the change shows the text it replaced. So after refining “green tea” to “herbal tea”, hovering “herbal” still shows you the “green” it stood in for.

Accepting and rejecting do not care about the colours: you accept or reject the result – the file against the baseline – exactly as before. The colours are there so you can see and weigh both kinds of change together before you decide; once you accept, the distinction has done its job and is cleared.

Coming from Word or Google Docs

The closest Word analogue is per-author colours in track changes – but here the split is by where a change came from, not by who you are, and you can refine incoming text in place without accepting it first. And as everywhere in Wymark, the colours annotate one real file rather than a separate marked-up copy.

Versions

The baseline is internal – you never see it listed anywhere. Versions are the checkpoints you create on purpose:

  • Save version (Cmd+S) snapshots the current file into the Versions panel. It does not touch the baseline: a pending review stays exactly as it was, so you can checkpoint mid-review as often as you like. Saving is “keep this state”; signing off is a separate gesture.
  • Accept all and Reject all are the sign-off. Each also saves a version automatically (labelled Accepted / Resolved in the panel), as does resolving the last remaining hunk by hand – so finishing a review always leaves a restorable checkpoint behind.
  • Versions can be named, at save time or later; the panel filters between All and Named, and shows Overwritten once a write from outside Wymark has replaced text you had in the document.
  • Restore loads a past version as both the file and the baseline. Before doing so, Wymark automatically saves the current state as a new version (Pre-restore) – a restore never loses work and is itself reversible from the Versions panel.

Versions and the baseline are deliberately independent: a version is a thing (a saved state, listed in the panel), the baseline is a role (whatever the review is currently measured against). Only accept, reject and restore move the baseline; saving never does.

Review from here points the review at something else: pick a version (or, in a git repository, a commit) and it becomes what your document is measured against. The document itself is not touched – only the comparison moves, and accept and reject then work on that diff exactly as they did before. The anchor you left is saved as a version labelled Was baseline, so one click gets you back. This is one entry in a wider vs … menu – see comparing against git and past versions for the rest, including the read-only overlays that don’t move the baseline at all.

Coming from Word or Google Docs

Versions are the equivalent of “Save a copy” milestones, except they live in one panel and never produce report-final-v2-FINAL.docx. The baseline is not a version – it is closer to the invisible line Word draws between “original text” and “tracked changes.”

Using git

Inside a git repository Wymark reads your history too, and never writes to it – see comparing against git and past versions for the full vs … menu and the Versions panel’s Git filter. Without a repository, none of it appears, and nothing else changes.

Save version is the closest thing to a commit: a durable, restorable, nameable snapshot. The differences: it is linear (no branches, no DAG), names are editable after the fact, and saving does not move the baseline – there is no implicit “accept all”; Accept all is its own button, and it is the one that checkpoints. The baseline itself is more like the index than like a commit: it advances hunk by hunk as you accept, and it is never listed as a version in its own right.

When the file is written from outside Wymark

Wymark takes the file exactly as it was written. It does not write a merge of its own back over it, whether the writer was another editor, a script, a sync client, git checkout, or a tool working from an older copy of the document. The one thing it adds is typing of yours that had not been saved yet, which is merged in around the write.

Most writes from outside show up as changes to review. The exception is a write that undoes something you did: words you had added are gone and the place reads as the baseline does, or text you had deleted is back. The review has nothing to show there, so Wymark shows a card at the place instead:

  • Removed outside Wymark shows your words. Put back returns them; Keep leaves the file as it is.
  • Brought back outside Wymark shows the text that returned. Delete again removes it; Keep leaves it.
  • Reply removed outside Wymark shows replies that went from a comment thread that is still there. Put back returns them; Keep leaves the thread as it is.

Put back and Delete again are ordinary edits of yours, and one undo step. A notice says what the write took out, and it waits until the Wymark window is in front.

Two wider nets sit under the cards. ⌘Z takes back everything written from outside since you last touched the document, as one step, for as long as the document stays open. And the text from before the write is kept in the Versions panel under Overwritten, for thirty days.

What the cards do not cover:

  • Words of yours that went from a paragraph that is itself a pending change get no card. The review shows the paragraph as changed, and the earlier text is under Overwritten.
  • A whole comment thread removed from outside gets the notice and no card, because that is also how a tool resolves a thread when you ask it to.
  • Wymark finds these places from its record of which text is yours. Where that record is wrong, a card can be missing; the text under Overwritten is kept either way.

What survives a restart

Accepted changes are durable: the baseline is persisted on your machine, so closing and reopening a document does not resurrect already-reviewed changes as a new diff. Versions are durable too. The fine-grained undo stack is not – after a restart, reversing an accepted change means restoring a version rather than pressing Cmd+Z.

A typical session on a colleague’s branch

  1. A colleague pushes a rewrite of chapter.md and you check out their branch. The folder is a git repository, so the vs … menu offers the commits in the file’s history and the point where the branch diverged.
  2. Review from here on the branch point makes it the baseline: every paragraph they changed is a hunk with its own controls, exactly as if they had typed it in front of you.
  3. You accept what you agree with and reject the two paragraphs you do not – the file reverts those, ready to commit as your reply. Where you want to argue rather than decide, you leave a comment; it travels in the file.
  4. Cmd+S saves a version. Git is untouched throughout: Wymark reads your history and never writes to it.

A typical session with an assistant

  1. You open chapter.md and turn on its AI sidecar, so the agent can see your review as well as your file. You ask it to tighten the prose, and it edits the file directly.
  2. Wymark shows every edit as a diff against your baseline the moment it lands – you can watch the file while the agent works, in either the WYSIWYG or the raw view.
  3. You accept the good hunks, reject the two where the agent got clever with your phrasing. The file now contains exactly what you approved.
  4. Cmd+S – the result is a version, and the slate is clean for the next round.

What the diff will not do

The honest fine print, covered in depth in the diff design note:

  • The diff is line-based. A paragraph moved unchanged is detected and labelled as a move (“Moved up”, “Moved down”); a paragraph that was moved and edited reads as a deletion plus an insertion, because the engine only calls something a move when the evidence is exact.
  • Adjacent changes can lump into one hunk, so accept/reject is sometimes coarser than you might want.
  • Changes that render identically (reflowed line breaks, equivalent markup spellings) are deliberately not shown as changes.

The diff is always correct – it describes exactly how the file differs from the baseline, and accept/reject always do exactly what they say. It is not always the prettiest possible story about how the document evolved.


# Review: baseline, accept and reject, versions

Wymark's review model rests on one idea: **every edit is already saved in your file; the baseline is what you are comparing against until you accept.**

When you open a file, Wymark remembers a *baseline* -- the last state you explicitly acknowledged. From then on, every change reaches the file promptly and in order, whether you typed it, another app or script wrote it, or an assistant you asked for help edited it. Whenever the file differs from the baseline, the difference appears as a diff: highlighted changes, grouped into hunks, each with its own accept and reject controls.

There is nothing to turn on. No track-changes mode to remember, no staging, no commit. If the file changed and you have not signed off on the change, it is in front of you. The one case the diff cannot show, a write from outside that undoes an edit of yours, gets [a card of its own](#when-the-file-is-written-from-outside-wymark).

:::persona word
In Word, track changes is a mode: if the author forgot to turn it on, the edits are invisible. And the marked-up document is not the "real" document until changes are accepted. Wymark inverts both: review is always on, and the file on disk is always the real, current document. Accepting does not apply a change -- the change is already in the file -- it records that you have seen and approved it.
:::

:::persona markdown
If you write markdown without git, you may never have had review at all: the file just changes, and your safety net is undo. Wymark keeps that simplicity -- the file still just changes, autosaved continuously -- and adds a memory of what you last approved, so anything new (especially something an AI wrote while you were away) is highlighted until you have looked at it.
:::

:::persona git
The baseline plays the role of HEAD in `git diff`: the diff is always `diff(baseline, file)`. But there is no staging area and no commit object. Accepting a hunk advances the baseline for just those lines -- as if that hunk alone were committed -- while the working tree (the file) is untouched, because the file already contains the change. Rejecting a hunk is `git checkout -- <path>` scoped to that hunk: the file reverts, the baseline stays.
:::

## Accept and reject

Each hunk in the diff carries two controls:

- **Accept** records the change into the baseline. The file is not touched -- it already contains the change. The hunk disappears from the diff.
- **Reject** reverts the file to the baseline's content for that hunk. The baseline is not touched. The change is undone in your document.

The toolbar's **Accept all** and **Reject all** apply the same actions to every remaining hunk at once. When everything is accepted or rejected, baseline and file are equal again and the diff is empty -- until the next change.

Accept and reject are part of the same undo history as typing: one Cmd+Z stack covers text edits and review decisions, in order.

## Working through the changes

The status chip at the foot of the comment cards counts the pending changes and the comments. Its arrows step to the next or previous change (`⌥⌘→`, `⌥⌘←`) and bring it into view without moving your caret. While you step, the count reads as a position, `change 3/11`, and it wraps at either end. For the change it names, the chip shows a check and an x: accept (`⌥⌘A`) or reject (`⌥⌘X`), and on to the next one.

How much one change holds is a setting: **Settings > Review & comments > Review changes by**.

- **Paragraph**, the default: usually one change per changed paragraph, heading, list item or code block.
- **Sentence**: an edited paragraph is also split at sentence ends, wherever unchanged text separates two edits.

Text that arrives or goes whole is never split by sentence. An added section is one change per block, so you can keep three new paragraphs and reject the fourth. A deleted section is one change per heading inside it.

## Your changes and incoming changes

Green and red show changes against the baseline. Blue shows your own changes since the last accept. Everything else came in from outside Wymark: another app, a script, a sync client, a connected assistant writing the file, or an edit you made while Wymark was closed.

That split is what lets you refine a change before you accept it. A paragraph arrives rewritten; it is close, but you would phrase one sentence differently. Edit it where it stands: your words turn blue, the rest stays green, and what arrived stays distinguishable from what you changed.

- **It is just colour.** There is still one file, one diff. The colours are attribution painted on the diff -- they never split your document or change what gets saved.
- **Word by word.** Green and blue words coexist on the same line; refining one word does not repaint the green around it.
- **Nothing to switch.** Everything you type or paste in Wymark is yours. To bring in text from elsewhere as an incoming change, use **Edit > Paste as Incoming Change** (Cmd+Shift+V) or the same item in the editor's right-click menu; after an ordinary paste of outside text, Wymark offers to mark it as incoming.
- **Hover to see what you replaced.** When your edit overwrites incoming text, the file keeps only the final words -- but resting your pointer on the change shows the text it replaced. So after refining "green tea" to "herbal tea", hovering "herbal" still shows you the "green" it stood in for.

Accepting and rejecting do **not** care about the colours: you accept or reject the *result* -- the file against the baseline -- exactly as before. The colours are there so you can see and weigh both kinds of change together before you decide; once you accept, the distinction has done its job and is cleared.

:::persona word
The closest Word analogue is per-author colours in track changes -- but here the split is by where a change came from, not by who you are, and you can refine incoming text in place without accepting it first. And as everywhere in Wymark, the colours annotate one real file rather than a separate marked-up copy.
:::

## Versions

The baseline is internal -- you never see it listed anywhere. *Versions* are the checkpoints you create on purpose:

- **Save version** (Cmd+S) snapshots the current file into the Versions panel. It does **not** touch the baseline: a pending review stays exactly as it was, so you can checkpoint mid-review as often as you like. Saving is "keep this state"; signing off is a separate gesture.
- **Accept all** and **Reject all** are the sign-off. Each also saves a version automatically (labelled *Accepted* / *Resolved* in the panel), as does resolving the last remaining hunk by hand -- so finishing a review always leaves a restorable checkpoint behind.
- Versions can be **named**, at save time or later; the panel filters between **All** and **Named**, and shows **Overwritten** once a write from outside Wymark has replaced text you had in the document.
- **Restore** loads a past version as both the file and the baseline. Before doing so, Wymark automatically saves the current state as a new version (*Pre-restore*) -- a restore never loses work and is itself reversible from the Versions panel.

Versions and the baseline are deliberately independent: a version is a *thing* (a saved state, listed in the panel), the baseline is a *role* (whatever the review is currently measured against). Only accept, reject and restore move the baseline; saving never does.

**Review from here** points the review at something else: pick a version (or, in a git repository, a commit) and it becomes what your document is measured against. The document itself is not touched -- only the comparison moves, and accept and reject then work on that diff exactly as they did before. The anchor you left is saved as a version labelled *Was baseline*, so one click gets you back. This is one entry in a wider `vs …` menu -- see [comparing against git and past versions](/docs/concepts/git) for the rest, including the read-only overlays that don't move the baseline at all.

:::persona word
Versions are the equivalent of "Save a copy" milestones, except they live in one panel and never produce `report-final-v2-FINAL.docx`. The baseline is not a version -- it is closer to the invisible line Word draws between "original text" and "tracked changes."
:::

:::persona git
Inside a git repository Wymark reads your history too, and never writes to it -- see [comparing against git and past versions](/docs/concepts/git) for the full `vs …` menu and the Versions panel's Git filter. Without a repository, none of it appears, and nothing else changes.

Save version is the closest thing to a commit: a durable, restorable, nameable snapshot. The differences: it is linear (no branches, no DAG), names are editable after the fact, and saving does *not* move the baseline -- there is no implicit "accept all"; Accept all is its own button, and it is the one that checkpoints. The baseline itself is more like the index than like a commit: it advances hunk by hunk as you accept, and it is never listed as a version in its own right.
:::

## When the file is written from outside Wymark

Wymark takes the file exactly as it was written. It does not write a merge of its own back over it, whether the writer was another editor, a script, a sync client, `git checkout`, or a tool working from an older copy of the document. The one thing it adds is typing of yours that had not been saved yet, which is merged in around the write.

Most writes from outside show up as changes to review. The exception is a write that undoes something you did: words you had added are gone and the place reads as the baseline does, or text you had deleted is back. The review has nothing to show there, so Wymark shows a card at the place instead:

- **Removed outside Wymark** shows your words. `Put back` returns them; `Keep` leaves the file as it is.
- **Brought back outside Wymark** shows the text that returned. `Delete again` removes it; `Keep` leaves it.
- **Reply removed outside Wymark** shows replies that went from a comment thread that is still there. `Put back` returns them; `Keep` leaves the thread as it is.

`Put back` and `Delete again` are ordinary edits of yours, and one undo step. A notice says what the write took out, and it waits until the Wymark window is in front.

Two wider nets sit under the cards. `⌘Z` takes back everything written from outside since you last touched the document, as one step, for as long as the document stays open. And the text from before the write is kept in the Versions panel under **Overwritten**, for thirty days.

What the cards do not cover:

- Words of yours that went from a paragraph that is itself a pending change get no card. The review shows the paragraph as changed, and the earlier text is under Overwritten.
- A whole comment thread removed from outside gets the notice and no card, because that is also how a tool resolves a thread when you ask it to.
- Wymark finds these places from its record of which text is yours. Where that record is wrong, a card can be missing; the text under Overwritten is kept either way.

## What survives a restart

Accepted changes are durable: the baseline is persisted on your machine, so closing and reopening a document does not resurrect already-reviewed changes as a new diff. Versions are durable too. The fine-grained undo stack is not -- after a restart, reversing an accepted change means restoring a version rather than pressing Cmd+Z.

## A typical session on a colleague's branch

1. A colleague pushes a rewrite of `chapter.md` and you check out their branch. The folder is a git repository, so the `vs …` menu offers the commits in the file's history and the point where the branch diverged.
2. **Review from here** on the branch point makes it the baseline: every paragraph they changed is a hunk with its own controls, exactly as if they had typed it in front of you.
3. You accept what you agree with and reject the two paragraphs you do not -- the file reverts those, ready to commit as your reply. Where you want to argue rather than decide, you leave a comment; it travels in the file.
4. Cmd+S saves a version. Git is untouched throughout: Wymark reads your history and never writes to it.

## A typical session with an assistant

1. You open `chapter.md` and turn on its [AI sidecar](/docs/guide/ai-sidecar), so the agent can see your review as well as your file. You ask it to tighten the prose, and it edits the file directly.
2. Wymark shows every edit as a diff against your baseline the moment it lands -- you can watch the file while the agent works, in either the WYSIWYG or the raw view.
3. You accept the good hunks, reject the two where the agent got clever with your phrasing. The file now contains exactly what you approved.
4. Cmd+S -- the result is a version, and the slate is clean for the next round.

## What the diff will not do

The honest fine print, covered in depth in [the diff design note](/docs/how-it-works/diff):

- The diff is line-based. A paragraph moved *unchanged* is detected and labelled as a move ("Moved up", "Moved down"); a paragraph that was moved *and* edited reads as a deletion plus an insertion, because the engine only calls something a move when the evidence is exact.
- Adjacent changes can lump into one hunk, so accept/reject is sometimes coarser than you might want.
- Changes that render identically (reflowed line breaks, equivalent markup spellings) are deliberately not shown as changes.

The diff is always *correct* -- it describes exactly how the file differs from the baseline, and accept/reject always do exactly what they say. It is not always the *prettiest possible story* about how the document evolved.