Merging from a VersionSpec in TFS: VersionSpec.Latest does not work as expected

Question

I have created a utility in TFS to enumerate the changes and conflicts from a source branch to a target branch. I would like to optionally include a VersionSpec for the source branch. However, when I supply the default VersionSpec as shown below, I do not get what is expected. I have used the GUI to do the merge and it shows 19 changes with zero conflicts. But in the TFS API it tells me that there are no changes if I use a VersionSpec as shown.

VersionSpec spec = VersionSpec.ParseSingleSpec("T", null)
mergeStatus = workspace.Merge(ServerSourcePath, ServerTargetPath, spec, null, LockLevel.None, RecursionType.Full, MergeOptions.None);
//mergeStatus.noActionNeeded returns TRUE

//OK now try another method
spec = VersionSpec.Latest
mergeStatus = workspace.Merge(ServerSourcePath, ServerTargetPath, spec, null, LockLevel.None, RecursionType.Full, MergeOptions.None);
//mergeStatus.noActionNeeded returns TRUE again

//But if I try using null instead of a VersionSpec....
mergeStatus = workspace.Merge(ServerSourcePath, ServerTargetPath, null, null, LockLevel.None, RecursionType.Full, MergeOptions.None);
//mergeStatus.noActionNeeded returns FALSE, and I am able to see all 19 changes

So why is it that null works correctly here, but the other two methods do not? While I do intend to use null for this scenario, the lack of reliability of the other method makes me suspect that I cannot trust the results of any VersionSpec, such as a LabelVersionSpec. I believe I may already have seen some suspect results when testing this using the LabelVersionSpec, so I need to understand if there is a reason for the discrepancy that I need to account for.

Answer 1

Due to Microsoft's usual lack of thorough documentation I misunderstood the fromVersion and toVersion parameters to mean sourceVersion and targetVersion (merging "from" one branch "to" another branch), respectively, though I did wonder what would be the use case would be around having a VersionSpec in the target branch, since you would always be applying it to the Tip. As it turns out, it seems that the fromVersion and toVersion are there to select a subset of changesets, so in the code above, the VersionSpec spec variable should be used in the toVersion argument, not a fromVersion. fromVersion = null would imply that the merge should go back to the initial changeset in the branch (or the last recorded merge, presumably), whereas toVersion = null would imply that the merge should use everything up to the Tip/most recent changeset.

Updated code:

VersionSpec spec = VersionSpec.ParseSingleSpec("T", null)
mergeStatus = workspace.Merge(ServerSourcePath, ServerTargetPath, null, spec, LockLevel.None, RecursionType.Full, MergeOptions.None);
//mergeStatus.noActionNeeded returns FALSE

//OK now try another method
spec = VersionSpec.Latest
mergeStatus = workspace.Merge(ServerSourcePath, ServerTargetPath, null, spec, LockLevel.None, RecursionType.Full, MergeOptions.None);
//mergeStatus.noActionNeeded returns FALSE again

//And if I try using null instead of a VersionSpec....
mergeStatus = workspace.Merge(ServerSourcePath, ServerTargetPath, null, null, LockLevel.None, RecursionType.Full, MergeOptions.None);
//mergeStatus.noActionNeeded returns FALSE