Using the RTC Eclipse client with other Tools
The RTC Eclipse based client provides a tool that, in many cases, can act as the user’s repository tooling as well as their editor tooling. When used in this way, the user’s local changes are detected by the Jazz SCM client through the Pending Changes view as soon as the changes are made. However, in many cases, users need to use editors that are not integrated with the Eclipse based client. In these cases, the user may need to take extra steps to ensure that the changes are properly recognized and handled by Jazz SCM. In this brief article, we are going to present various actions and preferences that will allow users to work safely with such editing tools.
Introduction
For some users, it is possible to do all of their work using the RTC Eclipse client. However, for others, Eclipse tooling may only exist for a subset of the file types they deal with. Also, some users may not want to do any file editing in Eclipse but only use the RTC Eclipse client to perform SCM related actions. In this article, we are going to focus on the later two types of users. First we will discuss how users who work partially in Eclipse and partially with other editing tools can ensure their local changes are detected by Jazz SCM. Then we will present how the RTC Eclipse client can be used as an SCM client with all editing done using other editing tools.
Editing with Eclipse and Other Tools
In this section, we are going to present some preferences and actions you can use when you load content into the Eclipse workspace as Eclipse projects but you use editing tools that are not integrated into Eclipse. Some examples of these types of editors are word processing software, presentation software or spreadsheets.
Loading Content into the Eclipse Workspace
When loading content into Eclipse, the default setting in the Load wizard is for the content to be loaded into Eclipse as Eclipse projects. You can find a more thorough explanation of the options for loading content in the article Loading Content from a Jazz Source Control Repository
Ensuring Local Changes are Detected
If you use editors that are not Eclipse based to edit content, you will need to take some extra steps to ensure that your local changes are detected by the Pending Changes view and to ensure you are warned about un-checked in changes that could be overwritten by Jazz SCM operations. In this section, we provide several ways to accomplish this.
If you use non-Eclipse editors to edit content, there are preferences you can enable to help detect these local changes automatically in the pending changes view. Starting with Rational Team Concert 4.0 there is a preference that will detect local changes both inside and outside of the Eclipse Workspace on the Windows platform only.
You can enable the Automatically detect changes option on the Team/Jazz Source Control/Local Changes preference page.
This option does incur some overhead as Rational Team Concert needs to scan the local file system to see if new changes have occurred since the last time a scan was run but the overhead is minimal. The other issue is that there is a time window in between when an external change is made and when it is picked up. If an SCM operation is run in this time window, the local change could be missed.
To overcome the issue presented above, you can enable the pre-operation check for local changes. This preference is available on the Team/Jazz Source Control/Local Changes preference page shown above. In 3.0 the preference is called "look for external changes before modifying or uploading local files," while in 4.0 it has been renamed to "check for changes immediately before the system modifies or uploads files."In either case this option will ensure that any SCM operation that modifies loaded content will check to see if there were any local changes made that are not currently known before running. This is so that the operation can detect any local changes and give you the opportunity to check them in before updating the contents on disk.
The other option presented on this preference page is the Jazz SCM backup shed which should be enabled when using external tools as well. More information on the backup shed can be found in the article Finding Lost Content with Rational Team Concert 2.0.
If you do have your content loaded as Eclipse projects and have modified some files using an external editor, you can explicitly cause the changes to be discovered by refreshing the project in a project view like the Project Explorer, as shown in this screen shot.
The refresh will trigger a resource delta event from the Eclipse workspace that will cause the local changes to be shown by the Pending Changes view.
Eclipse Local History
When content is loaded as Eclipse projects, there is a handy feature available to you called the Local History. If you have made several edits to a file and then realize that you deleted something you want to keep, you can look a the edit history of the file using the Compare with > Local History action.
This action will populate the history view with a time based list of changes made to the file. You can then open any of the entries from the view to see a comparison of the state of the file at that time with the current state of the file.
The Local History can also be used to restore deleted files by choosing the Restore from Local History action which is available from the content menu of projects and folders.
Editing Only with Other Tools
In this section, we are going to present some addition options and actions that are available to users that do not perform any editing using Eclipse based editing tools.
Loading Content Outside the Eclipse Workspace
If a user is not going to edit any content using Eclipse based editors, they may not want to load the content as Eclipse projects. To do so, you would select the option to browse components on the first page of the Load wizard.
On the second page, you would select the folders you want loaded and expand the Advanced Options section, as shown below, to specify the location where you want the content loaded and to enable the option to skip the creation of Eclipse projects.
When loading folders, it is the top level folders of the component that are selected by default (in the above example, that would be the Ruby Project folder). However, in the above screen shot, the component itself has been selected. The result will be that the component root folder is loaded at the file location C:devsandboxRuby Work and this folder will contain all the content from the component. As we will see in the sections that follow, there are some advantages to loading the component root folder. The main advantage of this is that, while the Eclipse client provides some custom actions to share new content and delete or move top-level folders in a sandbox (what is referred to as a share root), these actions are only available when the content is loaded as Eclipse projects.
You can find a more thorough explanation of the options for loading content in the article Loading Content from a Jazz Source Control Repository
Detecting Changes Made Outside Eclipse
If your content is not contained in Eclipse projects, you will want to enable the options presented in section Ensuring Local Changes are Detected. Additionally, you can trigger a detection of any local changes by requesting a refresh of the local sandbox from the Refresh dropdown menu in the toolbar of the Pending Changes view. On the Windows platform using Rational Team Concert 4.0 the changes will be detected automatically if the option is turned on.
This will open a dialog that will allow you to scope the specific resources to be refreshed. If a folder is selected, the folder and all its descendant files and folders are refreshed.
In Rational Team Concert 4.0 you can customize what the default behavior is when pressing the refresh button in the Pending Changes view. For users using RTC for source control only, it is likely that they would want the default behavior to be “Refresh sandboxes and remote changes” when pressed. To do this, users can set this option on the Team/Jazz Source Control/Changes preference page as shown in the figure below. The default action is indicated by a unique icon and bold text in the context menu drop-down.
Sharing, Moving and Deleting Content Outside of an Eclipse Project
In this article, we presented a way to load and work with content using the Eclipse based client without having the content available in the Eclipse workspace. You would only want to work this way if you never (or, at least, very rarely) wanted to use an Eclipse based editor to edit your content. There are some work flows/tasks that are easier to do when contents are in Eclipse projects. These are:
- Sharing new top-level content
- Detecting when files and folders are moved
- Deleting folders that are share roots from the repository
In this section, we present some alternatives for dealing with these issues.
Sharing new Top-Level Content
When we say we are sharing new top-level content, what we mean is that we have a sub tree of files and folders on our local file system that is not contained within a folder that is currently shared with SCM but that we want to upload to the repository. If the new content is a project in Eclipse, sharing is done by simply choosing Team/Share from the context menu of the project. However, if you do not have your content loaded in Eclipse, you have three options available for sharing new content:
- You can create or import the content into Eclipse as an Eclipse project and use the Team/Share action.
- You can load the desired parent folder (or an ancestor of the parent folder) and then create the new content within that folder. As shown in section Loading Content Outside the Eclipse Workspace, the Load wizard supports the loading of component root folders so this is possible regardless of where the target folder is location.
- You could use the Jazz SCM command line tool (CLI) to perform the share.
The first two options are fairly self explanatory but do require a bit of extra work. The use of the SCM CLI is the least disruptive approach but does require the installation of the CLI and the knowledge of how to use it. We will provide a small example of the commands you would use to accomplish this, assuming that you have installed the CLI already (tip: The executable is available in the jazz/scmtools folder of the RTC Zip install).
If Eclipse is already running, all we need to do is run the command to share the new folder. However, we do need to specify the repository and our credentials along with the workspace and component to contain the new content.
> lscm share -r https://my.server.com:9443/jazz/ -u username "My Workspace" "Ruby Work" NewStuff
The above command will prompt for our password and then share the folder NewStuff in the Ruby Work component of the My Workspace workspace in the repository https://my.server.com:9443/jazz/
Tracking Moves
If you move a file that is contained in an Eclipse project using a move or refactor action within Eclipse, the change will automatically be detected by Jazz SCM and appear in the Pending Changes view as a move, which is good since the history of the file changes will be preserved. However, if you move a shared file in the local file system and refresh the Pending Changes view, the move will show up as an add of the file in the new location and a delete of the file in the old location. As of RTC 4.0, the only way to preserve a move for content that was loaded outside of Eclipse is to use the SCM CLI. If Eclipse is running, this can easily be done by using the lscm command.
> lscm move file.txt moved.txt
The above command is what you would use if your current working directory was the parent directory of a file that you are renaming from file.txt to moved.txt. The command will take full paths as well, if you wanted to move a file to another folder.
Deleting or Moving Share Roots
The Eclipse client provides a Team/Delete in Repository action and a Team/Move in Repository action in the context menu of a project that can be used to delete or move the corresponding folder in the repository. There is no equivalent to these actions in the SCM CLI so you would need to load a parent folder of the folder you wanted to delete or move in order to do this if you were working with content that was not available as Eclipse projects.
Summary
The RTC Eclipse based client can still be used as a tool for Jazz SCM even if you make use of editors that are not integrated into Eclipse. However, to do so effectively, you need to be aware of the following points, which were covered in this article.
- You can load content using the Eclipse based client without having the content appear in the Eclipse workspace.
- You will want to enable the backup shed
- You may want to enable the option to look for any local changes before running SCM operations if you are not on the Windows platform or are not using Rational Team Concert 4.0
- A Refresh action is available from the Pending Changes view to explicitly look for local changes.
- Sharing new content, deleting share roots and moving content will require you to either use Eclipse projects or the SCM CLI.
About the authors
Michael Valenta is a member of the Jazz SCM development team. Prior to that, he worked on the Eclipse open source project.
Chris McGee is also a member of the Jazz SCM development team. He worked previously on Rational Software Architect’s UML modeling capabilities.
Copyright © 2010, 2012 IBM Corporation
Yes