Loading Content from a Jazz Source Control Repository in Rational Team Concert 2.0, 3.0 and 3.0.1
This article presents several ways to load content from a Jazz Source Control repository using the Eclipse-based Rational Team Concert (RTC) client and the Source Control command line client (SCM CLI). It begins with the basic forms of loading that existed in RTC 1.0 and then describes some of the new ways to load content that were introduced in RTC 2.0. Loading content using the client for the Visual Studio IDE is not covered in this article but will be covered in a future article.
If you are using Rational Team Concert 4.0 or later, you should read the Loading Content from a Jazz Source Control Repository in Rational Team Concert 4.0 article instead.
Table of Contents
- Basic Load Scenarios
- Advanced Load Scenarios
- Loading Folders Outside of the Eclipse Workspace
- Loading the Component Root Folder
- Loading a Folder More Than Once
- Loading a Single File
- Loading using the Source Control Command Line Client
- Editing Content Outside of the RTC Eclipse Client
- Summary
Basic Load Scenarios
This section describes the basic load scenarios. These scenarios, for the most part, existed in RTC 1.0 and remain the same in RTC 2.0 and beyond. The basic scenarios are:
- Loading Eclipse projects into an Eclipse workspace
- Loading folders that are not Eclipse projects into an Eclipse workspace
- Reloading folders when they have become out-of-sync with the remote workspace
Loading Eclipse Projects
The most straight forward load scenario is the loading of Eclipse projects into an Eclipse workspace. An Eclipse project is a folder that contains a .project file that configures the folder to be a project in an Eclipse workspace. Choosing the Load action from the context menu of a workspace or component entry in the Team Artifacts view will open the Load wizard. The first page, shown below, allows you to specify what type of load to perform. The default option is Find and Load Eclipse Projects which is the option we want for this scenario.
You can click Finish on the first page to load all the projects in the selected workspace or component. You can also go to the next page to manually select which projects to load. This page, shown below, shows you a flat list of folders, grouped by component, that contain a .project file.
When loading Eclipse projects, you may need to create projects that appear in the Eclipse workspace but are not located in the Eclipse workspace directory. This was not possible in RTC 1.0 because content could only be loaded into the Eclipse Workspace. However, as of RTC 2.0, content can now be loaded into other locations on disk. Directories into which content is loaded are referred to as a local sandbox. The sandbox directory will contain any content you load as well as some extra data used to manage the synchronization state between the local data and the remote workspace from which it was loaded.
The target sandbox for a load can be set using the Advanced Options available on the project selection page of the load wizard. The following screen shot shows these options. The user can specify the Eclipse workspace directory or another directory as the target sandbox for the load. The select projects will then be created and loaded as subfolders in the specified sandbox directory.
You can see the sandboxes that are currently in use by your RTC client on the Team > Jazz Source Control > Sandboxes preference page. From that page, you can perform various management such as adding new sandboxes, removing a sandbox from the list of known sandboxes or deleting the sandbox entirely.
Loading Folders as Eclipse Projects
In some cases, you will want to load folders that are not Eclipse project folders and hence do not contain a .project file. This can happen for several reasons including:
- The folder you want to load is a subfolder of an Eclipse project folder but you only need the content within the subfolder loaded.
- You have imported data from another SCM system and you want to start working with the content inside RTC.
When loading a folder into an Eclipse workspace, you would choose the Browse the components to select the folders to be loaded options on the first page of the Load wizard as shown above. On the second page, shown below, you can then select one or more folders to be loaded into the Eclipse workspace.
In this screen shot, the scripts folder is selected and will be loaded into the Eclipse Workspace as a project named scripts. Because the folder is not an Eclipse project already, the load operation will end up creating a new .project file within the folder which will show up as an Unresolved addition in the Pending Changes view. You can choose to check-in this change or ignore it, depending on whether you want the folder to be treated as an Eclipse project in future loads.
Reloading Out-of-sync Shared Folders
A new option has been added to the first page of the Load wizard in RTC 2.0: Reload projects that are out of sync. The local workspace can become out of sync with the remote workspace due to a couple of reasons:
- The remote workspace is loaded multiple times and changes have been checked in or accepted from another client session.
- An error was encountered during an operation (e.g. Accept) that modifies both the local and remote workspaces.
When the local workspace became out of sync with the remote workspace in RTC 1.0, the user was forced to run the Load wizard and reselect the folders that needed to be reloaded. In RTC 2.0, this new option will automatically select the out of sync folders and reload them so they are no longer out of sync. Also new in RTC 2.0 is an indication in the Pending Changes view that there are projects out of sync, as shown below.
Clicking on the Reload out of sync link in the Pending Changes view will open the Load wizard.
The reload option will be selected by default and clicking next will then allow you to select which folders to reload. As you can see in the following screen shot, all the projects in the Foundation component are out of sync and need to be reloaded. Clicking Finish will reload these folders and bring them back in sync.
Advanced Load Scenarios
In this section, we will describe several load scenarios that were not possible in RTC 1.0 but are now supported in RTC 2.0 and beyond.
Loading Folders Outside of the Eclipse Workspace
In RTC 1.0, any loaded folder became a project in the Eclipse workspace. As of RTC 2.0, content can now be loaded outside of an Eclipse Workspace and, hence, outside of the RTC client. This is done by selecting to load a folder. The folder selection page has an advanced options section that, as with loading a project, allows you to specify an alternate sandbox in which to load the content. The advanced options for the folder selection also allow you to specify whether to create Eclipse projects or not. The following screen shot has the Load the selected folders but do not create Eclipse projects option selected so the script folder will be loaded as a subfolder of C:devsandbox but no Eclipse projects will be created.
When content is loaded outside of the Eclipse workspace, it does not appear in many of the views in RTC (e.g. Project Explorer). However, these files are on the local disk and can be modified using other tools. When files contained in the loaded folder are modified, the Pending Changes view needs to be manually refreshed in order for those changes to be checked in to the remote workspace. The screen shot below shows the refresh menu in the Pending Changes view along with an Unresolved change to a file that is loaded outside of the RTC client.
Once you have refreshed the Pending Changes view to pick up any local changes, you can perform the actions available in the Pending Changes view in the same way you perform actions on content that is available in an Eclipse project. That is, you can now check-in and deliver your changes to a stream, accept changes from a stream and perform the many other actions available in the view. When you modify files or folders loaded outside of Eclipse, you should always refresh the sandbox prior to performing any actions in the Pending Changes view. If you do not, it is possible that local changes will be overwritten by remote changes to the same files. To avoid such loss of data when working outside of Eclipse you can enable backups on the Team > Jazz Source Control > Backup preference page, as shown in the following screenshot.
More details on the backup shed can be found in the article Finding Lost Content with Rational Team Concert.
Loading the Component Root Folder
A Jazz/RTC component has a root folder that can contain files and folders. Typically, the component contains a set of folders and it is these folders that are loaded as share roots on the client filesystem. However, it is possible to load the component root as a share root as well. There are a couple of reasons you may want to do this, which include:
- You may have imported data from another SCM system which resulted in files located at the root of the component
- You may want to have root level folder additions picked up automatically without the need to explicitly share the folders.
It is worthwhile to expand on the second point. Consider a component C that contains two top-level folders F1 and F2. If you load F1 and F2 as share roots and then create a new folder F3, you will need to perform a Team > Share Project action on the new folder for it to be shared. However, if you loaded the component root folder as C and then created a child folder F3 of C, you could simply check in the change and F3 would become another top level folder in component C.
There are two ways to load a component root folder. The first is to select the Load folder option in the Load wizard and check the component itself instead of another folder. For convenience, the component checkbox in the Load wizard is a tri-state checkbox that has the states unselected, select all children, and select the component itself. If you select the component itself, the component will be loaded as a folder with the same name as the component.
The other way to load a component is to choose Load As on the component entry in a Workspace in the Team Artifacts view. When this option is chosen, you can provide a custom name to the folder that will contain the component.
In both of these load cases, you can choose whether to create Eclipse projects or not, as was mentioned in the Loading Folders section. At this point, it is worth mentioning the other load option related to Eclipse projects which will load the selected folder and create Eclipse projects for any folders within the loaded content that contain a .project file. This is the option selected in the two screen shots that illustrate loading the component root. For example, in the first screenshot, the SCM component is expanded to show the project at SCM/plug-ins/client/com.ibm.team.scm.client and loading the component with the selected options will load that project at C:devsandboxSCMplug-insclientcom.ibm.team.scm.client on disk and create the com.ibm.team.scm.client Eclipse project which points to the loaded content.
Loading a Folder More Than Once
In some cases, it is desirable to have different versions of the same content loaded at the same time. The changes made in RTC 2.0 make this possible under certain conditions. There are basically two ways to load the same folder more than once:
- Load the folder into different locations on disk.
- Load the folder using a different name.
RTC now has support for both of these methods of loading but there are some restrictions:
- RTC does not support loading content from the same workspace and component into the same sandbox multiple times. However, you can load the same content from two different workspaces into the same sandbox.
- You cannot load different versions of the same folder into an Eclipse workspace as projects unless a different name is used for each project.
In this scenario, we will load two version of the same folder into our Eclipse workspace. You may want to do this so you can browse or test both versions at the same time. We will first load the folder MyThemes from component My Component in workspace My Workspace. The first step is to select Load on the component in the Team Artifacts view.
In the Load wizard, we then indicate that we want to load folders and, on the next page, we select our folder.
Once we have the folder loaded once, we want to load it again using a different name. To do so, we must first show the folders of the component, located in another workspace, in the Repository Files view.
From there, we can choose Load As on the folder.
We then enter an alternate name for the folder and load it.
We can now see that the folder is loaded twice.
Now that we have two versions of the folder loaded, we can work with either version.
Loading a Single File
In some cases, you may want to make a change to a single file in the repository without loading any other content. In RTC 2.0, this is possible by using Load As in the Repository Files view. To populate the Repository Files view, you can perform a Show > Repository Files action on a Workspace or Component in the Team Artifacts view. You can thin drill down to the desired file and choose Load As from the content menu. This result in the following dialog.
In this dialog, you can use the same file name as the name in the repository or specify a different name. You can also place the file in a folder or folder hierarchy within the chosen sandbox. This gives you some flexibility in arranging the content on disk. Once the file is loaded, you can modify the file and check changes in. However, keep in mind that, unless the file is within an Eclipse project, you will need to manually refresh the pending changes, as described in section Loading Folders Outside of the Eclipse Workspace.
It is worthwhile to note that when using Load As to load a file or a folder, the file or folder does not need to be placed at the root of the sandbox. The screen shot below shows the build.xml script being loaded into the buildScripts folder within the sandbox.
The one restriction here is that the buildScripts folder can not be a shared folder. The ability to load content into unshared subfolders or subtrees within a sandbox is provided in order to give a bit more flexibility when loading content.
Loading using the Source Control Command Line Client
RTC provides an scm command line tool for providing access to Source Control operations from the command line. The executable is available in the jazz/scmtools folder of the RTC Zip install.
To login, you would use the following command where username and password are your credentials and local is an alias that can be used in future commands to identify your repository more easily.
> scm login -n local -u username -P password -r https://localhost:9443/jazz
Once you are logged in, you can search for the workspace or component or folder you want to load. To list the workspaces, you would use the following command.
> scm list workspaces -r local (1009) "My Other Workspace" (1000) "My Workspace"
You can then load a workspace by name or, as we show below, you can load the workspace using the unique identifier that was associated with the workspace by the client. We choose to load My Workspace by using its identifier 1000.
> scm load -r local 1000
The above command would load all the folders in the components contained in the workspace as top level folders in the current directory. If you just wanted to load the MyThemes folder, you could do the following.
> scm load -r local 1000 "My Component/MyThemes"
Again, 1000 identifies the workspace and the first segment of the path is the component name and the subsequent segments represent the path within the component.
The CLI also supports the use of load rules which can be used to load a set of selected folders from a component. For instance, load rules provide a way to load a set of Eclipse projects that may not be at the top-level in a component, as described in Loading Eclipse Projects. For example, to load the Eclipse projects from the SCM component, we could create a file loadrules.txt that contains the following lines:
RootFolderName=/plug-ins/client RootFolderName=/plug-ins/common RootFolderName=/plug-ins/server RootFolderName=/features RootFolderName=/tests
Each line indicates that the child folders of the specified folder is to be loaded as a share root. You could then load these folders from the workspace named Source Control Workspace by issuing the following command:
>load -r jazzrepo -L loadrules.txt "Source Control Workspace" "SCM"
For convenience, you could store the load rules in a file in the repository and use the -R option to reference the remote file instead of -L.
Editing Content Outside of the RTC Eclipse Client
The RTC rich client has buit-in support for editing many types of files and there are plug-ins available for several other file types as well. However, it is not uncommon to use the RTC client only for SCM related operations and to use other tools to edit your files. When files are edited using the RTC client, there is built in support which notifies the SCM client that the files have been edited. This allows the SCM views and operations to have up-to-date information about the files in you sandbox. When you edit files using other editing tools, you will want to make sure that the SCM client has up-to-date information about the file system before any operations are run.
One way to ensure that the SCM client has up-to-date information is to refresh the sandbox from the Pending Changes view before you perform an operation. An option was added in RTC 2.0.0.2 to the Team/Jazz Source Control/Sandboxes preference page to ensure that a sandbox refresh includes all files as shown in the screenshot below. The options is enabled by default which means that a refresh of the sanbox always scans all files. The only reason you would want to turn this option off is if you always use the RTC client to edit your files
Refreshing the sandbox before each operation can become a bit tedious so another options was added to the Team/Jazz Source Control/Local Changes preference page that allows you to enable an auto-refresh during SCM operations. This option is not enabled by default since it does add a bit of overhead to each operation but it is recommended to turn this option on if you regularly edit files with tools other than the RTC client. You should also enable the backup shed on the same preference page as this will ensure that any file being updated gets backed up to the shed before the new content is written out. This is done to ensure that your changes are not inadventently overwritten and lost by an SCM operation.
Summary
In RTC 1.0, users could load folders from a Jazz Source Control repository but there was not a lot of flexibility in how content was loaded. In RTC 2.0, loading became much more flexible by providing the capability to load content into different locations on disk with the option to either bring the content into the RTC as Eclipse projects or to just put the content on disk to be used or edited using other tooling.
About the author
Michael Valenta works for IBM and is a member of the RTC Source Control development team. He is also a committer on the Eclipse Platform project.
Copyright © 2011 IBM Corporation
Yes