View Compare/Merge (VCM) Overview

This topic presents an overview of comparing and merging views using the View Compare/Merge utility.

View Compare/Merge Introduction

View Compare/Merge is available through two application interfaces:

  • The Cross-Platform Client provides a graphical interface that is integrated with other CPC functionality. The graphical View Compare/Merge tool provides interactive compare/merge functions with per-item and per-folder interaction. This allows you to carefully control which items are compared, and how each difference is resolved. For example, you can select an item, folder, or group of items in a regular view window and start a View Compare/Merge session using the selection as the source scope.
  • The VCMUtility is a command-line tool that allows you to start, resume, and commit View Compare/Merge sessions from shell scripts. In a single script, for example, you could create a View Compare/Merge session, perform a test build of the proposed changes and run other verification tasks, then commit the session if all tests complete OK.

Compared to the use of process items, which tracks file changes within a view, View Compare/Merge is the preferred mechanism for propagating and tracking changes made across views, that is, from one view to another. A common use of View Compare/Merge is to propagate the changes in one view, as tracked by a process item, to another view.

Back to top

About View Compare/Merge Sessions

View Compare/Merge uses a “session” concept, which is a specific view compare/merge operation that can be started, reviewed, adjusted, verified, and then committed. When you save a View Compare/Merge session, a change package object is created that contains all the changes and information about the changes made during that session. Except for locks, no data is modified in the StarTeam repository until the change package for that change session is committed, at which point all changes are applied at once to the target view.

Before a change package is committed, it can be saved and restored – potentially on a different machine. This allows one user to create the change package, then transfer it to a peer for review or to verify the change package before committing it.

The Cross-Platform Client interface allows user interaction with the entire View Compare/Merge process. The VCMUtility provides partial or complete automation of View Compare/Merge sessions, which can be helpful when a specific kind of session is performed repeatedly. View Compare/Merge sessions are interoperable between the two interfaces. For example, you can create and save a change View Compare/Merge session using the VCMUtility, then restore, review, and commit the session using the Cross-Platform Client. You can also apply the same changes in the committed change package to another view using a process called “Replay”.

Back to top

View Compare/Merge Session Views

Two StarTeam views are involved with every View Compare/Merge change session: a source view and a target view.

  • The source view contains the changes to be propagated. You can use the tip configuration of the source view or a snapshot defined by a view label, promotion state, or timestamp. There are several ways to identify the items to be “considered” for propagation, collectively known as the source scope. If you like, the entire view can be used as the source scope, though you will usually propagate items that represent specific changes.
  • The target view receives the propagated changes, so it must be able to be updated. “Receiving” the changes does not mean that the source items are merely copied to the target view as-is. View Compare/Merge compares the source view to the target view and determines if and how to propagate item differences. Propagation of a specific change can take many forms such as sharing, re-pinning, merging, and so forth. You can review and adjust what View Compare/Merge proposes before anything is committed.

Note: The source and target views must belong to the same project.

Back to top

View Compare/Merge Merge Types

Every View Compare/Merge merge session has a specific merge type which controls the direction and semantics of the View Compare/Merge session.

Rebase A rebase session propagates changes from a parent view (the source) to an immediate child view (the target). The most common use of rebase sessions is to “catch-up” a child view with changes that occurred in the parent since the child view was created or since the last rebase was performed.
Promote A promote session is the opposite of a rebase. It propagates changes from a child view to its immediate parent. Promote sessions employ special rules that accommodate the directionality of share trees. That is, they strive to keep share trees pointing in the same direction as the project’s views.
Replicate A replicate session propagates changes from a source view to any other (updateable) view in the same project. Compared to rebase and promote, replicate is the “wild card” merge type that allows changes to be propagated anywhere in the same project.
Compare-only A compare-only session only shows you the differences between views or two configurations of the same view. No changes or merge actions are performed.

Back to top

Why Use View Compare/Merge?

There are a variety of reasons you might want to merge two views. A typical example would be code development in a software development company. If both maintenance and new development for a software product need to occur in parallel, a separate view is often created to store each set of source code files. If you fix some defects in the maintenance view, you may need to merge changes from that view into the new development view so that the next release of your product has the fixes.

You can compare and merge any two views if those views are in the same project. However, in general, you can merge only items that are related (that is, have a common ancestor), even though that ancestor may not be in either of the views you are comparing or merging. The exception to this is when files are matched by name.

View Compare/Merge allows you to do the following to reconcile differences between views:

  • Catch up an activity or child view with new changes from its parent (Rebase).
  • Deliver changes or a completed activity from a child view to its parent (Promote).
  • Duplicate a fix or enhancement from one view to another view (Replicate).
  • Merge items of one view, known as the source view, with items in a second view, called the target view. Changes are stored as updates to the target view.
  • Merge two views using an earlier configuration of the source view.
  • Compare and merge file contents and item properties.
  • Control what is being merged by using one of several selection methods before starting the View Compare/Merge session. For example, individual items may be selected, a folder and its contents may be selected (optionally recursively), or a process item and its linked files can be selected.

View Compare/Merge always uses the source file (that is, the "merge from" file) from the last recorded merge as the common ancestor for performing three-way merges. When there is no recorded merge point, View Compare/Merge uses the most recent common ancestor. For example, if the item in the source view has the dot notation 1.9 and the item in the target view is 1.7.1.4, the most recent common ancestor is 1.7.

Back to top

Auto-merge

The View Compare/Merge Wizard has an available option called Auto-merge Files. When this option is selected in the wizard, View Compare/Merge automatically merges files without conflicting differences at the beginning of the View Compare/Merge session.

Auto-merge does a 3-way merge. The auto-merge examines the following in the merged file:

  • What is in all three files.
  • What is in the child that is in neither the ancestor nor the root.
  • What is in the root that is in neither the ancestor nor the child.

That means that it ignores lines that exist in both the child and ancestor, but not the root. It also ignores lines that exist in both the root and ancestor, but not the child. The former would be lines that have been deleted from the revision in the root view, and the latter would be lines that have been deleted from the revision in the child view.

It is possible that the merged file would be identical to the target file, even when the source and target files are different. For example:

Comparisons are made of an ancestor file foo.txt with the target (root view) foo.txt and with the source (child view) foo.txt The comparisons show that two lines in question were deleted when the ancestor revision moved to the root (target) revision, but were not deleted from the child (source) revision. Therefore these two lines were in both the ancestor and the child, but not in the root revision. In this case, the two lines in question were deleted from the root view revision. The auto-merge did not restore deleted lines.

You can perform a manual merge when you want to restore deleted lines, and you can perform an overwrite if you want the target (root) to exactly match the source (child). Even if the file is resolved with auto-merge, you can select overwrite or merge again manually.

Back to top

Commonly Used Views

Below are the most common views you will use in view comparisons and merges:

Main View

The main view is where new development eventually appears.

Activity View

The activity view is a child view used for a set of related tasks such as the development of a new feature. This view generally ends when the activity is complete.

Release View

The release view is a child view used to maintain a specific version of an application or module. This view generally ends when the corresponding application or module is no longer supported.

Back to top

Common Merge Tasks

The most common tasks associated with merging views are:

  • Allowing an activity view to catch up with new changes from its parent (Rebase).
  • Delivering a completed activity to its parent (Promote).
  • Duplicating a fix or enhancement to one or more development views (Replicate).

Back to top