Versions and History

You can create a version from the Document panel; click to create a new version without leaving the workspace.

You can also create a version through Versions and history, also located on the Document panel:

1. With a document open, click to open Versions and history.
2. Click the workspace from which to create a version; this makes that workspace active.
3. Click the Create version icon .
4. In the dialog that appears, enter a name and description for the new version.
5. If any drawings in the document have updates pending, as indicated by a bright yellow Update icon , a message is included in the dialog:

   

   Click the icon in the message to update all drawings that are listed so the version will contain the most recent version of the drawings. Note that if you click the Update icon and then cancel the dialog, the drawings are still updated.

6. Click either:
   1. Create - Creates the new version and remain in the currently active workspace
   2. Create version and edit properties - Creates the new version and also open the Properties dialog for the new version. This Properties dialog includes names and descriptions for each tab and part of the new version.

The new version is shown in the Versions and history graph:

Onshape may also create a version automatically when updating document references. In that case, you will see an automatic version icon in the graph, as shown below:

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:

For more information about automatic versioning, see Updating References.

To create a branch of a document:

1. With a document open, click to open Versions and history.
2. Right-click on the version entry from which to create a branch to access the context menu.
3. Select Branch to create workspace:

   

4. In the Properties dialog that appears, enter the name and description for the branch:

   

5. Click either:
   1. Create - Creates the branch and optionally open the new workspace (check box)
   2. Create version and edit properties - Creates the branch (optionally open it) and also open the Properties dialog for the new workspace. This Properties dialog includes names and descriptions for each tab and part of the new document workspace.

You can compare two workspaces, two versions, or a version and a workspace. You are also able to merge one or more branches.

To delete a document workspace:

1. With a document open, click to open Versions and history.
2. Right-click on the branch to delete.
3. Select Delete.

   

4. Click Delete to confirm.

   

To restore a deleted workspace:

1. Open the document with the deleted workspace.
2. Expand the Document menu :

   

3. Select Restore deleted workspaces.
4. In the dialog, select the branch(es) you want to restore.
   
5. Click Restore selected.

A team is working on a bicycle and has reached a stable design base for the frame. Now it's time for the team to experiment with various component designs. Begin by marking the basic frame design document as a version.

1. Click the Versions and history icon to open Versions and history in the Document panel:

   

2. Click the Create Version icon .
3. Name the first version Base Frame; click Create:

   

   

   Each designer is then able to create their own workspace from the Base Frame version, perhaps labeled Seat, Brakes, Shocks.

4. Right-click the Base Frame version, then click Branch to create workspace:

   

5. Name the new workspace, Seat; click Create:

   

   The Base Frame version still exists as well as the original workspace (Main). In addition, there is a second workspace, Seat, so the designer making changes for the seat won't affect the Base Frame workspace.

6. The Shocks and Brakes designers each create their own workspaces, from the same Base Frame version:

   
   The workspace of each designer is, at this point, identical to the Base Frame version.

7. As they continue to design in their own branches, their designs evolve, independently of the Base Frame version and independently of each other. As they work, they are free to create versions of the workspaces.

   When the independent work is complete, each branch is merged back into the Main workspace, bringing all the independent work together.

   

Legend

A typical Version and history graph contains icons that indicate the type of workspace, branch, version, or revision each node is. To more fully understand how to read the graph, consider this table:

Icon	Indication
	version
	change node
	A version containing a release that has been approved.
	A version containing a release containing an obsoleted item.
	A workspace.
	A version with a revision pending.
	A version in the Version and history that was created automatically by Onshape; for example, when using the Update to latest option as explained later in this topic

Terms

• Version - A named and saved state of the document. Versions are immutable and separate from workspaces. Create a version to capture a workspace at a particular point in time. You can open and branch a version.

  Indicated by normal text and a solid dot on the version graph.

• Workspace - A modeling/design space.

  The active workspace is indicated by a blue box to the left of it in the version graph list, and an open dot at the end of the associated branch.

• Branch - Where the document is split and a new workspace is created. A branch can have zero or more versions, and up to one workspace. You can open and delete a branch.

  Indicated by bold and italic text and a dot on the version graph. If the dot is open, the branch has one associated workspace. If the dot is closed, the workspace associated with that branch has been deleted.

Merge lines

All merges are displayed explicitly in the Versions and history graph, which updates automatically as changes are made to the document.

Showing and hiding merge lines

To make the Versions and history graph easier to visualize, toggle the Show/Hide merges and Show/Hide automatic versions buttons as needed:

A Versions and history graph with merge lines and automatic versions shown (above).

A Versions and history graph with merges hidden (above).

A Versions and history graph with automatic versions hidden (above).

Merge lines example

The example below shows a complex Versions and history graph with several branches. Each branch was created from the Main workspace, and then individual work was done on each branch. As work on each branch was completed, the branches were merged back into Main. The flow of lines to and from the Main branch shows the merging workflow, making it easy to see which changes were merged when.

To automatically scroll to the top or bottom of a branch, right-click on a branch to access the context menu and select either the Scroll to branch top or Scroll to branch bottom option.

If a Document version contains a published custom feature, the bracket indicator ({}) is displayed around the Version node in the Versions and history graph:

See Publish a custom feature for more information.

Search history allows you to search history entries across all versions and branches. The result is a filtered list of entries based on your search term. Version names and version descriptions are not included in the search.

To search history:

1. Enter a search term in the Search history field. All history entries including the search term are displayed in the Versions and history list:

   

When searching, results are presented from all branches, even if you have selected Active branch above the search field.

2. Optionally, to further narrow your search, click the dropdown arrow in the search history field. This allows you to filter the search using the following criteria:

   

• Tab - Narrow the search by selecting a specific document tab. Default is Any tab.

• Tab types - Narrow the search by selecting either Part Studio, Assembly, or Drawing. Default search uses all tab types. Click the Clear button to reset the tab type filter. Both tab types are included in the search.

• Modified by - Narrow the search by selecting the person who made the history change. Options are Only me, Not me, or Any (default).

• Date modified - Narrow the search by selecting the Start and End dates. Default searches all dates.

3. Once the criteria are selected, click the Search button. The search term is filtered according to the new criteria. At any point, you can click the Reset button to set all filter criteria to their default values.

The Filter branches button changes which branches are displayed in your version graph.

To filter branches:

1. Open the Versions and history panel.
2. Click the Filter branches button.
3. Select a filter option:
   • Show all branches - Display all branches in the Version graph. Default view.

     

   • Show all branches with workspaces - Hide all branches that belong to deleted workspaces. In the image below, you'll see that the bottom green branch (in the image above) has been hidden. This option can be used to clean up large version graphs.

     

   • Show current branch - Display only the current branch.

     

   • Show current branch with parent branches - Display only the current branch and its parent branches.

     

You can open the Versions and history panel from the Documents page or from within the document:

• From the Documents page - Select the Information panel icon that corresponds with the document for which you want to open the Versions and history panel, then tap Versions.
• From within the document - Tap the Versions and history icon

• The Versions and history panel displays the default version graph for a document,
• A Main workspace and a Start version exist by default.
• Tap to switch between viewing All branches and the Active branch (workspace that is active, or open, in the graphics area).
• Tap Create version to create a version.
• Tap the X to close the Versions and history panel.

The graph displays all versions and workspaces of a document, in tree form. The graph is color-coded by branch. Each branch is one color, and every branch ends with a workspace, which are depicted as open dots. Branch names are shown with bold and italic text. Versions are depicted as solid dots, and normal text, and are View-only.

The active branch, which is the currently open workspace, is indicated by a blue highlight. In the image above, branch B1 is the active branch.

• Version - A named and saved state of the document. Versions are immutable and separate from workspaces. Create a version to capture a workspace at a particular point in time. You can open and branch a version.

  Indicated by normal text and a solid dot on the version graph.

• Workspace - A modeling/design space.

  The active workspace is indicated by a blue box to the left of it in the version graph list, and an open dot at the end of the associated branch.

• Branch - Where the document is split and a new workspace is created. A branch can have zero or more versions, and up to one workspace. You can open and delete a branch.

  Indicated by bold and italic text and a dot on the version graph. If the dot is open, the branch has one associated workspace. If the dot is closed, the workspace associated with that branch has been deleted.

To create a version of a document:

1. Open the Versions and history panel .
2. Tap the workspace or branch from which to create a version to select it.

A workspace (branch) is indicated by an open dot.

3. Tap .
4. Add a name and description for the version, then select Create version.

   

5. The newly created version appears in the Versions and history panel.
   

To create a branch of a document:

1. Open the Versions and history panel .
2. Tap the three-dot menu icon next to the version you want to branch from, then tap Branch to create workspace.

   

3. Add a name and description for the branch, and then select Create workspace.
4. The newly created branch appears in the Versions and history panel.
   

Onshape keeps a history of all the changes made to every document by every user. This enables you to view those changes in one list in the document history, and also to restore a document to a specific point in history at any time.

When restoring, the workspace you are in is the one being restored. If you wish to restore to another workspace, open that workspace first.

To restore a version to the currently active workspace:

1. Open the Versions and history panel .
2. Tap the version you wish to restore to.
3. Tap the three-dot menu icon next to the version you want to restore, then tap Restore to [Target].

   

For more information about restoring versions, see Document Management.

You can open the Versions and history panel from the Documents page or from within the document:

• From the Documents page:

  Select the Information panel icon that corresponds with the document for which you want to open the Versions and history panel. From here tap Versions.

• From within the document:

  Tap the Versions icon in the upper left:

  

• The Versions and history panel displays the default version graph for a document, notice there is a Main workspace, and a "Start" version by default.
• There are two icons in the upper right of the Versions and history panel:

- Create a version

- Close Versions and history panel

• Tap to switch between viewing All branches and the Active branch (workspace that is active, or open, in the graphics area):

The graph displays all versions and workspaces of a document, in tree form. The graph is color-coded by branch. Each branch is one color, and branch names are shown with bold and italic text. The workspace associated with a branch is displayed as an open dot. Versions are depicted as solid dots, and normal text, and are View only.

The active branch, which is the currently open workspace, is indicated by a blue box around the title. In the image above, the branch titled b2 is the active branch as is indicated by the blue box around it and to its left.

• Version - A named and saved state of the document. Versions are immutable and separate from workspaces. Create a version to capture a workspace at a particular point in time. You can open and branch a version.

  Indicated by normal text and a solid dot on the version graph.

• Workspace - A modeling/design space.

  The active workspace is indicated by a blue box to the left of it in the version graph list, and an open dot at the end of the associated branch.

• Branch - Where the document is split and a new workspace is created. A branch can have zero or more versions, and up to one workspace. You can open and delete a branch.

  Indicated by bold and italic text and a dot on the version graph. If the dot is open, the branch has one associated workspace. If the dot is closed, the workspace associated with that branch has been deleted.

To create a version of a document:

1. Access the Versions and history panel.
2. Open the workspace (or branch) from which to create a version.

A workspace (branch) is indicated by an open dot.

To do this, tap to select desired workspace, then tap the Open icon.

3. Tap .

4. Add a name and description for the version, then select Create.
5. The newly created version appears in the Versions and history panel:

   Tap on a version to see details and options such as Open and Branch.

   

To create a branch of a document:

1. Access the Versions and history panel.
2. Tap to select the version from which to create a branch:

   

3. Tap the Branch icon:

   

4. Add a name and description for the branch, and then select Create.
5. The newly created branch appears in the Versions and history panel.

   Note that both b2 and Main are branches and are indicated as such by the bold and italic text as well as the open dots in the version graph.

   Also note that "v1" and "Start" are saved versions and are indicated by the normal text and the solid dots in the version graph.

   The branch titled Main has two versions, "v1" and "Start", as is indicated by the blue color of the line. Branch titled b2 does not yet have any saved versions, it is the only item on the yellow line.

Onshape keeps a history of all the changes made to every document by every user. This enables you to view those changes in one list in the document history, and also to restore a document to a specific point in history at any time.

When restoring, the workspace you are in is the one being restored. If you wish to restore to another workspace, open that workspace first.

To restore a version to the currently active workspace:

1. Open the Versions panel.
2. Tap the version you wish to restore.
3. Tap the restore icon at the top of the panel.

For more information about restoring versions, see Document Management.