Merge Explanation

[Balthazor]

It would be much appreciated if I could get a concise explanation of how exactly the Merge functionality works. I just had a situation here where resolving the merge status on a Visual Basic module resulted in all my code changes being lost. I have no idea how this happened, since I lack a clear understanding of just what goes on during the merge.

The specific questions I have are how does Vault determine that a merge is necessary? Or, in other words, what is the determining factor between a status of Needs Merge and a status of Edited.

My second question is what goes on during the Resolve Merge Status process. How does Vault determine which file changes are to be made to the repository file and which are not? And finally, how do the local cache files factor into all of this?

It is very important to me, and to the company I represent, that the local code file we are attempting to check in is exactly what is saved to the repository. We cannot have the code being changed behind the scenes, at least not without a clear understanding of the process. If someone could shed some light on this process for me, it would be of great help.

[ericsink]

When you get a file from the repository to your local machine, Vault remembers which version you retrieved, and it keeps track of whether you have edited the file or not.

If you have edited your local copy of the file and there is not a new version of that file on the server, then the status of your file will be Edited.

However, if you have edited your local copy of the file but the file has also been edited by someone else, and thus there is a newer version on the server, then the status of your file will be Needs Merge.

Vault will not allow you to checkin a file if your modifications to that file were not based on the most recent version of that file. So, in order to checkin the file, you must "merge" the newest changes from the repository into your local copy.

Resolve Merge Status tells Vault that you have completed the merge. It does not modify the local working file. Rather, it updates Vault's records to indicate that your local working file is based on the most recent version of the file.

A few paragraphs ago I said that when you get a file from the repository, Vault remembers which version you retrieved. This is your "baseline", the base version from which you started editing. Your file is in Needs Merge status if you have edited the working file and the baseline is no longer current.

For example, suppose you grab version 7 of foo.c. You make some edits. Meanwhile, I grab version 7 of foo.c, make some edits, and check it in. Now the current version of foo.c on the repository is 8, but your edited copy was based on version 7 (your baseline for this file is 7). So your file status is Needs Merge. Before you can checkin your file, you have to merge the changes I made in version 8 into your working file, then use the Resolve Merge Status command to assure Vault that you have done it.

In many cases, Vault's automerge feature will correctly perform this merge for you. In cases where it cannot, you will need to manually edit the file to reflect both your changes and the delta from version 7 to 8.

None of this attempts to address what went wrong in your case. I am curious about that, as the merge feature of Vault is known to be extremely reliable. Nonetheless, I do not doubt what you say. Something went wrong, and if possible, I would like to figure that out.

Chapters 2 and 3 of my Source Control HOWTO might be worth reading for additional background:

http://software.ericsink.com/scm/scm_checkins.html

http://software.ericsink.com/scm/scm_file_merge.html

[GregM]

This is what you are telling Vault to do using these two functions:

Show Merge = Merge changes from the repository to my local copy,

Resolve Merge Status = I already merged changes from the repository to my local copy, forget that there was a problem.

You usually want Show Merge, not Resolve Merge Status.

Using Resolve Merge Status instead of Show Merge would cause you to lose the latest changes from the repository, not your own edits. Is that what happened?

[Balthazor]

Thanks for the quick reply!

I skimmed through the HOWTO a bit, and I'll read it more closely when I get time. In the meantime, I've got a couple more questions related to your response. First, is the baseline related to the local cache files that Vault retrieves? If so, then what happens if those cache files are deleted while I've got some code files checked out?

I've also noticed a setting in the Diff/Merge Options which toggles between "Diff against last version retrieved from repository" and "Diff against current version in repository". Does this have any impact on merge status?

I'm not sure what happened during the merge I described, and it may well have been something I did wrong. Which is why I'm trying to find out more about the merge, so that if I did do something wrong, I won't do it again.

But I'm also wondering if there's a means by which to effectively disable the merge functionality altogether. We don't do any kind of concurrent editing of code here. The way we do things, the only person who should be editing code is the person who's got an exclusive check-out on that code. There should never be a situation where two people are editing the same code at the same time. That would be bad. What we need here is what you refer to as the "checkout-edit-checkin doctrine" in the HOWTO. We need to ensure that whatever file I'm trying to check in is exactly what's saved to the repository, regardless of what it's baseline version is or what might have been done with that file by another user. Can we do that?

[ericsink]

First, is the baseline related to the local cache files that Vault retrieves? If so, then what happens if those cache files are deleted while I've got some code files checked out?

Vault client does keep cached copies of specific versions of files, including the baseline. I doubt it is a good idea to delete those cached files. If you delete them, Vault will probably just refetch them when it needs them, but I cannot say for certain that this behavior applies to all circumstances.

I've also noticed a setting in the Diff/Merge Options which toggles between "Diff against last version retrieved from repository" and "Diff against current version in repository". Does this have any impact on merge status?

No, this has no impact on the file status. This merely tells Vault how to behave when you use the Show Differences command to view the diffs for your current working file.

But I'm also wondering if there's a means by which to effectively disable the merge functionality altogether.

Yes. Under the Tools menu, select Options, and go to the page called Concurrent Development Style. Click the button for VSS style.

Note that "VSS mode" is the default behavior for Vault. If you are not already in VSS mode, it would seem that perhaps you intentionally changed your settings?

[Balthazor]

Vault client does keep cached copies of specific versions of files, including the baseline. I doubt it is a good idea to delete those cached files. If you delete them, Vault will probably just refetch them when it needs them, but I cannot say for certain that this behavior applies to all circumstances.

So, I take it that setting the local cache folder to be the Recycle Bin wouldn't be a good idea?

We do occasionally delete these cached files, since it seems that the local cache grows pretty big, pretty quick. One guy here, a while back, realized he had over 9 GB of Vault cache files on his machine. It was eating up so much of his hard drive space that his machine wouldn't boot. So it seems necessary to clear out those cache files from time to time.

Now, if it's a bad idea to delete those files while something is checked out, then I could warn the folks here not to do that. But since these cache files appear to never actually go away, even after a file check-in, we can't really let them accumulate forever.

Yes. Under the Tools menu, select Options, and go to the page called Concurrent Development Style. Click the button for VSS style.

Note that "VSS mode" is the default behavior for Vault. If you are not already in VSS mode, it would seem that perhaps you intentionally changed your settings?

It's entirely possible. I'm one of a couple of guys here who've been implementing the Vault software, so we've been experimenting with the different settings. But since this is a setting at the client level and not the server level, what would happen if two users had it set up differently, one using the VSS style settings and the other using the CVS style?

[ericsink]

We really need to provide a feature to manage the disk space used by those cache files. I agree that they can't just accumulate forever. I still think it is probably safe to delete them, but I also wouldn't be shocked if we discovered that doing so causes some kind of a problem.

Different people can use different settings for CVS or VSS style. These settings control the way the client behaves, not the server. Exclusive locks get honored, no matter what style you are in.

[davidt]

I see that in the Admin tool, under Repository Options, there is an option for Require Exclusive Locks. This should help enforce the policy you're looking for.

[Balthazor]

There's one thing which still baffles me. There are a variety of code files I work with that nobody besides me ever edits. When I need to make an edit, I use the Vault client to check out all the code, then I make the necessary edits in Visual Studio. When I'm done, I go back into the Vault client and check in all the files. Every single time I do this, I end up with at least a couple files which show a status of Needs Merge.

I'm absolutely certain that nobody else has edited any of these files during this timeframe, since not only does nobody else have a need to edit them, but I'll have all the files with an exclusive checkout. Yet something routinely causes them to get a Needs Merge status. This is why I wondered if deleting those local cache files may play into this, since that's about the only thing that would make any sense.

Finally, I've got one further question. Based on what's been said earlier, am I right in thinking that the Resolve Merge Status function is basically saying "skip merge" or "don't bother merging"? In other words, it saves the working file to the repository, overwriting whatever the current respository version is. Is that correct?

If so, then that pretty much would solve my problems, since the local working file is always going to be what I need to save. So I'd be good just choosing Resolve Merge status whenever the Needs Merge status pops up.

[GregM]

I've had files end up in "Needs Merge" when something was locking the local file during the check-in, so Vault couldn't overwrite it with the latest file in Vault.

Yes, "Resolve Merge Status" means "I've already merged it manually."

[Guest]

As an experiment, I checked out a file and edited it. The status shown in the Vault client changed to Edited. While the file was still checked out, I deleted the local cache folder. The file status immediately changed to Needs Merge. In light of that, it does appear that deleting the local cache while files are checked out probably isn't a good idea.

[Balthazor]

Oops. That last post was mine. Seems I wasn't logged in.

[dan]

What happens when you delete the cache is that the file status really becomes "Unknown", meaning it doesn't have a baseline file for it (meaning it doesn't know which version of the file you started with in that working folder).

But, the the client tries to recover from this by checking whether there are any versions of the file on the server that match it. Since you edited the file, there are no matching server versions, so it simply assigns the first version of the file as the baseline, which causes it to go to Needs Merge. Then it is up to you to manually determine that this is the file you want checked in on top of the server version the next time you check it in.

Hope that makes sense. Short answer is that yes, deleting the client cache is bad, but the client tries to recover anyway.

[Balthazor]

Yes, that does make sense. And I think I finally have all the information I need. Basically, that we don't want to delete the local cache while we have something checked out and edited. And that if a Needs Merge status arises, that we should do the Resolve Merge Status rather than actually try to perform the merge. That should work for us, and it calms my fears.

Thanks for the help!

[dan]

The only caveat I would have is to always do a Show Diff against the current repository version when the file is Needs Merge, just to verify that the changes you are checking in are the ones you made, and that you are not wiping out someone else changes (in the unlikely chance that you didn't check the file out exclusively and someone else checked in a file while you had it checked out).