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
Helpful tip
Think of a workspace as a sandbox - when you want to try something new, create a new workspace (on a new branch) in which to experiment.
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).
Note that you can work in a workspace, but you can only view a version.
The initial history of a document
Helpful tips
- Selections in the Versions and history panel are highlighted in blue.
- Hovering over an entry in the panel highlights it in light blue.
- Click > Show changes to expand the list of all changes made in that workspaces or version
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
Helpful tips
- Each document can contain many branches, one workspace for each branch, many versions, and many releases.
- Changes are identified by lighter text and a dashed line in the graph with a small solid dot for each change.
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:
- Click in the Document panel to open the Versions and history.
- 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:
If the user is an Onshape employee, an Onshape logo icon is displayed to the left of the User's name under the Modified column in the graph:
Create a version
Helpful tip
To create a version from a workspace, with the workspace and the Version and history panel open:
Click and fill out the dialog.
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.
- With the Versions and history open in the Document panel, right-click on the change entry from which you want to create a version.
- Right-click on the change row and select Create version here...
- Enter information for the version.
- 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 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.
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.
- With the Versions and history open in the Document panel, click .
- Select any two entries: a workspace, version, or any specific history entry within a workspace or a version.
- 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 panel.
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.
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).