Branching, Merging, Two-Way, and the like...

[andrew00]

First,

Let me say I just got the latest version of 2.0 and it is BLAZING. You guys have come so far since 1.0 - the product is working great for me. Thanks.

Now - I need some real direction on the branching/merging functionality. I have two separate questions that I need to get answered.

The first is: BEST PRACTICES

What are branching/merging best practices? I know what they were when merging was one-way, but what are they now? Before, I was told that your trunk was your main development folder, where all of the development code actually lived. Branched were like, previous versions - all changes made in branches eventually get merged into the trunk. Thus, you could merge code from branches to the trunk, but (at the time) not the other way around.

Let me give you my situation, and perhaps someone can tell me best practices. I have a product, and we have clients for that product - each client has a customized implementation of that product. So my tree sorta looks like:

$/
/MainProduct

/Client1
/Client2
/Client3

When I make changes to the main product - let's say, a bug fix in some core code - , I always need to merge them out to the clients. I never need to merge changes from the clients back to the main product.

Given this scenario, what are best practices for me? Is this the right way for me to be storing my folders? Will I run into any issues?

Second question: MERGING

You all mentioned Araxis Merge, and the ability for Vault to work with other merge utilities. I think I'm missing something here. If we could have used Araxis before, then why build it into Vault? In other words, what does it mean that Vault natively supports bi-directional merge, what does the merge utility do NOW that an external one wouldn't have done 3 months ago? Is there some way that Vault is able to interact with the utility to give it (or store) more information? If so, how, and what info? I want to make sure I understand what I'm doing when I do a folder merge, and I think I may be missing something.

Any help would be appreciated.

Thanks,
Andrew

[dan]

Thanks for the encouragement. We like Vault too

Answers to your questions:

1. The structure you have looks fine, as long as ClientX remains a peer of or outside MainProduct (e.g., ClientX should never be underneath MainProduct). The new MergeBranches command should work well for you - choose MainProduct as the origin, and ClientX as the target, and then choose which two versions of MainProduct for which to apply changes to ClientX. However, in your situation, you'll need to do this for each 'Client' folder.

2. I think you are confusing individual file merges with entire tree merges. The MergeBranches command works to move changes from one entire tree to another. It determines which files need to have changes moved to their counterparts in the other branch.

The Araxis and other 3rd party merge tools that we now allow are for merging changes into individual files. This can happen after a Merge Branches operation (for example, when there were conflicts when trying to apply the changes), or just during regular checkouts and checkins, when someone else checks in in a change while you were modifying the same file yourself. In those cases, you can invoke Show Merge to bring up a file merge tool (either our internal one, or a 3rd party tool) to help you resolve the changes.

One other note for the latter case is that doing a Get will resolve a merge if it can (and if your options are set that way), and most of the time you don't have to manually apply changes from other users - Get can do it for you.

[ericsink]

You all mentioned Araxis Merge, and the ability for Vault to work with other merge utilities. I think I'm missing something here. If we could have used Araxis before, then why build it into Vault? In other words, what does it mean that Vault natively supports bi-directional merge, what does the merge utility do NOW that an external one wouldn't have done 3 months ago? Is there some way that Vault is able to interact with the utility to give it (or store) more information? If so, how, and what info? I want to make sure I understand what I'm doing when I do a folder merge, and I think I may be missing something.

I want to respond to the portion of your note quoted above. I may be able to clarify a few things.

First of all, let's distinguish between the somewhat different meanings for the word "merge".

We sometimes use the word merge to refer to the 3-way combination of 3 versions of a single file. I often distinguish this by calling it "file-level merge".

Alternatively, we sometimes use the word merge for the larger operation of merging the changes from an entire folder into another folder. This is the operation which Vault calls Merge Branches. Essentially, this operation will usually end up involving several or many "file-level merges", but it also includes the ability to migrate other operations like file additions, deletions, renames, and so on.

OK, let's talk about the merge branches case first. Prior to 2.0, the ability to merge branches was very limited. Vault 1.x could only merge changes from a branch back into its trunk.

As a workaround, we suggested that people could use Araxis Merge to do their merging. However, this approach simply involved using Araxis as a very advanced file editor. Vault didn't support any particular integration with Araxis Merge or any other such utility.

For the merge branches case, this is still true. Outside of the Vault environment, you can use any tool you want to edit your files or migrate changes from one file to another. Just use Vault to retrieve all the necessary versions of your tree to your local disk, and then use the other tool's particular features as needed. Vault can't tell the difference between a working file which was edited by a text editor and one which was modified by Araxis.

But as of Vault 2.0, the built-in merge branches capability is much improved. There is no particular reason to use an external tool like Araxis for merging of branches anymore. Not only is Araxis Merge rather expensive, it cannot take advantage of special information known by Vault because it is a general-purpose merge tool. For example, our built-in merge branches feature can detect a file rename because it knows the history of what happened. An external merge tool can do nothing but look at the versions on the disk and see the differences between them.

Now, let's talk about the other case, file-level merge. As I mentioned above, this operation is just one of the several things that can happen as part of a larger merge branches operation. Alternatively, this case can happen completely outside the merge branches feature. Anytime a file ends up with a status of Needs Merge, you have a file-level merge operation which needs to be addressed. Files end up with this status when two people edit the same file at the same time.

The file-level merge breaks down further into two distinct cases. First, there is "automatic merge". This is what happens when you tell Vault to attempt an automatic merge when retrieving files from the server. Behind the scenes, Vault will grab all three versions of the file and try to reconcile them based on the context surrounding each change. If this can be done safely, then the merge will be performed automatically. Note that this feature can be turned off for those who are not comfortable having their version control tool perform this kind of magic.

The other case of file-level merge is the notion of an interactive tool which allows the user to see the various changes and decide how the merge should be resolved. Prior to 2.0, Vault had a built-in Show Merge dialog. In fact, Vault 1.x was unable to interact with any external merge apps at all. You had to use the built-in Show Merge dialog, and it was actually rather lame.

Vault 2.0 improves this situation considerably. First of all, Vault 2.0 now allows the user to specify an external merge application for file-level merge. This allows people who prefer tools like Araxis or Guiffy to continue using them. Second, Vault 2.0 now ships an external merge application of our own. It is called SourceGear DiffMerge, and we are rather pleased with how it turned out. The old Show Merge dialog from 1.x is now gone, and the new DiffMerge application is a big improvement in several ways.

I hope this brings some clarity. Reply here if I can answer any further questions on this matter.