Version control

Is there any guidance/docs regarding how to do version control with the models?
How do you create a new branch (I presume “cake output” is a new branch in the screenshot)?
How do you merge branches?
How do you ensure that the new commits retain information from your previous commits, or do you have to “fetch” first?
How do you checkout an older commit?

Is there any guidance as to how best use the version control system on speckle I can share with new collaborators/users? Thanks!

1 Like

Hey, @KatherineC, those are good questions. In part, if you have been following Speckle for a while, this could cause some confusion.

The launch of the new web application also involved a lot of renaming, which we have gone through. A lot of our documentation has been updated, but alas, none of the older tutorials have.

The older branch and commit language were largely rejected by AEC professionals as unfamiliar and also rejected by those familiar with git-like software actions as false. There is no true merge or forking here with Speckle in normal operations in host applications like Revit, Rhino, and Microstation, say.

What used to be branches are now referred to as models. To create a new model, click the blue New+ button. This is an empty path for new data to be published. You can also create new models from our connectors.

As your screenshot demonstrates, model names can be made to make nested models effectively.
i.e. Option 1/Architecture and Option 1/Structure are two models, and they will appear to be nested together such:


All native data published to these model branches using Speckle connectors will be a new version (formerly known as commits) of that model.

Your screenshot shows 5 versions of the dance_studio_centrelines model. All models will behave like this.

As models are different to branches, versions are different to git-like commits.

If a selection of objects in AutoCAD, say, is published to a model, this will be a version. Subsequently, the same selection of objects is published again, but only three of them have changed. Speckle stores the changed objects as new database entities, and the version holds a reference to those unchanged objects. This allows versions to be compared or ‘diffed’.

If a subsequent selection from the AutoCAD file is published to the model address, these will all be new entities in the DB, and the version will show the total difference. This is a great flexibility but also a point of confusion compared to git version control.

Where Speckle is used collaboratively, the equivalent to Fetch can come into play, as all the new data from user A will be wanted to be received by user B. Should user B then make changes to this, they will publish a new version of a model, and this can be received by A—and so on.

However, all contributors must understand how to control what data is stored in each model. A close equivalent of knowing what each of a project’s files contain.

User C can receive any model version into their host application via the Speckle connectors. It is also possible to view the data of any version of any model within the web app. Indeed, you can view 2 versions overlaid with the indicative changes between them.

We don’t offer branch merging, but we allow model federating. The “View All” button automatically opens a 3D viewer with the Architecture and Structure models shown together.

It is possible using our code SDKS (C# and Python) to merge models effectively: Federating Speckle Models - #6 by jonathon

But again, this is different to the classic git-like merge.

Essentially, Speckle version control handles changed/unchanged elements on every publish, keeping an immutable record of all objects ever published and a total audit trail of every version. The git-like description of version control served Speckle as a familiar concept but did not do well under scrutiny, hence the renaming efforts.

  1. For updated terminology and concepts: Speckle User Concepts Guide.
  2. For understanding the rationale behind the renaming efforts: The Great Rename Blog Post.