Revisions

This page is not really about a feature. It is about what becomes available once the document is an ordinary file, which is the argument of The file is the document arriving at its most useful consequence.

Because an .ifc is text, the tools that the rest of the world built for keeping the history of text files work on your building model. Bonsai puts a panel over the most widely used of them, Git, but nothing conceptually new is being introduced. Your project is a file in a folder, and the folder can remember.

What a repository is, if you have never used one

A repository is a folder whose history your computer keeps.

You work normally, and you save normally. Every so often you tell it that the current state is worth keeping, and it records that state, with the date, your name, and a sentence from you saying what changed. It does this cheaply, keeping what differs from one state to the next rather than a fresh copy of the file each time, so a hundred revisions of a large model is not the disk-filling exercise you would expect.

What you get in return is that no past state is ever lost, and none of them are called Block-A-FINAL-v3-revised-CJ.ifc. There is one file with one name, and behind it a list of every state it has been in.

Saving and keeping are separate acts, and the separation is the point. You save constantly, as you always did. You commit when you have finished something - when a stair works, when a comment has been addressed, when the model is going out. The sentence you write becomes the thing you read a month later when you are trying to remember when a wall moved.

Git is a separate program, and you may need to install it, which the Bonsai documentation covers, along with the details this page is deliberately skipping.

Why the comparisons actually mean something

Anybody who has used version control before will be sceptical here, and rightly. Version control is superb with source code and useless with the sort of file that rewrites itself completely every time you save. A model that renumbered its contents on each save would produce a comparison saying “everything changed”, which is the same as saying nothing.

Bonsai keeps the step ids - the #123 line numbers - stable from one save to the next. So the comparison between two revisions is legible, and the mechanism is almost comically direct: Bonsai runs an ordinary textual comparison and reads the lines off it. A line starting +#456= is an object that appeared. One starting -#456= is an object that went. An id that turns up in both lists is an object that was changed, because it was rewritten in place.

That is the whole trick, and it is why persistent identity matters in practice rather than in principle. See The model is a graph of standard objects for the two identity mechanisms and which is which.

Seeing it in the model rather than in a list

The consequence is that a revision comparison is not a wall of text. Having worked out which objects changed, Bonsai colours them in the viewport, so “what happened between Tuesday and Friday” is a question you answer by looking at the building with the changes lit up.

The same works for what you have not committed yet, which is the more useful direction day to day - before you commit, you can see exactly which objects you have touched since the last time. That is a good habit, and it catches the thing you moved by accident.

You can also ask for the history of a single object: select a wall, and get the list of revisions in which that wall changed.

Branches, for trying things

A branch is a second line of history that starts from where you are now. You work on it, and either it becomes the project or you abandon it, and abandoning it costs nothing and leaves no trace.

This is the part that is genuinely hard to do with files. Exploring a different stair arrangement by saving option-B leaves you with two files that both keep going, drifting apart, and a decision about which is real that nobody makes explicitly. A branch is the same idea done properly: named, kept separate, switchable, and disposable.

When an option wins, you merge it back. Where the two lines have both changed the same object, there is a conflict, and Bonsai will select the conflicting object in the viewport so you can look at the thing being argued over rather than at a text file describing it.

Several people on one model

Other people’s models takes the central model away, and explains why the models of separate organisations stay separate. It leaves a question behind, and this is where it is answered: four architects in one practice, working on one building, with no central model to take turns over.

A fork is a branch in somebody else’s copy of the repository. They clone the project, work on their own machine, and their branches are their own. You add their repository as a remote, fetch what they have done into a branch of yours, and merge it when you want it. Or - the commoner arrangement and the simpler one - everybody pushes to and fetches from one shared repository that nobody works in directly. Either way, each person holds the whole project and the whole of its history, and nobody is locked out of a file because somebody else has it open.

It is worth being plain about how ordinary this is. Fork and merge is not an experimental corner of Bonsai, and it was not invented for building models. It is how most of the world’s software is written - by millions of people, every working day, on shared files that nobody takes turns over. It is the two-way sharing that Other people’s models holds in reserve: not a read-only reference to somebody’s export, but the same file, genuinely editable at both ends, with a record of who changed what. And it is available to you here for the same reason everything else in this guide is available to you, which is that the document is a file.

Merging does the part you would expect to be hard. Where two people have changed different things, both changes are kept; where they have both changed the same object, you get the conflict described above, on the object rather than in a text file. Branch off the main line and merge back into it, and the direction of travel stays simple.

The tool that does the merging ships with Bonsai, so there is nothing to install for it. Git itself is the one thing that may not already be on your machine, and on Windows Bonsai will go and fetch it for you.

None of this has to be the first thing you do. The machinery is the same whether one person is using it or six, so start on your own, where the worst that can happen is that you keep too many revisions of your own work. The rest is the same commands, pointed at somebody else’s repository.

Last updated 4 September 2026.