Revisions

Bonsai saves your building model as an .ifc file, and because IFC is an open standard written out as plain text, the tools the rest of the world built for keeping the history of text files work on it. Bonsai has support for Git built in, so you drive it from inside the model rather than from a terminal. 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 own computer keeps. It is local: it sits on your machine, there is nothing to log in to, and it works the same on a laptop with no network.

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 isn’t 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, and 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 is what you will read a month later when you are trying to remember when a wall moved.

The Bonsai documentation covers setting Git up, 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. It is superb with source code and useless with a 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 rests on the step id alone - not on the object’s Name, and not on its GlobalId, which serve other purposes.

The comparison holds for as long as the file is edited in place. A fresh export from another program, or a file put through a conversion of units or schema, is in effect a new file, and the chain of comparisons stops there. A file that another program wrote wants one save and one commit of its own before you start work on it, so that Bonsai’s way of writing numbers isn’t mixed up with your edits.

Seeing it in the model rather than in a list

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, not by reading a wall of text.

The same works for what you haven’t committed yet, which is the more useful direction day to day: before you commit, you can see exactly which objects you have touched, 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.

Trying things is 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

Bonsai has no central model, which leaves a question: how do four architects in one practice work on one building without taking turns over it?

The answer is a second repository. A remote is another copy of the same repository, somewhere more than one of you can reach - on a server in the office, or on a hosting service, or on a colleague’s machine.

A handful of verbs cover nearly all of it. You fork a repository, taking a complete copy of somebody else’s so that it becomes yours to work in. You fetch from a remote, bringing what other people have committed into your own repository without disturbing what you are doing. You push to it, sending your own commits the other way. And you merge what you fetched into the branch you are on, which happens on your own machine like everything else. Bonsai supports them.

In practice most offices do the simplest version of it: everybody takes a copy of one shared repository, works on their own machine, and pushes to and fetches from that one. 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.

Nothing about this is exotic. 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 federation holds in reserve: not a read-only reference to somebody’s export, but the same file, editable at both ends, with a record of who changed what.

Merging does the part you would expect to be hard: where two people have changed different things, both changes are kept, and where they have both changed the same object you get a conflict, just as with branches. Branch off the main line and merge back into it, and the direction of travel stays simple.

The tool that does the merging, ifcmerge, 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 install 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; the rest is the same commands, pointed at a remote.

Last updated 8 October 2026.