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 Versions and history icon (outlined in blue, below) in the Document panel to display a graphical representation of the document history:

Version and history icon on the toolbar

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

Versions and history panel

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 icon Create a release candidate - Available only for Professional and Enterprise accounts; discussed in another lesson.

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

Compare history entries icon 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 Version menu icon 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.

    Version changes in the versions and history panel

    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:

history change 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:

New version node

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.

View the version at a specific point in time

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 to the right 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.

Restore and Return to main along the toolbar


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 Compare icon icon in the top right corner.

  1. With the Versions and history open in the Document panel, click Compare icon.
  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:

Compare workspaces

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:

Selecting a feature from the features list

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 panel.

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>:

Rstore to main context menu option

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

Additional resources

For additional Learning center resources, follow the self-paced courses here: Document History and Versions (Onshape account required) and Using Compare (Onshape account required). You can also follow the technical briefing articles here: Understanding and Working with a Document’s Historical Data (Onshape account required) and Gitflow Version Management (Onshape account required).