The ClearCase Bridge User Guide
Contents
Introduction
Welcome to the ClearCase bridge products CC2SVN and CC2GIT.
This user guide gives information for users of repositories being bridged, and in particular important information that is necessary for dealing with "Merge Conflicts" within bridges. THe latest version of this document is available on our website
For details on bridge setup, planning, and installation, please refer to The ClearCase Bridge Administration Guide.
Overview
The ClearCase bridge transparently synchronizes data between ClearCase, Subversion and Git. Hence, you can have one part of a team working with Clearcase, and another part working with Subversion or Git, and they can all work together seamlessly, without knowing that some people are using another type of SCM system.
So, for example, as a normal user of Subversion, you carry on making changes using your normal Subversion tools. The only difference you will see is that members of the team working at the ClearCase end of your bridge may also make changes, and these will appear in your Subversion repository simply as if another user has made those changes.
The ClearCase Bridge creates links between a ClearCase view on one side and a Subversion or Git workspace on the other as shown in the following diagram.
As users work normally within their ClearCase, Subversion and Git environments, data is transferred automatically in the background. This process should be fully transparent and users do not need to do anything special for bridging to take place.
When data is checked in to ClearCase, a regular update process will pick up these changes and transfer them to the other side.
Similarly, when changes are committed in Git or Subversion, the bridge will pick up the new data on the next regular update and transfer it to the ClearCase environment.
Merge Conflicts
Most of the time, the changes from either side of a bridge will not overlap, so the bridge will work transparently. However, if the same data is being modified at both ends of a bridge, and these changes conflict, users will need to intervene to resolve these conflicts. (This is the same situation as 2 people making conflicting changes while working on the same files in one repository). Each Bridge that is created can be configured with a list of email addresses ("resolvers") for this purpose.
In this scenario, the set of "resolvers" (set up by the Administrator) for a bridge are informed via email, and it is their responsibility to communicate with the teams at either side to resolve the conflict by applying a "Fix Activity" (ie a change that fixes the conflict). You might set a project lead as a sole resolver, or you might have a distribution list that goes to all team leads on a project, or you can even have all of your individual developers on the resolvers list if you like. However you prefer to set this up, it is important that the people being emailed can arrange for the problem to be fixed as soon as a problem arises.
The next section explains how to deal with the most common conflicts.
Problem Types and Resolutions
As data is being transferred in the background by a process not normally observed by users, email notifications are provided should a bridge encounter any problems.
Email notifications contain a list of all the issues encountered during a bridge update.
Potential types of problem that a bridge may encounter are:-
- A change on one side conflicts with a parallel change on the other side of a bridge ("Merge Conflicts").
In the case of ClearCase, a reserved checkout on the same branch makes it impossible for a bridge to apply a change.
- A system error causes an update to fail.
Whilst some of these issues can be prevented by using an intelligent bridge setup (please see the Administration Guide for details), problems may still occur and you need to know how to resolve such problems.
As a general rule, if you receive any error message from a bridge, you must inspect both ends of the bridge and compare the file(s) in question in order to confirm whether the problem is permanent or not. The simple fact that you may not get any further error messages on future updates is not an indication that the problem has been resolved. Error messages from a bridge usually indicate that the bridge was unable to resolve an issue automatically and that manual intervention is required.
The following sections explain how to deal with the most common types of issues. Each section has a Signature subsection describing how to recognize a particular type of problem, and a Resolution subsection explaining how to resolve an issue of that type.
Note that if your Administrator has enabled INFO log messages for the CC2X Server, they can identify on which side of the bridge a problem occurred by the INFO message in the log file which preceded the error. INFO messages relating to SvnWorker relate to the Subversion side, CcWorker relates to the ClearCase side and GitWorker relates to the Git side.
Subversion Merge Conflict
A Subversion merge conflict occurs if the same parts of the same file are changed at both ends of a bridge in between two update cycles. As update cycles tend to be fairly short, this should not be a very common occurrence. However, if you do receive a Subversion merge conflict error, you must act in order to resolve the problem.
Signature
A Subversion merge conflict error looks as follows:-
[Bridge mybridge-1] *** Object mydir/myfile is in conflict, reverting change, repositories are going out of step. This problem must be resolved through checkin of a fix version!
Resolution
The easiest way to resolve a Subversion merge conflict is to manually create a new revision/version of the file at either end of the bridge and commiting/checking in the change. The bridge will then transfer the manually merged version of the file at the next regular update.
ClearCase Merge Conflict
ClearCase merge conflicts are very rare by nature and you should not see these very often. A ClearCase merge conflict occurs if a file is checked out unreserved on the same branch as the bridges view and if the file is checked in between the bridge's checkout and checkin operations to apply a change. As the bridge only holds checkouts for a very short period of time, these types of conflicts do not occur very often.
Signature
A ClearCase merge conflict error looks as follows:-
[Bridge mybridge-1] *** Failed to propagate a change_file from Subversion to Clearcase! (cc_file=mydir/myfile error=cleartool: Error: The most recent version on branch "\main" is not the predecessor of this version. cleartool: Error: Unable to check in "mydir/myfile".)
Resolution
You can resolve a ClearCase merge conflict by merging the changes between the ClearCase version of the file at the ClearCase end with the Git/Subversion version at the other end and checking in a new version at either end of the bridge.
Please note that you can eliminate ClearCase merge conflicts by using a special branch for the bridge to use in ClearCase. Please refer to the ClearCase Bridge Administration Guide for details.
Other ClearCase Errors
The most common problem is that a file is checked out on the same branch as the one that the bridge's view has been configured for. Other potential problems are system errors such as incorrect permissions or a vob or view having run out of disc space.
Signature
Examples of ClearCase errors are shown below:-
[Bridge mybridge-1] *** Failed to propagate a change_file from Subversion to Clearcase! (cc_file=mydir/myfile error=
[Bridge mybridge-1] *** Failed to propagate an add_dir from Subversion to Clearcase! (cc_dir=subdir/newdir error=cleartool: Error: Branch "\main" of element is checked out reserved by view user1_view ("cchost1:c:\ClearCase_Stor
age\views\CLEARVIS-8D48C5\Administrator\user1_view").
cleartool: Error: Unable to check out "subdir".)
Resolution
The effect of this type of issue is that a change in Subversion has not been propagated to ClearCase. Before attempting to resend the data, you need to cancel the checkout in the other view. Please speak to the developer in question and inform him/her that his change conflicts with a change coming from the other end of the bridge.
Once the checkout has been cancelled, you can apply a property change on the Subversion side, which will cause the data to be resent, e.g.:-
svn propedit FORCE_SEND mydir/myfile svn commit
This will cause the data to be resent on the next regular update. Note that the name of the property, FORCE_SEND in this case, is not relevant. Any property change will cause a file to be resent.
If the developer does not want to cancel their checkout, another possible resolution of this type of issue is to ask the developer to manually merge the changes from the Subversion side into their checked out version in ClearCase.
Please note that you can eliminate problems due to parallel checkouts by either of the following two methods:-
Use a special branch for the bridge to import data onto, i.e. a branch not used by any other user. This setup is also commonly used for ClearCase's multi-site implementation.
- Always use unreserved checkouts. Note that you can enforce unreserved checkouts using a trigger that makes every checkout unreserved.
Other Subversion Errors
The most common problems you may encounter are related to a commit failing due to hooks preventing data from being checked in or the repository running out of available disc space.
Signature
Subversion errors typically look like the following examples:-
[Bridge newbridge-1] *** Cannot remove file 'nosuchfile': svn: 'nosuchfile' does not exist [Bridge newbridge-1] *** Cannot commit changes to subversion:: svn: Commit blocked by pre-commit hook (exit code 1) with no output.
Resolution
The easiest way to resolve a problem with applying changes to the Subversion repository is to reapply the change in ClearCase. If the problem was due to a system issue such as the repository running out of disc space, and if you only want to resend a file, you can make a fake change by checking the file out, and checking it back in again on the ClearCase side using the -identical option.
cleartool co myfile cleartool ci -identical myfile
This will cause the file to be resent with the next regular update.
Git Ahead Errors
Signature
The error message contains something like this:
# Your branch is ahead of 'origin/master' by 2 commits.
Resolution
This usually only happens after some other errors have occurred that the bridge could not automatically deal with. In this case, the administrator will have to step in and go in to the server's private repo for the bridge in the cc2x workspace (eg ~/cc2x_workspace/git/my_bridge).
Usually if you just do a
git push
from inside here, this will get the bridge back in step. (Do this while the server is stopped)
Background Information
The ClearCase bridge uses ClearCase attributes, Subversion revision properties and Git ??? (Tushar: TODO) to track whether data was created by a user or by a bridge.
If you come across ClearCase attributes called clearvision_cc2x or Subversion revision properties called clearvision:cc2x, please do not modify this metadata unless instructed to do so by a Clearvision support engineer.