How does GitBook resolve merge conflicts during simultaneous two-way sync?

The short answer

GitBook's two-way Git sync is not a real-time merge engine, and it does not expose a native conflict-resolution UI comparable to a Git three-way merge. When the same page changes on both sides — a direct commit to the linked GitHub branch and an edit in the GitBook web editor — the reconciliation generally favors the remote repository on the next pull. Unpublished editor-side changes in the conflicted page can be overwritten rather than surfaced for manual resolution. Treat the following as the likely behavior, not a guaranteed contract: exact sync direction, frequency, and overwrite rules are SaaS-controlled and may have changed, so verify against the current GitBook Git Sync documentation for your plan.

What is confirmed vs. assumed

Well-established: GitBook syncs periodically, not per keystroke. Changes saved in the editor are pushed back to the repository, and remote commits are pulled into the space. Because of this, "simultaneous" edits are actually reconciled at sync time, and the window for a conflict is the gap between an editor edit being saved and the next pull of a conflicting remote commit.

Likely, but verify: On a conflicting pull, the remote Git side is treated as the source of truth for file content. GitBook keeps its own per-space revision history, which acts as a recovery safety net if editor work is overwritten — but that history is a fallback, not a conflict-resolution mechanism.

The .content / metadata question

GitBook stores content in the repository as Markdown plus GitBook-managed structural files — historically SUMMARY.md for navigation and a .gitbook configuration directory. These files are GitBook's projection of its internal state. If a remote push modifies them directly (renaming pages, restructuring the summary) while the editor holds a different structure, the sync may not reconcile the two cleanly, and you can end up with structural drift between the repository and the editor. The practical rule: do not hand-edit GitBook-managed metadata files on the Git side unless you are prepared to let the next sync overwrite editor-side structure.

Preventing data loss

There is no lock or optimistic-concurrency guard that blocks a forced overwrite. The reliable mitigations are procedural:

1. Route editor-side work through GitBook change requests and merge them before expecting conflicting remote commits to land.
2. Route repo-side work through pull requests, and merge one side before editing the same page on the other.
3. Never leave high-value edits sitting as unpublished drafts in the editor while commits are being pushed to the same files — that is the most vulnerable state.
4. If an overwrite happens, check the space's revision/activity history to recover the lost editor-side content.

Verify it yourself

Because this behavior is SaaS-controlled, run a five-minute experiment before relying on any assumption: create a test space linked to a scratch GitHub repo, edit a page in the GitBook editor without publishing, push a conflicting change to the same file on GitHub, and observe whether the editor change is kept, overwritten, or flagged. Then check the space's revision history to confirm recoverability. If the result differs from what this answer describes, the current behavior wins — and the one diagnostic detail that would change this recommendation is which GitBook plan and sync configuration you are on, since safeguards can differ.