Plastic SCM provides a comprehensive integration with Visual Studio 2005 and newer versions. In the form of a Visual Studio Extensibility Package, this integration offers the user most of the functionality found in the Plastic SCM GUI right inside Visual Studio.
This section will describe the functionality and commands of the Plastic SCM Source Control Package for Visual Studio. Basic knowledge of Plastic SCM 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 INTRODUCTION TO PLASTIC SCM and the PLASTIC SCM GUI GUIDE.
The Plastic SCM Source Control 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.
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.
Before using Plastic SCM inside Visual Studio, the solution has to be added to Plastic SCM. Adding the solution to Plastic SCM binds them together and this binding is stored inside the solution and project files.
If no other developer has added the solution to Plastic SCM 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 Plastic SCM plug-in will show a dialog to create a new workspace. This dialog is the same used to create a new workspace in the Plastic SCM GUI client. For more details, refer to the PLASTIC SCM GUI guide.
The new workspace configuration can be customized using the following commands:
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 Plastic SCM. This dialog is the same used to create a new repository in the Plastic SCM GUI. Refer to the PLASTIC SCM GUI guide for more details.
If the solution was already contained in a workspace, although it had not been added to Plastic SCM 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 Plastic SCM defines it) they are decorated with a lock icon.
When the solution has already been added to Plastic SCM 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 Plastic SCM repositories. The sequence is this:
If the files that make the solution are already in a Plastic SCM, but the solution and projects are not bound to Plastic SCM, 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 Plastic SCM GUI.
Once the solution is bound to Plastic SCM, most of the changes in the solution are handled transparently by the Plastic SCM 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 PLASTIC SCM GUI guide.
Plastic SCM 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.
Any open document in the code editor has an associated context menu. The Plastic SCM plug-in adds some options to that menu, detailed below.
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 PLASTIC SCM GUI guide.
The revisions table on the top panel has one row for each revision of the file. It has the following columns:
The top panel has several controls to filter the list of revisions upon the following criteria:
The Plastic SCM 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).
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 Plastic SCM 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.
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.
For more details, refer to chapter Introduction to the Graphical User Interface in the PLASTIC SCM GUI guide.
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 Plastic SCM 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.
When a solution has been bound to Plastic SCM, the plug-in will try to connect to the Plastic SCM 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 Plastic SCM 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 Plastic SCM 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.
This same dialog also lets you remove the bindings from the solution so it is no longer connected to Plastic SCM, 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 Plastic SCM plug-in, select all the items in the list and click the Bind button. The status column changes from "Not bound" to "Bound".
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
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).
Plastic SCM 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 Plastic SCM. 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 Plastic SCM when they are delete in Visual Studio is set, then moving a file between projects will appear in Plastic SCM as if the file has been deleted from the source and added new in the destination.
Plastic SCM provides a complete integration plug-in for the Eclipse IDE covering the most common operations needed by developers. Eclipse version 3.1 and higher are supported.
This section will describe the functionality and commands of the Plastic SCM Eclipse integration plug-in. Basic knowledge of Plastic SCM 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 INTRODUCTION TO PLASTIC SCM guide and the PLASTIC SCM GUI guide.
Most likely the first operation a developer can do is putting some existing code project in the source control system. In Plastic SCM, this means adding the code to the repository (the repository is the database on the Plastic SCM server that holds all the data about files, directories, versions and branches).
Adding a project to Plastic SCM is a two step process. First create the workspace and bind the project to Plastic SCM, then add the files to the repository.
To add an existing Eclipse project to the repository, a Plastic SCM workspace a needed. Normally the workspace will be created in the same directory where your code already sits.
In the following example, the workspace is located in 'c:\wks', and the project structure will be the following:
C:\wks
C:\wks\projectC:\wks\project\src\
Open the project in Eclipse as usual. To add the project to Plastic SCM, right click on the top directory (that of the project itself) in the Package Explorer and select:
Team > Share project
Eclipse will ask about the repository type. Depending on the plug-ins available to your Eclipse installation, different options may appear. Choose "Plastic SCM" to continue.
The plug-in needs to find the Plastic SCM binaries directory. It will try to locate the Plastic SCM command line interface executable "cm" in the PATH environment variable automatically, but if it is not found, a dialog will be displayed so the user can enter the location of such file. This file is located under "client" in the Plastic SCM installation directory.
Then the plug-in will ask to create a workspace. The next figure shows the fields needed for this.
Once this is done, the project is bound to Plastic SCM. The next step is to add the files to the repository. You can add the whole project or just a part of it. To add the whole project, right click on the project in the Package Explorer and select:
Team > Checkin pending changes...
Once added, the items in the Package Explorer display the status as "Controlled" through a decorator.
Once the project is in the repository, other developers don't need to add it again; they will simply download it from the repository. To do this, go to:
File > Import...
The import dialog opens up. Select "Plastic SCM" and "Projects from Plastic SCM" inside it:
The step in the wizard lets you select the data source. In Plastic SCM, this means the repository where the project is contained in the Plastic SCM server, as well as the specific branch whose content will be downloaded to the workspace.
First select the repository:
Then click Next and, in the new dialog, select the branch to proceed to the next step.
In the next step of the wizard, you can select an existing workspace or create a new one. The workspace is the directory in the local disk where the code will be downloaded from the repository.
Normally you will create a new workspace to work on the new project you are connecting to. To do so, click the Create new workspace button. The new workspace dialog appears, with the same fields described in the Adding projects to the source control system section.
The next page summarizes the details of the workspace that will be created. It contains the directory where the code will be downloaded and the repository and branch (or label) from which the code will be downloaded.
Clicking Next, the workspace will be updated and the code downloaded from the repository. Once this is done, the next page of the wizard lets you import the code from the Plastic SCM workspace into Eclipse, as shown in the figure below:
Now you can choose whether to import using the familiar Eclipse wizards: "Import resources wizard" or "New project wizard". Three options are available once all the data is downloaded into the workspace.
If using the "New project wizard", make sure to select the location of the workspace you have just created, overriding the default. For instance, if your Eclipse workspace is located in:
c:/Users/tester/EclipseWk
and the Plastic SCM workspace you just created is located in:
c:/Users/tester/plastic/prjwk
you want to specify this directory as location, opposed to the default location c:/Users/tester/EclipseWk.
Another possible way to work in a project is to create the Plastic SCM workspace and downloading the contents from the repository outside Eclipse, and then bind the project. Creating the workspace and updating it can be done using the Plastic SCM GUI or the command line interface (the cm command).
Once the workspace is populated with the code from the repository, it only needs to be bound to Plastic SCM inside Eclipse. To do so, right click on the project in the Package Explorer, and select
Team > Share project...
Then proceed as described in the Adding projects to the source control system section, but this time the source code files are already added and that part can be skipped.
The Eclipse plug-in lets you perform the most common operations on files. These operations can be found under the Team submenu right clicking on a file in the Package Explorer.
Here is a description of the Plastic SCM specific operations in the Team menu:
Note that if the selected items are directories, this operation will also list the pending changes inside those directories. If this operation is performed on the project itself, then all the pending changes are listed. This is, indeed, the most common use of the check in operation.
The history view lets you open any given revision in the editor, as well as compare the selected revision with the current one in the workspace, or compare any two revisions.
When two revisions are compared, a differences tab is open inside Eclipse. The figure below shows this.
To compare any two revisions, select both by holding down the Control key (or Command in a Mac computer) and clicking on the desired revisions. Right click and select Compare revisions.
If the selected file is checked out, the content of the file in the workspace is compared to the latest revision of the item in the repository.
The tooltip displays the author that created the change, the changeset number, the date it was created and the comment associated to the changeset.
Decorators are small overlay icons drawn on top of items in the Package Explorer that tell you the status of the item. This is a summary of the possible status:
Decorators are activated by default when the Plastic SCM Eclipse plug-in is installed. It is possible to enable or disable them by going to
Window > Preferences > General > Appearance
Check or uncheck the Plastic SCM Decorators option to enable or disable the decorators, respectively.
Plastic SCM provides several views to access repository objects and their operations right inside the Eclipse IDE. Although the functionality in these views is not as complete as the Plastic SCM GUI, they provide enough functionality to a developer to work comfortably without leaving the IDE.
The next figure displays the available Plastic SCM views. To show any of these views, go to:
Window > Show View > Other...
In the dialog that appears, open the Plastic SCM category, select the views you want to show in the IDE and click the Ok button.
Open a Branch Explorer view similar to the one in the PLASTIC SCM GUI guide.
Inside the Branch Explorer view you can run the following operations right clicking in a branch:
If you right click in a changeset in a branch in the Branch Explorer view you can execute this operations:
Open a new view that shows all the branches created in the workspace.
The Branches view has these operations:
You can get further information about the Branches view in the PLASTIC SCM GUI guide.
The changeset explorer view lets you explore the changesets of the repository currently loaded in the workspace. This view is a table with the list of changesets where the comment, date, branch and author of the changeset are displayed.
In the Changesets view you can execute the following commands:
Open a new view where you can see all the labels created in the current workspace.
These are the label operations:
Display the Pending changes view with its own toolbar:
These are the commands available in the toolbar:
The workspace explorer view lets you explore all the previous views of the repository currently loaded in the workspace.
Besides, lets you execute the following operations:
Plastic SCM provides complete support for refactor operations, especially effective when renaming and moving items from one directory to another.
This behavior is due to the way in which Eclipse handles refactor and plug-in communication. You will only have to click Back and Next again and the refactor operation will correctly finish.
To set the preferences for the Plastic SCM Eclipse plug-in, go to:
Window > Preferences > Team > Plastic SCM
A dialog is shown where the following option can be set:
Plastic SCM provides integration with Mylyn 3.0 or later; this version of Mylyn works fine in Eclipse 3.4 or later.
This feature is very useful when using task controls (see the TASK AND ISSUE TRACKING SYSTEMS guide of Plastic SCM to obtain a list of task controls that can be connected to Plastic SCM), because the user will be able to work on his / her tasks from the Eclipse environment, checking out and checking in the files and linking those changes to a certain task.
To install the Mylyn integration it is necessary to check the following option when installing or upgrading the Plastic SCM client:
Then, the installer will ask you for the Eclipse location. Specify this information and proceed with the installation process.
When the installation is finished, the Mylyn integration is ready to work with (as long as you have Mylyn installed in Eclipse; otherwise this plugin will not work at all).
If you have Plastic SCM GUI configured with a task control you do not need to do anything else. Continue reading the section Using the Mylyn integration; otherwise you will need to configure the Mylyn integration. To learn about configuring task controls in Plastic SCM GUI, please, check the TASK AND ISSUE TRACKING SYSTEMS guide.
To configure the Mylyn integration, go to
Window > Preferences > Team
and finally Plastic SCM for Mylyn in the list provided in the left pane. You will see something like this:
If you have the Plastic SCM GUI already configured with a task control you do not need to change anything.
You can choose if you want to link branches with tasks or changesets with tasks. The most common scenario (and the one we recommend) is the first one.
If you have chosen to link issues with Plastic SCM branches, specify the branch prefix that will be linked with the tasks ID. Finally, click on Ok.
Once the appropriate task control is configured in Mylyn, and having the 'Task list' view opened, just click on the bullet that appears on the left of a certain task, as you would do when working on a task from Mylyn as usual. The following dialog appears:
In this dialog you can select a workspace that is configured with the opened projects (by default is selected the current one, opened in Eclipse). In the list shown below Plastic SCM lists the branches which prefix matches with the task ID of the selected task. This information will be taken from the Plastic SCM GUI or from the Preferences window, as explained before.
You can select the branch that will be associated with the selected task, add and select another one that is not listed, remove branches from the list or create a new one, which will take the configured prefix by default. Finally, press OK.
Plastic SCM will switch to the specified branch automatically; this way working in a specific task from Eclipse is very easy: you simply select the desired task, specify the branch to work on and automatically you are doing changes in that branch.
Mylyn will filter the Package Explorer view with the files that have been modified previously in other tasks, as it believes that a user often modifies the same files; anyway you can see the whole project by clicking on the 
icon in this view.
