Skip to content

Version history

Save a version of a shared text, keep editing, then look at the document as it was - or bring it back. A version is a BcrdtSnapshot: a few dozen bytes that name a point in the document's history, rather than a copy of the document.

Two replicas, one history

Type into either replica and press Save a version. The version is stored in the document itself, so it reaches the other replica like any edit, and either replica can open it. Preview rebuilds the text as it was when the version was saved; Restore makes the current text say that again. The footer compares the size of the whole document with the size of a version.

Opening two replicas…

The thing worth trying. Type a sentence into A and save a version. Delete half of it and type something else, then preview the version: the old sentence is back, rebuilt from the document's own history. Now take B offline, type into A and save another version: B does not list it until it reconnects, and then it receives the version together with everything the version names. Finally restore the first version in A while B is offline, type into B meanwhile, and reconnect: the restore merges with B's typing instead of wiping it, because a restore is an edit, not a rewind.

A version is a name, not a copy

A BcrdtSnapshot holds two things: the state vector - which content existed at that moment - and the delete set - which of it had been deleted. That is all it takes to say exactly what the document looked like, so a version costs a few dozen bytes whatever the document's size, and a hundred versions cost a hundred small records rather than a hundred documents.

The price is paid by the document: rebuilding an old version needs every character that has been deleted since, so a document whose history will be restored keeps its deleted content instead of reclaiming it. The replicas on this page are created with GarbageCollect = false for that reason. Restoring from a document that collects is refused with an exception rather than answered wrongly.

// Kept for history: BcrdtCollaborationOptions.GarbageCollect, or BcrdtDocumentOptions.GarbageCollect.
var options = new BcrdtCollaborationOptions { GarbageCollect = false };

BcrdtSnapshot version = BcrdtSnapshot.Capture(document.Crdt);
byte[] stored = version.Encode();                               // a few dozen bytes, to keep anywhere

using BcrdtDocument then = BcrdtSnapshot.RestoreDocument(document.Crdt, BcrdtSnapshot.Decode(stored));
string text = then.GetText("body").ToString();               // the document as it was, as a new document

Where versions live, and what restoring does

This page keeps its versions in the document - an array of maps, each with who saved it, when, and the encoded snapshot as a byte[] - so they synchronize, merge and persist like the text does. Two replicas saving a version at the same moment simply add two entries. An application could equally keep them in a database next to the document.

A replica can only rebuild a version once it holds everything the version names. Kept in the document, a version arrives after the content it names - a replica's changes reach others in the order it made them - so a replica that lists a version can always open it. Versions kept anywhere else need the check, which is one call: document.Crdt.GetStateVector().IsSupersetOf(version.StateVector).

Restore does not roll anybody back. It works out the smallest edit that turns the current text into the old one (BcrdtTextSynchronizer.Apply) and makes it, as this replica. That edit synchronizes like a keystroke, merges with whatever others are typing meanwhile, and becomes part of the history itself - so the version before the restore can be restored in turn.

BcrdtTextSynchronizer.Apply(document.Text("body"), text);   // an ordinary edit, not a rewind
An unhandled error has occurred. Reload 🗙