Version: 2020.1
Plastic SCM Integration
Using external version control systems with Unity

Plastic SCM plugin for Unity (beta)

Plastic SCM provides version controlA system for managing file changes. You can use Unity in conjunction with most common version control tools, including Perforce, Git, Mercurial and PlasticSCM. More info
See in Glossary
functionality for teams to collaborate on Unity projects.

The Plastic SCM plugin for Unity (beta) provides source control functionality from within the Unity Editor. The Plastic SCM window in the Unity Editor displays a list of new or changed files in your local project. From here you can check these files into Plastic SCM.

Any files you update in Unity are automatically checked out. This prevents other users from updating them until you check them back in.

The Plastic SCM plugin for Unity (beta) is supported for Unity 2018.4 LTS and above for macOS and Windows. Note: The plugin is not currently supported for Unity 2020.1 and above on Windows. Unity will add support for these versions in a future version of the plugin.

Getting started with Plastic SCM

Installing the Plastic SCM plugin for Unity

The Plastic SCM plugin for Unity is available on the Asset StoreA growing library of free and commercial assets created by Unity and members of the community. Offers a wide variety of assets, from textures, models and animations to whole project examples, tutorials and Editor extensions. More info
See in Glossary
. To install the Plastic SCM plugin:

  1. Select Assets > Import Package > Custom Package…
  2. Select the PlasticSCMForUnity package.
  3. In the Import Unity Package window:
    1. Select All.
    2. Select Import.

The Plastic SCM plugin is now enabled on your project. To access the Plastic SCM window in the Unity Editor, select Window > Plastic SCM.

Creating a new workspace

To use the Plastic SCM plugin on a Unity project, you must create a workspace for the project in the Plastic SCM window or in the Plastic SCM GUI.

To create a new workspace for your project in the Unity Editor: 1. Select Window > Plastic SCM. 2. Specify the repository name, workspace name and path to the project. By default, the existing project path and name are used. 3. Choose whether you want to use Plastic SCM as a developer (for full Plastic SCM functionality) or an artist (for a simplified workflow).

Once you’ve created your workspace, the Plastic SCM window displays your project files. Additionally, Plastic SCM automatically creates an ignore fileA special file used in many Version Control Systems which specifies files to be excluded from being placed under version control. In Unity projects there are a number of files which could be excluded from version control, and using an Ignore File is the best way to achieve this. More info
See in Glossary
in the workspace, that is, your project folder.

Committing your project files to source control

Once you’ve connected your project to a Plastic SCM workspace, the Pending Changes tab of the Plastic SCM window displays all your existing project files as Added and private. To include these files in the workspace, you must check them in.

Once you have checked in your files, the Pending changes tab refreshes and no longer lists the files you have checked in. Additionally, the Plastic SCM GUI now displays:

  • Your project files in the Workspace Explorer
  • Your latest check-in in the Changesets view

Using the Plastic SCM plugin

The Plastic SCM plugin enables the Plastic SCM window in the Unity Editor. Use the Plastic SCM window to manage your file changes, including:

  • Link your project to source control
  • Check-in files
  • Undo changes
  • Compare file revisions

The Plastic SCM window displays a list of new and changed files in your project. When you add a new file, or save changes to an existing file, the Plastic SCM window automatically displays the affected files.

To open the Plastic SCM window, select Window > Plastic SCM.

Checking in files

To check in files:

  1. Select Window > Plastic SCM.
  2. In the Plastic SCM window, select the files you want to check in.
  3. In the text field, enter a comment to explain your changes.
  4. Select Checkin.

Your changes are listed in the Plastic SCM GUI, in the Changesets view.

Ignoring files

When you create a workspace using the Plastic SCM plugin, it automatically creates an ignore file in your workspace. This contains a default list of file types and paths to exclude from source control. If there are other files in your project that you want to exclude from the shared repository, add them to the ignore file:

  1. In the Plastic SCM window, right-click the file you want to ignore.
  2. Select Add to ignored list.
  3. Select the file name.

The files you choose to ignore are removed from the Pending changes list. You can ignore specific file names, whole folders, and all files with a specific extension.

Learn more about ignore files.

Viewing file changes

To compare an updated file with the previous version, right-click the file in the Plastic SCM window and select Diff. This opens the Differences view, which compares the repository source with your local copy. This is a text-only view.

Reverting file changes

If you’ve made changes in your project that you don’t want to keep, you can revert back to the previous version, that is, the latest checked-in version. To revert changes to a file, select the file in the Pending changes tab and select Undo changes.

Migrating to Plastic SCM

Plastic SCM provides a migration wizard to help you migrate projects from Collaborate to Plastic SCM. To migrate a project to Plastic SCM:

  1. Go to the migration wizard.
  2. Enter your Unity ID login details.
    1. Select Log in.
  3. Create a Plastic SCM organization.
    1. Select a region in the region dropdown.
    2. Select Next.
  4. Choose the projects to migrate.
    1. Select Next.
  5. Select the team members from your organization to join Plastic SCM.
    1. Select Next.
  6. Select Confirm.

Once you’ve completed the steps in the migration wizard, Plastic SCM migrates your projects from Collaborate to Plastic SCM. Plastic SCM also sends email invitations to the invited team members to get started with Plastic SCM.

Plastic SCM window

Use the Plastic SCM window in the Unity Editor to manage version control for your project. If your project is not already connected to Plastic SCM, the Plastic SCM window displays a view to create a new workspace. The table below describes the fields of this view.

Field Description
Repository name Name of the repository. By default, this is the name of your project.
Workspace name Name of the workspace. By default, this is the name of your project.
Path on disk The path to your project. By default, this is the location of your open project.
Developer radio button Select this option for full Plastic SCM functionality, including merging and pushing and pulling branches.
Artist radio button Select this option for a simpler workflow of checking in files, without merges or multiple branches.
Create workspace button Create a workspace for your project with the details you’ve provided.

The table below describes the Plastic SCM window in the Unity Editor.

Field Description
Branch Displays the branch of the workspace you’re currently working on.
Pending changes tab Displays a list of changed files in your project.
Incoming changes tab Displays external changes in the workspace that your local version of the project does not yet have.
Launch branch explorer (Developer mode only) Click to open the branch explorer.
Launch Plastic (Developer mode only) Click to open Plastic SCM.
Configure Gluon (Artist mode only) Click to open Plastic Gluon in configuration mode.
Launch Gluon (Artist mode only) Click to open Plastic Gluon.

Pending changes tab

The Pending changes tab displays new and changed files in your local version of the project. Use this tab to check in your files to the Plastic workspace, exclude files from version control and compare changed files with the previously checked-in version.

Field Description
Checkin changes Commit the selected files to the workspace. You must enter a comment in the text box before you can check in your changes.
Undo changes Undo local changes made to the selected files.
Keep items locked (Artist mode only) Keeps the items locked after the check-in operation. This is useful, for example, if you want to make multiple changes to a file but check them in separately as individual changes. To unlock the items, deselect this button.
Options Click to open the Options window.
Item The name and path of the file. Files are grouped by the type of change, for example:
Changed
Deleted
Added
Status The status of the file, for example:
Changed
Removed locally
Private
Size The size of the file.
Extension The file extension.
Type The file type.
Date modified Date and time of the change.
Repository The repository where the change was made, that is, the local repository or remote repository if another user has made the change.

Learn more about the Pending changes view.

Incoming changes tab

The Incoming changes tab displays external changes in the workspace that your local version of the project does not yet have. Use this tab to get the latest changes from the remote workspace.

Field Description
Update workspace Updates your project with external changes from the workspace.
Path The file path and name.
Last edited by (Artist mode only) The user who checked in the change.
Size The size of the file.
Date modified (Artist mode only) The date of the file’s most recent check in.
Author (Developer mode only) The user who checked in the change.
Details (Developer mode only) Describes what the update operation will do with the related change.
Resolution method (Developer mode only) Shows the resolution method the user selected when solving the directory conflicts.

Learn more about the Incoming Changes feature.

Options window

Use the Options window to control the behavior of the Plastic SCM window. The table below describes the options for the Plastic SCM window.

Field Description
What to find tab
Show checkouts Shows files that:
You have explicitly checked out in Plastic
You have moved
Have a merge in progress
Find changed files in the workspace Checks the workspace directory structure to identify changed files via the timestamp.
Check the content to determine files as changed, not just timestamp Calculates the hash of files with updated timestamps to ensure the file content has actually changed.
What to show tab
Auto-refresh Plastic automatically refreshes the Pending Changes list as needed to avoid manual refreshing.
Show private files Show files that are not committed to source control, such as new files or tool-generated content.
Show ignored files Show files that you’ve added to the ignored list.
Show hidden files Show files that you’ve added to the hidden list.
Show deleted files and directories Show files that you’ve deleted manually in the workspace outside of Plastic control.
Move detection tab
Find moved and renamed files and directories Searches the workspace for possible renamed or moved files, for example if one file has been deleted and another file has been added.
Match binary files only when they have the same extension Restricts file matching for binary files to files with the same extension.
Match text files only when they have the same extension Restricts file matching for text files to files with the same extension.
Similarity percentage Defines how similar files need to be to be considered as moved or renamed.
For text files, this percentage relates to the content.
For binary files, this percentage relates to the file size.
For directory structures, this relates to children as a percentage of the total number of directory entries.

Learn more about the Options window.

Plastic SCM Integration
Using external version control systems with Unity