Next: Working with branches

Working with Versions

The estimated time of completion is 8 minutes.

Onshape captures the state of every tab in a workspace every time an edit is completed. Every edit, by every user, across every session is captured so there is always a complete history of every action made in the document. In addition to keeping a history of actions taken in every document, Onshape provides a way for you to capture an immutable version of a document at any point in time as well.

This lesson covers how to preserve a particular state of a document at a particular point in time by creating a version, as well as what you can do with a version once it's created.

Onshape workspaces


Before discussing versions, it's important to understand what an Onshape workspace is. Basically, a workspace is where you do your work. Every Onshape document starts with a workspace called Main. Creating parts, assemblies and drawings is all done in a workspace.

The name of the workspace or version you currently have open is displayed in gray next to the document name in the document title bar. Since you can have many workspaces and versions per document, look there to see which workspace or version you are in at any point in time (below, outlined in blue).

Workspace name

Note that you can work in a workspace, but you can only view a version.

The initial history of a document




All documents start with a version named Start and a workspace named Main. The Start version is immutable (as are all versions). It is the starting point of every document.

Click the Versions and history icon (outlined in blue, below) in the Document panel to display a graphical representation of the document history:

Click the icon outlined in blue, above, to open the Versions and history in the Document panel, below

The key to the graph is below it (seen above); the second line of icons relate to release management tasks and objects

The icons in the top right of the panel are:

Create a release candidate - Available only for Professional and Enterprise accounts; discussed in another lesson.

Create a version - Create an immutable snapshot of the workspace at that particular point in time.

Compare history entries - Compare any two entries in the history graph.

Viewing the history of a document




The history of a document is a list of all actions taken on that document during all sessions and by all users. To see the history:

  1. Click in the Document panel to open the Versions and history.
  2. Click > Show changes to see a list of changes for a particular version, workspace or release.

    The history (list of changes) for the Main workspace: 6 changes, all made in Part Studio 1

Hover over a particular change entry to see by whom and when the change was made.

There are a number of actions you can take on any of the history moments (changes) in the expanded list; right-click over an entry to access the context menu:

Create a version




Create a version to indicate to the system that you want to preserve the workspace at a particular moment in time. Versions are immutable, meaning you can never change or edit a version in any way. You can create a new branch (and thereby a workspace) from a version.

  1. With the Versions and history open in the Document panel, right-click on the change entry from which you want to create a version.
  2. Right-click on the change row and select Create version here...
  3. Enter information for the version.
  4. Click Create.

Note that a new version node is added to the Versions and history graph:

The V1 (version) was created

The changes along the Main (blue) branch are indicated by blue tick marks along the Main branch once the version changes are expanded.


Select a history entry (click Show changes to see a list of history entries) to view the document at that point in time, or right-click on an entry and select View.

The name of the workspace (or version) you are viewing is always displayed next to the document name in the document toolbar. When viewing a version, directly below that is a link to Restore to the top of that workspace: to restore the state of the workspace back to that point in time. There is also a link to Return to the top of the workspace, which simply shifts the view to that of the workspace.

The change labeled "Myspresso-v4Asmb parts:: Change part appearance" is selected and visible in the document, in the "Main" workspace; to return to the end point of the workspace, select the workspace name in the history or click Return to Main at the top of the dialog.


If you are unsure of how your work in a document differs between workspaces, versions, or between a workspace and a version, you can compare them. Onshape allows you to compare two entities at a time: two versions, two workspaces, or one of each.

Initiate a comparison in the Versions and history in the Document panel, using the icon in the top right corner.

  1. With the Versions and history open in the Document panel, click .
  2. Select any two entries: a workspace, version, or any specific history entry within a workspace or a version.
  3. The first selection is highlighted in blue and when you click the second selection, the compare dialog opens:

The compare dialog is color-coded, changes made in one version are color-coded blue and changes made in the other version are color-coded red

Select a feature in the Features list on the left side to open another dialog listing the Features created or edited and the specifics of the feature:

The feature selected on the left is also highlighted in the model. Use the slider above the model to change the display emphasis towards one workspace or the other to visualize changes. Note the fields shown for the feature are view-only in the Compare flyout.

Restore to <workspace>

Restore is like an Undo action on a larger document and user scale. Since all actions, by all users, across all sessions are listed here, you can select a particular action to restore the workspace to. Right-click on any change point in the Versions and history in the Document panel and select Restore to <name>:

Rest assured that even a restore action can be 'undone' by restoring to the action taken just before the Restore action in the History.

Next: Working with branches


Was this article helpful?

Last Updated: May 06, 2021