View Compare-Merge common problems



View Compare-Merge common problems


Information in this Brief applies to:

  • StarTeam 5.x
  • Windows NT, Windows 2000


View Compare/Merge is a complicated procedure and this article discusses the common areas that are often misunderstood.


1. Understanding Visual Merge and Visual Diff

The differences between Visual Diff and Visual Merge are often confused. They look similar but are very different. When you perform "merge items" or "auto-merge" in View Compare/Merge, it brings up Visual Merge while "compare items" brings up Visual Diff.

Visual Diff is a text comparison utility. Using Visual Diff, you can quickly compare two different revisions of a text file or two similar text files. The files are compared with one another and no other information is involved. When you launch Visual Diff in View Compare/Merge by choosing to "compare items", you are performing a straight comparison between the revision of the source file against the revision of the target file.

Visual Merge is a utility that helps you merge two text documents that are different but based on the same StarTeam revision (which we call a "common ancestor") For example, if two team members check out the same revision of a file and make changes to their working copies simultaneously, the first to check in the file creates a new revision. The second finds that the status of the file is Merge. That means that checking in the file will override the changes in the tip revision (because they are not in the revision that is about to be checked in.) StarTeam helps you combine the changes in these files so no work is lost.

When you launch Visual Merge in View Compare/Merge by choosing "merge items" or "auto-merge", you get a window with 3 panes. The Top-left pane shows the differences between the source file and the common ancestor, and the Top-right pane shows the differences between the target file and the common ancestor. The bottom pane is the resulting "merged" file. It is important to understand that the differences shown on screen (Top-left pane and Top-right pane) are not the differences between the source and target file but rather each file against the common ancestor. For example, if the common ancestor is revision 1.0, then the Top-left pane will show you the differences between revision 1.0. against the source revision of the file (i.e. revision, and the Top-right pane will show you the differences between revision 1.0 and the target revision of the file (i.e. revision 1.2).

The line differences in Visual Merge are marked in colors:

Green indicates that the line has been added in this revision but did not exist in the common ancestor (i.e. revision 1.0)

Red indicates that the line has been removed in this revision but existed in the common ancestor

Blue indicates that the line has been modified in this revision and is different from its common ancestor

Users often get confused when they see matching lines when they compare the Top-left pane with the Top-right pane and yet the lines are marked in blue. Since the lines match between the two, users readily think there should be no difference. However, if you understand that the revision of the file shown on the Top-left pane is NOT directly compared to the revision of the file on the Top-right pane, then you know why it is so.

2. Understanding merge tracking and setting merge points

With merge tracking turned on, StarTeam remembers the last time you merged two corresponding items (one from the source and one from the target view). Regardless of what changes were included or excluded during the merge process, StarTeam considers the two items to be identical after the merge. Then, StarTeam reports that the two corresponding items need to be merged only when new changes are made to either or both of the items.

With the merge tracking feature turned off, StarTeam considers any two corresponding items as different unless they are truly identical.

A common misunderstanding is that users assume that when merge points are set, the merged file should match the contents of both source and target file. This is incorrect. When merge tracking is turned on, and you perform a merge, the merge results don"t necessarily have to match the contents of the source file or the target file. Usually it is a mixture of both files in the merge results. Merge tracking saves the fact that these files have been merged and you are happy with the results the way they are. This does not mean that the file in the source and target views have the same content. It just indicates that you have "resolved" the merge situation. When merge tracking is turned off however, it ignores that you decided that it was "resolved" and compares the file contents. Obviously the merge results checked in did not match the contents of the source file (since it had parts of the source and target changes in it), so it displays in the lower pane as requiring merging.

Be aware that if you turn off merge tracking after you have been using merge tracking, all the differences will show up again and you will see the file as needing to be merged. We recommend that you do not alter between turning merge tracking on and off. Keep to one choice and only turn off merge tracking if you made a mistake on a previous merge where a merge point has already been set and want to rectify the problem.

NOTE: Reconciling the merge in one direction (child -> parent) only flags it as resolved for that direction. If the merge is performed the other direction (parent -> child), all differences are marked as needing merge until they are reconciled in this direction as well.

To use merge tracking:

¨ From the View Comparison window, select Display\Use Merge Tracking For Merge Resolution from the Item or pop-up menu.

To record merge information:

¨ During manual or automatic merge operations or during reconcile operations, check the Record Merge check box.

3. Understanding effects of sharing items from View Compare/Merge.

Using View Compare/Merge, you can choose to share items in the source view into the target view if it doesn"t already exist in the target view. This is equivalent to a normal "share" of objects between views. Thus, if the source view is a branching view based off a floating configuration, and the target view is the parent view, then the items shared from child to parent will be shared back into the child view if the folder the item is in, has not yet branched in the child view. This causes the file to appear twice in the same view.

When you create a branching view based off a floating configuration, then changes in the parent view will propagate down to this child view until the object in the child view has been branched. Since folders are separate/unique objects in StarTeam, branching a file in a folder does not branch the folder itself. New items added to this folder in the parent view will be shared into the same folder in the child view until you branch the same folder in the child view. (You can branch the folder in the child view by modifying the folder"s properties)

When using branching views based off a floating configuration in View Compare/Merge, you must be careful when sharing items. (More often than not, child views are based off a labeled configuration or a specific time in which case, this problem will not be present.) Understand the child view"s configuration before you perform any share. If you have already shared the items and you find duplicate files in the child view, a workaround is to delete the shared file since deleting one end of a share does not delete other respective shares. Make sure you check the object IDs of the shared file before you delete it. Files with the same name does not necessarily mean they are the same files. You can identify the same files if they have matching ObjectIDs and if it is the case, you can safely delete the duplicate share.

4. Understanding why an item is not showing up as having conflict or needing merge when you expect otherwise.

This is a common issue where a user is expecting to merge a file but the file does not show up in View Compare/Merge as needing to be merged. The problem here is that the files might have the same name but they are not rooted from the same common ancestor so View Compare/Merge does not see them as related files. This happens when the branched file was accidentally deleted and then re-added. When you re-add this file into StarTeam, it is a brand new file and does not share a common history with the original file. To workaround this issue, you can either un-delete the file or merge the current file outside of View Compare/Merge. For more details on how to do this, please contact StarTeam support.

5. Understanding limitations of View Compare/Merge.

a.) View Compare/Merge does not list items recursively. It does not recurse through folders.

b.) View Compare/Merge does not stop items from being shared back to a floating child view as indicated in item #3 of this document.

TIP: An alternative is to use the viewmerge command line utility (viewmerge.exe under the StarTeam client installation directory). The command line utility does not have the above two limitations and allows users to run the merge as a batch job. Please refer to the StarTeam Administrator"s guide or online help for more information on how to use the viewmerge command line.

Old KB# 28429
Comment List