MS Visual Studio integration#

Unity Version Control System (UVCS) provides a comprehensive integration with Visual Studio 2010 and later versions. In the form of a Visual Studio Extensibility Package, this integration offers the user most of the functionality found in the UVCS GUI right inside Visual Studio.

This section will describe the functionality and commands of the Unity Version Control Package for Visual Studio. Basic knowledge of UVCS concepts and terminology is needed. Things like a workspace, checkout / checkin, branch or merge should be familiar to the reader. For more details, please refer to the Unity Version Control page.

Installing the Visual Studio Source Control Package#

The Visual Studio UVCS plug-in is installed as part of the full Plastic SCM installer or the "Client + Plugins Plastic SCM installer".

The component "Visual Studio Integration Package" has to be selected in the component selection screen of the installer. Note that Visual Studio needs to be installed for this component to be enabled.

Selecting Plastic SCM as the source control provider#

Once Plastic SCM has been installed and configured, the next step is to configure Visual Studio to use Plastic SCM as the source control provider. To do this, you need to go to:

Tools > Options > Source Control

There, select "Plastic SCM Source Control Package" as shown in the next figure, and click OK. The plug-in is ready to be used.

Note: If you selected "Plastic SCM SCC plug-in" during the installation, you will see this plug-in as well in the dropdown list. The SCC plug-in was designed for the old SCC version control interface that was standard in versions of Visual Studio prior to 2005. The "Plastic SCM Source Control Package" is a far more complete solution and is the recommended integration for Visual Studio 2005 and newer versions.

Adding the solution to UVCS#

Before using UVCS inside Visual Studio, the solution has to be added to UVCS. Adding the solution to UVCS binds them together and this binding is stored inside the solution and project files.

Note: the solution should be contained in a single UVCS workspace. If the projects inside the solution are located in more than one UVCS workspace, many operations of the plug-in will choose to act only on the workspace of the first project (for instance, displaying any view from the UVCS menu, or checking in pending changes right clicking on the solution will be applied only to the workspace of the first project).

 Adding a solution for the first time#

If no other developer has added the solution to UVCS already, it has to be added for the first time. This is done by right clicking on the solution in the Visual Studio's Solution Explorer and selecting Add to source control.

If the solution directory tree is not contained inside a workspace, the UVCS plug-in will show a dialog to create a new workspace. This dialog is the same used to create a new workspace in the UVCS GUI client. For more details, refer to the Unity Version Control GUI guide.

The new workspace configuration can be customized using the following commands:

Workspace name#

This is a name chosen by the user to identify the workspace. This name will appear in the UVCS GUI workspaces tab.

Path on disk#

This is the directory where the workspace will be created. By default, the plug-in will fill in this field with the top directory of the solution.

Default repository#

This is the repository where the solution will be added. The dropdown list contains all the repositories in the Plastic SCM server. When adding a new solution to Unity Version Control, you will normally want to create a new repository for it. This is done using the New button.

The New button will open a new dialog that lets you create a new repository to contain all the data of the solution you are adding to UVCS. This dialog is the same used to create a new repository in the UVCS GUI. Refer to the UVCS GUI guide for more details.

If the solution was already contained in a workspace, although it had not been added to UVCS yet, the new workspace dialog will not appear and the solution will be added automatically.

Once the workspace and optionally the repository have been created, the solution is added to the source control. All the items inside it are added to the repository and checked in. Being controlled items (as UVCS defines it) they are decorated with a lock icon.

Open an Existing Solution#

When the solution has already been added to UVCS by another user, you can directly open it from within Visual Studio. To do so, go to:

File > Open > Open from Plastic SCM...

This command lets you open a solution from one of the UVCS repositories. The sequence is this:

• Choose a workspace or create a new one. The source code will downloaded to this workspace from the repository.
  • If a new workspace is created, choose the repository it will be pointing to. Keep in mind that, by default, the workspace points to the latest changeset in the /main branch.
• Browse the repository directory structure and select a solution file.
  • The repository browser will use the same branch that the workspace is pointing to.
• Once a solution file is chosen, the workspace is updated to download the selected versions (if it was created in the first step).

 Binding a Solution already in UVCS#

If the files that make the solution are already in UVCS, but the solution and projects are not bound to UVCS, binding them is just a matter of adding the solution to source control. The solution and project files will be modified to include the binding information, so they are automatically checked out.

To complete the binding, you will need to checkin the changes. To do so, right click on the solution and select Checkin. The Pending changes view will appear, letting you enter a comment to checkin. This is the same Checkin dialog that appears when you select the Checkin command in the items in the UVCS GUI.

 Basic operations#

Once the solution is bound to UVCS, most of the changes in the solution are handled transparently by the integration. When a file is modified, it is automatically checked out. When a file is moved (even between projects), the change is detected as a moved item.

You can review all the pending changes by right clicking in the solution in the Solution Explorer and selecting Checkin. This will open the Pending changes window and let you check in the changes or undo some of them. The Pending changes view details the items whose content has changed as well as moved, added and deleted items. For more details on the Pending changes view, refer to the UVCS GUI guide.

Items Commands#

UVCS provides several commands when right clicking a file or folder in the Visual Studio Solution Explorer.

The following commands are added to the context menu by the Plastic SCM Source Control Package.

Checkout for edit#

Explicitly checkout the item so that UVCS knows that it is going to be edited. By default, the plug-in will automatically checkout the files that are modified inside Visual Studio. If an item is modified outside the IDE, however, you may want to check it out explicitly.

Update to Latest Version#

Update the selected item to the latest changes in the repository.

Diff with previous#

Open a Side-by-side Diff tool that compares the selected file with its previous version. If the item is checked out, the diff view shows the changes made.

Diff...#

Display a dialog in which you choose two revisions of the selected item and then open a Side-by-side Diff tool to compare those revisions. By default, one of the revisions is the item as it exists in your workspace.

Annotate#

Open an Annotate view for the selected item. The annotate view displays the contents of the file with annotations for each line detailing its author as well as the branch and changeset where the change was made.

History#

Open a History view of the selected item. This view details all the revisions created for the item, as well as any namespace change (i.e. if the file has been moved, renamed or deleted).

 History as 2D revision tree#

Open a Branch Explorer for the selected item showing the revisions and their types as described in the 2D revision tree.

 Change revision type#

Change the revision type of each selected item, to binary or text. The type of an item controls how it is handled by the Diff and Merge tools.

 Refresh status#

Reload the status (checked out / checked in / controlled / added) of the selected item and its children, updating the decorators. This command is useful when some items have been modified outside Visual Studio, to set the status up to date again in the IDE.

Permissions#

Open a new window to view or edit the permissions of the selected item.

Text File Commands#

Any open document in the code editor has an associated context menu. The UVCS plug-in adds some options to that menu, detailed below.

 Show semantic history#

Open a new window with a browser for the history of the specific method where the right click was made. This option works on C#, Java and Vb.net projects. Many times a developer looks at a piece of code and wonders how it ended up written like it is. In such cases, she can use the history and annotate view to find out how the method evolved. But in this process, she has to go find the method inside the file each time a new revision is compared.

With method history, the developer can focus on a specific method and browse the changes specific to it. The method history view can filter the revisions in which the analyzed method had changes, so the answer to the question "What happened to this method?" is quickly answered.

The method history view will download the different revisions of the item from the repository, and parse the code to find the requested method, so it is found even if it has been moved.

The view contains a top panel with a table displaying all the revisions of the file that contains the selected method. When a revision is selected in the top panel, the changes made to the method in that revision are shown in the bottom panel. This panel contains a Side-by-side diff tool as described in the UVCS GUI guide.

The revisions table on the top panel has one row for each revision of the file. It has the following columns:

• Change type: Show the change type of the revision. These can be some of the possible values: Unchanged, Added, Deleted, Changed, Moved from...to..., Moved down..., Moved up..., Renamed from...to...
• Contains element: Indicate whether or not the selected element is in the revisions showed.
• Changeset: The number of the changeset that contains the revision.
• Branch: The name of the branch that contains the revision.
• Comment: The comment of the revision.
• Owner: This is the author of the revision.
• Date: The timestamp when the revision was created

The top panel has several controls to filter the list of revisions upon the following criteria:

• Show only revisions that contain the element: Filter out those revisions where the element is not present.
• Show only revisions with changes: Filter out those revisions that don't have changes in the revision. Only revisions with "Change type" column different from "Unchanged" will be showed.
• Show full file differences / Show only element differences: Show in the bottom pane all the differences in the file. Or show only the differences involved in the selected method.

The Unity Version Control menu#

Toolbar#

The UVCS Toolbar shows the most common views available.

To enable this toolbar click on

View > Toolbars or Tools > Customize

and select "Plastic SCM".

By clicking on these buttons the corresponding view will appear the same way as clicking on the View > Plastic SCM menu (see picture below).

 Accessing Views#

Most of the work in Plastic SCM happens inside a "view". The most relevant views can be open right inside Visual Studio, through the View > Plastic SCM menu.

The views available under that menu behave in the same way as their counterparts in the UVCS GUI. Since they are fully described in the Plastic SCM GUI guide, that information will not be duplicated here. Please refer to the pointers given below for more details on each specific section.

Pending changes under Solution#

Open a Pending changes view with all the changes of the solution. This is mostly as the Checkin command available on the solution explorer. Both commands differ only in their extent: while this includes changes for the whole solution, the one in the solution explorer only affects the selected item and its children. If you want to see all the pending changes in the workspace instead of only those of items in the Visual Studio solution, check the Pending changes on workspace command described below.

Branches#

Open a Branches view with the branches of the repository loaded in the workspace. The view is fully functional and lets the user perform all the operations available to branches such as creating new child branches or switching the workspace to a specific branch.

Branch Explorer#

Open a Branch Explorer view for the repository loaded in the workspace. The view is fully functional letting the user perform all the operations available to branches, changesets and labels, like comparing changes or opening new filtered Branch Explorer views.

Labels#

Open a Labels view for the repository loaded in the workspace. Again, all the operations normally available for labels on the UVCS GUI are available here as well.

Changesets#

Open a Changesets view for the repository loaded in the workspace. This lists all the changeset of the last month by default. It operates as the same view in the UVCS GUI.

Repositories#

Open a Repositories view that contains the list of repositories in the default UVCS server and possibly repositories in other servers as defined by the server connection profiles (in Preferences, see below). This view behaves as the Repositories view in the UVCS GUI client.

Sync replication#

Open a Sync replication view.

Workspace explorer#

The Workspace explorer view is the same as the Workspace Explorer in the UVCS GUI. Normally items are handled in Visual Studio through the Solution Explorer, but this view can be better suited for files in the workspace that are not contained in the Visual Studio solution.

Pending changes on workspace#

Open a Pending changes view displaying with the changes of the whole workspace. Like the Workspace explorer view, this one makes more sense when the user needs to look at changes on items not contained in the Visual Studio solution. To open a view that only contains the changes in the solution, see the Pending changes under solution view above.

Show workspace working info#

Open a workspace status view. It contains details about the workspace, such as the location on disk of the workspace as well as the repository and branch loaded in the workspace. This view is slightly different to the UVCS GUI counterpart (the workspace status bar) and is meant to be docked in a visible place inside Visual Studio. But the information shown is essentially the same.

For more details, refer to chapter Introduction to the Graphical User Interface in the UVCS GUI guide.

UVCS preferences#

Open a Preferences dialog to change UVCS settings. This window is the same as the Preferences window available in the UVCS GUI.

 Rearranging the Windows#

All the views opened from the View > Plastic SCM menu can be arranged with the usual docking controls found in Visual Studio.

To dock any UVCS view, drag the window or tab title and drag it. Visual Studio will display the docking guides that let you dock the window in the desired location.

Working offline and unbinding the solution from UVCS#

When a solution has been bound to UVCS, the plug-in will try to connect to the UVCS server to perform each operation (checkout, checkin, diff, annotate, etc). If the server is not available for some reason, most of the operations will fail, after some time spent waiting for the network timeout.

It is possible to set the UVCS plug-in into "offline mode", so that the operations that require the server are not available (like annotate or diff), but still it is possible to make changes in the code. Later, when the connection with the server is back, those changes can be sent to it by setting the plug-in online again.

To set the solution offline, go to:

File > Plastic SCM Source Control > Change Source Control

The bindings dialog appears and displays the status of the solution and the different projects inside it.

To work offline, select all the items in the table and click the Disconnect button. The green status line "The Plastic SCM plug-in is Connected" changes to a red "The Plastic SCM plug-in is disconnected (Working offline)".

If you right click on an item in the Solution Explorer, the only UVCS command available is Checkout for edit. When an item is modified, it is indeed checked out in the workspace.

To go online again, open the bindings dialog and select all the items in the table and click the Connect button. The red status line changes back to green and the items that were checked out locally while offline are now checked out in the source control.

Binding and Unbinding#

This same dialog also lets you remove the bindings from the solution so it is no longer connected to UVCS, as well as bind it back if needed.

To unbind the solution, select all the items in the table and click the Unbind button. The status column for all the selected items should change from "Bound" to "Not bound".

To bind the solution with the UVCS plug-in, select all the items in the list and click the Bind button. The status column changes from "Not bound" to "Bound".

Configuring UVCS options#

Additional options can be configured inside Visual Studio once the "Plastic SCM Source Control Package" has been selected as the source control plug-in. Go to:

Tools > Options > Source Control > Plastic SCM settings

Preferences#

This button opens the Preferences dialog from the UVCS GUI. It is the same as the menu command View > Plastic SCM > Plastic SCM Preferences.

Delete files in UVCS when they are deleted in Visual Studio#

Visual Studio provides hooks to notify the UVCS plug-in when certain operations happen. For instance, when a file is moved, Visual Studio notifies the UVCS plug-in of this fact. However if you move a file between different projects inside the solution, Visual Studio notifies this as a deleted item in the source project and a new added file in the destination project. This is normally not desirable from the source control perspective because the history if that item is "lost" (it is there, but you will have two items, the old and the new, instead of the one single item that has been moved).

UVCS is capable of detecting when a file has been moved on its own, so when this option is not set (the default), the moved items detection is handled by UVCS. The only thing to consider is that, in the pending changes view, the option to "Show deleted items" has to be checked and everything will work smoothly.

If Delete files in UVCS when they are delete in Visual Studio is set, then moving a file between projects will appear in UVCS as if the file has been deleted from the source and added new in the destination.