Resolve conflicts
Two different things get called “a conflict”, and they happen at different moments. Telling them apart is most of the work.
| Save conflict | Merge conflict | |
|---|---|---|
| When | You press Save in the editor | You press Get updates on the Sync page |
| Cause | The file on disk changed since you opened it | A teammate published changes to lines you also changed |
| Where | A dialog on top of the editor | The Merge changes screen |
| Decision | One whole file wins | One choice per clashing passage |
A file changed on disk while you were editing
The editor records the file’s hash when it opens a document and sends it back with the save. If the file on disk no longer matches, nothing is written and a dialog appears: This page changed while you were editing — Someone else saved this document since you opened it. Compare the two versions, then choose how to continue. Two read-only boxes show the Markdown side by side, On disk (canonical) and Yours (raw), above three buttons:
- Keep editing — closes the dialog and leaves your work in the editor, unsaved.
- Discard mine & reload — reloads the document from disk. Your edits are gone.
- Overwrite with mine — saves again with force, replacing the file on disk.
This is not a merge. One version wins whole. It fires when something outside the editor touched the file — a Get updates, a script, another checkout of the same folder.
A related dialog, This page was moved or deleted, appears when the file is gone entirely: The original document is gone. Save your work as a new document instead. Give it a title, and Save as new writes your text somewhere it can live.
A teammate published changes to lines you also changed
Get updates is a real Git pull. When Git cannot combine the two sides on its own, the Sync page answers Some changes clash with yours. Let’s merge them together. and shows a banner — Some changes clash and need merging — with a Merge changes button.
Step 1 — pick a document
The Merge changes screen lists each conflicting path with an Open link. Work through them in any order.
Step 2 — build the final version
Merge this document puts three panes side by side:
| Pane | Contents |
|---|---|
| Your version — What you wrote | your side, read-only |
| Final version — You build this | the result you are assembling, editable |
| Their version — What your teammate wrote | their side, read-only |
Everything that does not clash is already merged and appears, greyed, identically in all three panes — including edits both of you made in different parts of the same file. Only the passages Git could not reconcile are highlighted, numbered Conflict 1, Conflict 2, and so on, and tagged needs a choice until you decide.
Each conflict offers three buttons — Use mine, Use theirs, Keep both — plus a text box beneath them. The buttons fill the box; typing in it directly is equally valid. Whatever ends up in that box is what gets written. The tag flips to chosen and the toolbar counts N of M clashes chosen.
Auto-merge easy parts resolves every untouched conflict where only one side actually moved away from the common ancestor. It never overrides a choice you made, leaves genuine disagreements alone, and jumps to the first one still open.
Save this document is enabled once every clash is chosen. It writes the assembled text to disk, stages it, and moves you to the next conflicting document, or back to the list.
Step 3 — finish
When the list is empty you get Every clash is resolved, an optional Merge note, and
Save the merge. That creates one merge commit — with both sides as parents — using your note
as the message, or Merge team updates if you leave it blank. The response is Merge complete.
Your documents are back in sync.
That commit is local. The merged result reaches the team only when you Publish.
When a file was deleted on one side
The same three panes handle every case; one side is simply empty. If a teammate deleted a page you edited, Their version is blank, and choosing it writes an empty file rather than removing it — delete the document afterwards in the editor. If both of you added a different file at the same path, there is no common ancestor and every line reads as a clash.
Things that will surprise you
[!WARNING] Cancel merge is a hard reset, not an undo of the merge alone. It runs
git reset --hard HEAD, discarding every uncommitted change in the docs folder — the incoming changes and your unsnapshotted edits to unrelated documents alike. The confirmation says Your saved snapshots are kept, but the changes you were merging in will be undone, and “saved snapshots” means commits: anything you only pressed Save on is not one. Save a snapshot is disabled while a merge is in progress, so you cannot rescue that work halfway through. Snapshot or copy anything you care about before you cancel.
A few more honest edges:
- Overwrite with mine keeps no copy of the version it replaces. If that version was never committed, it is gone. If it was, Git still has it.
- Save the merge commits the whole working tree, not just the files you merged. Unrelated saved edits ride along in the merge commit.
- The merge view reads both sides as UTF-8 text. A conflicting binary attachment appears in the list like any other path but has no meaningful side-by-side view — decide which file you want and re-upload it.
- There is no real-time co-editing and no locking. Save-conflict detection plus this merge is the entire concurrency model.
Avoiding most of them
- Press Get updates before starting a long edit, not after finishing one.
- Publish in small units. A day of unpublished work conflicts far more than an hour of it.
- Split pages people edit together. Two writers in one document clash; two writers in two documents merge silently.