IDE integrations

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.

• Workspace name - The name assigned to the workspace. This name is used to refer to the workspace in the Plastic SCM GUI and some other administrative commands.
• Workspace path - By default this is the directory where the project is located. You can adjust it to a different directory, but keep in mind that it should contain your project code.
• Repository - This is the Plastic SCM repository where the code will be stored. Select an existing repository from the dropdown list or create a new one using the button on the right.

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.

• First, you can configure an Eclipse project importing resources from the workspace content; this process uses the Eclipse Import Resources Wizard and at the end of the wizard all the resources imported will be bound to Plastic SCM automatically.
• The second option is to create a new project in the new Plastic SCM workspace; this new project will be bound to Plastic SCM.
• Finally, you can exit directly without configuring any Eclipse project. It can be later done using the File > Import dialog.

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:

Checkin pending changes

Check in the selected items. A Pending changes window appears (see the next figure) listing the items grouped in categories according to the type of change: changed, added, moved or deleted.
You can select what items will be checked in using the checkboxes in each row of the table. Enter the comment associated to the changes in the textbox at the top and press the Ok button to check in the changes.

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.

Checkout for edit

When an item is to be edited, it is checked out so that Plastic SCM tracks the changes. This operation is rarely used, since files are checked out automatically when they have been changed and are saved.

Undo pending changes

Open a new window listing the pending changes of the selected items to confirm that they are being undone. The list of items is grouped in categories for changed, added, moved and deleted, similar to the pending changes window described above in the Checkin operation.
Again, if the selected items are directories, this operation will also list the pending changes inside those directories. If the operation is performed on the project itself, then all the pending changes are listed and can be undone.

Update workspace

Download the latest changes from the repository.

Refresh Status

Refresh the state (checked in or checked out) of the selected items. If any project file has been modified and checked out or checked in outside Eclipse, the state can be refreshed with this operation.

Show Plastic SCM history

Open a new tabbed table with the history of the selected item.

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.

Diff with previous

Open a differences view (as described above) comparing the contents of the latest revision of the selected item with its previous revision in the workspace.

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.

Annotate

Display an annotated view of the selected item. This is a normal editor window with an annotations column on the left. The different colors in this column represent the different changesets that each line belongs to. Hovering the mouse over this column displays a tooltip with extended information about the specific change for the line on the right.

The tooltip displays the author that created the change, the changeset number, the date it was created and the comment associated to the changeset.

Unbind project from Plastic SCM source control

Unbind the project from the version control. This effectively disables the Plastic SCM plug-in for the current project.

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.

Branch Explorer view

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:

Create child branch

Create a child branch of the selected branch. A window is open to enter the details of the new branch to be created.

This dialog lets you set the name of the new branch, as well as the comment and the branch base. The branch base indicates the point where the branch starts and lets you select a label, or a specific changeset in the parent branch (the last one being a special case and having its own option).
Refer to the PLASTIC SCM GUI guide for more details about the Create child branch command.

Switch to this branch

Change the workspace configuration so that it downloads the contents of the selected branch to the workspace. Refer to the PLASTIC SCM GUI guide for more details about workspaces and the Switch workspace to this branch command.

Merge from this branch

Open a merge branch window. This window lists the items that need to be merged from the selected branch to the current configuration of the workspace. For more details about the functionality of this window and the merge operation in general, refer to The Merge Organizer Window chapter in the PLASTIC SCM GUI guide.

Diff branch

Open a Diff window and shows you the differences existing in the selected branch.

Properties

Display a window with the properties of the branch, such as name, comment and merge history.

If you right click in a changeset in a branch in the Branch Explorer view you can execute this operations:

Diff changeset

Open a Diff window and shows you the differences existing in the selected changeset.

Switch to this changeset

Change the workspace configuration so that it downloads the contents of the selected changeset to the workspace. Refer to the PLASTIC SCM GUI guide for more details about workspaces and the Switch workspace to this changeset command.

Label this changeset

Create a new label and applies it to the selected changeset. A new window opens to let you enter the name and comment of the new label.

Go to parent changeset

Show the parent changeset of the selected changeset.

Branches view

Open a new view that shows all the branches created in the workspace.

The Branches view has these operations:

Create child branch

Create a child branch of the selected branch. This is the same command as Create child branch in the Branch Explorer view.

Switch to this branch

Changes the workspace configuration as the same command does in the Branch Explorer view.

Merge from this branch

Open a merge branch window. This is the same command as the above in the Branch Explorer view.

Show in Branch Explorer

Open a Branch Explorer view and highlight the selected branch.

Properties

Display the same Properties window as the same command does in the Branch Explorer view.

Compare with

Compare the selected branch with an Eclipse API baseline.

You can get further information about the Branches view in the PLASTIC SCM GUI guide.

Changesets view

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:

Show in Branch Explorer

Open a Branch Explorer view and highlight the selected changeset.

Compare with

Compare the selected changeset with an Eclipse API baseline.

Labels view

Open a new view where you can see all the labels created in the current workspace.

These are the label operations:

Switch to this label

Switches the workspace to the selected label. This loads a read-only confirmation in the workspace, since labels are not mutable. For more details, refer to the Switch workspace to this label command in the PLASTIC SCM GUI guide.

Apply label to workspace contents

Applies the selected label to the changeset currently loaded in the workspace.

Merge from this label

Opens a merge window to merge the status marked by the label with the items currently loaded in the workspace. At the end, this is the same as merging the changeset to which the label is applied with the changeset currently loaded in the workspace.
For more details, refer to the Merge from this label command in the PLASTIC SCM GUI guide.

Show in Branch Explorer

Open a Branch Explorer view and highlight the selected label.

Compare with

Compare the selected label with an Eclipse API baseline.

Pending changes view

Display the Pending changes view with its own toolbar:

These are the commands available in the toolbar:

Refresh view

Reload the view to show any new change.

Checkin selected changes

Check in the selected items.

Undo selected changes

Undo the selected items.

Show view options

Display a new window to select the items you want to appear in the pending changes view.

Paste last used comment

This option lets you select a used comment o paste the last one used.

Workspace Explorer view

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:

Show pending changes for this workspace

Display the pending changes view including all the changes in the workspace.

Update

Download the latest changes from the repository. This is the same as right clicking in the project in the Package Explorer and selecting Team > Update workspace, described in the Item operations section above.

Plastic SCM provides complete support for refactor operations, especially effective when renaming and moving items from one directory to another.

Note for Eclipse 3.1: Due to an Eclipse 3.1 restriction, solved in Eclipse 3.2, refactor for renaming a package could show an error at the end of the process, like this:

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:

• Command line executable - This is the directory to the Plastic SCM cm executable. The Eclipse plug-in can detect this setting automatically if the Plastic SCM directory is contained in the PATH environment variable. Otherwise, it can be manually set here. Changing this setting is normally not needed unless you need to use several separate Plastic SCM installations on the same machine and want to force the Eclipse plug-in to use one of them.

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.

Installation

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).

Configuring the Mylyn integration

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.

Using the Mylyn integration

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.

Note: If you cannot see the Task list view, please click on Window > Show view > Other on the Eclipse menu and select Mylyn from the list. Select Task Repositories to configure a repository of a task control if you do not have specified one before, or click on Task list to see this view if you have already configured your task control system. Finally, press OK.

August 12, 2014

July 24, 2014