Merge History

Merge History

Note: This is draft documentation for the Team Foundation Server SP1 Beta. The contents of this article should not be considered as final.  All feedback is welcome.

Introduction

New APIs now provide the information from the server that you need to build tools to track the flow of changes through branches.  This was not possible with the QueryMerges method. The QueryMerges method provided summary merge history information that could only approximate the merge history.  SP1 includes a new object model API that gives you the detailed information.  The new QueryMergesWithDetails method is in the Microsoft.TeamFoundation.VersionControl.Client namespace.

The QueryMergesWithDetails method is called with the same parameters as the QueryMerges method, but with two additional parameters to specify deleted items in a changeset. In contrast, the QueryMerges method does not let you specify a deletion ID as an item.

This is the QueryMergesWithDetails method signature:

public ChangesetMergeDetails QueryMergesWithDetails(

      string sourcePath,

      VersionSpec sourceVersion,

      int sourceDeletionId, // NEW

      string targetPath,

      VersionSpec targetVersion,

      int targetDeletionId, // NEW

      VersionSpec versionFrom,

      VersionSpec versionTo,

      RecursionType recursion

);

The new QueryMergesWithDetails method is similar to the QueryMerges method, with two significant differences. The new method can return merge details from deleted items. Also, it returns an array of ChangesetMergeDetails instead of a ChangesetMerge objects.

The ChangesetMergeDetails object contains distinct arrays for merged and unmerged items.  In contrast, the ChangesetMerge returned by the QueryMerges method has a Boolean property that shows whether all items were merged. However, it does not list the state of each item.

public sealed class ChangesetMergeDetails

{

      public ItemMerge[] MergedItems { get; }

      public ItemMerge[] UnmergedItems { get; }

}

The properties in the ItemMerge class are similar to the ChangesetMerge properties, but the additional SourceItemId and TargetItemId properties can simplify the code by allowing methods to be called with item IDs rather than with paths.

public sealed class ItemMerge

{

      public int SourceItemId { get; }

      public string SourceServerItem { get; }

      public int SourceVersionFrom { get; }

      public int TargetItemId { get; }

      public string TargetServerItem { get; }

      public int TargetVersionFrom { get; }

}