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.
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.
- Selections in the Versions and history flyout are highlighted in blue.
- Hovering over an entry in the flyout 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:
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.
- 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.
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:
To create a version from a workspace, with the workspace and the Version and history flyout 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 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.
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:
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 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).