20th April 2026
Revising the Revisions
Working on the basic text editing functionality in Orsn, I found that before I could work on text block features (tables, etc.) I had to update something more fundamental: the Revisions system for keeping track of changes to Cards and Pages.
Part of the philosophy of Orsn as a tool for documenting research is to allow the writer to 'share their workings' if they so desire, in the spirit of open scholarship and transparency; viewing the history and evolution of a document might allow readers to make a more informed judgement of the researcher's process and assumptions.
Of course there is no requirement in Orsn to publish work or share revision drafts, and having access to revision snapshots is also extremely practical for writing of any kind – it allows for freedom in exploring one path in depth, knowing that it is always possible to retrace one's steps if one arrives at a dead end. Sometimes it's necessary to go back and take a different fork in the road.
This is a wonderful feature of branching in git. I have often thought about how this workflow might be translated into non-programming scenarios. That was a fundamental reason why I chose to use Markdown as the text format for Orsn. Plain text allows for this kind of tracking.
Version control and publishing
My conception for Revisions in Orsn is closely tied to git. While Orsn stores its data in a database, rather than flat text files, it will be possible to serialise its data (export them) to a series of Markdown files which will be exportable as a git repository. Conversely, it will also be possible to import Projects from git repos and deserialise them (import them) for viewing and further editing.
In this scenario, the Revisions in Orsn function as git commits, or snapshots, so that key changes can be documented, but without the learning curve and the tooling required for working with git. When a Project is exported and published as a git repository, it becomes available in that format for anyone familiar with version control and its more sophisticated options; and it can become a site for collaboration, if that's useful.
So, in short, every Revision in Orsn becomes a git commit in the exported git repository. (For the moment there is no equivalent of branches in Orsn. This may arrive at some point in future. We walk, or at least toddle, before we can run.)
Out with the old
In Orsn v1, the revision system stored changes as a series of patches: that is, it only stored the parts of a text document which had changed since last time. That is a space-spacing approach, but it introduces a long chain of dependencies.
Picture this: a document is revised 5 times. The original document is stored in full, along with the text changes made in each subsequent revision. To view the document at, say, revision 4, we have to load the original document, apply the patch changes of revision 1, then to the resultant updated document, apply the patch changes of revision 2. And so on. Until we get to the desired revision, number 4.
You can imagine that in a long chain of revisions, this introduces a lot of vulnerability to errors. If there is an issue in applying just one of the patches, the rest in the chain will fail, and it won't be possible to construct the document.
In the new v2 revision system, I have accepted the compromise of slightly greater storage requirements in exchange for greater reliability (plain text doesn't use up too much space, so this is reasonable). In the new system, a full snapshot of a given change is captured, making its restoration much more robust. It's still possible to calculate and show the differences between a revision and its predecessor, and I have included that option. With the new snapshots, changes to title and tags are also captured, and we have flexibility to track other properties if they are introduced. This new setup feels much more solid and dependable than the 'cumulative patch' system of Orsn v1.
Contact
Find me on the fediverse (Mastodon) @Lemmy@post.lurk.org, or send an email to: info [at] orsn.io