I wonder if you could provide a KB article to explain what happens when you add a solution.
The dialog box that pops up when you right-click a solution and select "add to source control" has the following items:
1) "Vault Folder" - seems to default to the solution name.
2) "Choose folder" - seems to just be an echo of whatever is currently selected in the tree
3) The folder tree in the current Vault repository
4) The working folder.
I've noticed that these 4 elements (well, 3 degrees of freedom) conspire in some way to generate the resulting location of the solution within Vault. Having experienced situations where I tried to add my solution to what I thought was the right location, only to end up accidentally with it somewhere like
$/Foo/Bar/Foo/Bar/bar.sln,
it'd be great if you guys could provide a clear, definitive information of how to predict where the solution will end up, based on what is in these four boxes in the "add solution" dialog box.
TIA.
dev team - please clarify how adding solutions works
Moderator: SourceGear
Choose folder is where the solution/project will be placed in vault.
You can change it by selecting a different node in the tree, and also by changing the "Vault Folder" textbox (you may notice if that when you change the node selected or the "Vault Folder" textbox, it changes the value of Choose Folder, which you can't change).
Visual Studio may create subfolders underneath that, depending on whether you are adding a solution or a project, but Vault doesn't have any control over that.
Working folder is where the files are physically located on your local disk. Since they already exist there when you add the solution/project, you can't change it from here.
You can change it by selecting a different node in the tree, and also by changing the "Vault Folder" textbox (you may notice if that when you change the node selected or the "Vault Folder" textbox, it changes the value of Choose Folder, which you can't change).
Visual Studio may create subfolders underneath that, depending on whether you are adding a solution or a project, but Vault doesn't have any control over that.
Working folder is where the files are physically located on your local disk. Since they already exist there when you add the solution/project, you can't change it from here.
I've been there too...
I feel your pain.... Really I do. I have just finished (about 5 minutes ago) adding all of my own source code to Vault and, like you, have gone through a little bit of hell in the process.
Not to put the SourceGear people down, but their excuse of "it's VS doing it, not Vault, so don't ask us" does not cut it at all. Sorry SourceGear, but saying this is rather lame, taking into consideration that source code is extremely valuable to us and we are relying on Vault to safeguard it.
Here is some of what I wished Vault documentation would say about VS and adding pre-existing solutions and projects to Vault:
- First and foremost: Backup your original files before adding anything to Vault. This is not because anything will be deleted, but because files will be changed to reflect that they are now under source control. Getting the files back to "non-source control" settings to undo anything is hard to do.
- Many file and directory arrangements that are "legal" under non-source-controlled Visual Studio are illegal when you add your project/solution to source control. Visual Studio will gladly make decisions for you and restructure your directories to force the structure to comply with source controlled directory rules. The easiest way to undo this is to delete the files from source control, restore a backup to the local hard disk, fix the problem, back up again, and re-add to source control.
- Immediately after adding a project to source control (Vault), check the directory structure created with the Vault client. There may be many different changes to the structure than with what you started, or what you intended.
- Make sure all the projects referenced by your solution are at a directory at or below your .sln file. If you have outside projects, Visual Studio (not Vault), may recreate the whole subdirectory structure in the source control tree under the .sln file. This may result in some projects being put into source control seevral times in several locations (if, for example, you have a common library added into several solutions and the library is under a different subdirectory tree than the rest of your solution), defeating one of the major purposes of version control.
- Regard every addition of a project/workspace into Vault as "experimental" and double-check that the project was added with the intended directory structure.
Anyway, my inclusion of my projects into Vault was not "a breeze" in any way, but eventually I did end up with what I wanted.
I would recommend you experiment and definitely re-arrange your files before you even try to put them under source control. In the process of adding my projects and solutions to source control I got really good at editing solution and project files with Notepad to make re-arrangement much easier than through the VS IDE.
I still think that SourceGear should provide some walk-through or reference to Microsoft documents (if they exist) that deal with this issue. At the very least, there should be a strong warning that strange things may happen. I wasted about 2 full days making mistakes and recovering from them. I had so much trash in source control that I deleted and recreated the whole repository once, too.
Ending up with weird and redundant directories created by Visual Studio in the source control when I added a project to Vault was, to say the least, surprising.
Not to put the SourceGear people down, but their excuse of "it's VS doing it, not Vault, so don't ask us" does not cut it at all. Sorry SourceGear, but saying this is rather lame, taking into consideration that source code is extremely valuable to us and we are relying on Vault to safeguard it.
Here is some of what I wished Vault documentation would say about VS and adding pre-existing solutions and projects to Vault:
- First and foremost: Backup your original files before adding anything to Vault. This is not because anything will be deleted, but because files will be changed to reflect that they are now under source control. Getting the files back to "non-source control" settings to undo anything is hard to do.
- Many file and directory arrangements that are "legal" under non-source-controlled Visual Studio are illegal when you add your project/solution to source control. Visual Studio will gladly make decisions for you and restructure your directories to force the structure to comply with source controlled directory rules. The easiest way to undo this is to delete the files from source control, restore a backup to the local hard disk, fix the problem, back up again, and re-add to source control.
- Immediately after adding a project to source control (Vault), check the directory structure created with the Vault client. There may be many different changes to the structure than with what you started, or what you intended.
- Make sure all the projects referenced by your solution are at a directory at or below your .sln file. If you have outside projects, Visual Studio (not Vault), may recreate the whole subdirectory structure in the source control tree under the .sln file. This may result in some projects being put into source control seevral times in several locations (if, for example, you have a common library added into several solutions and the library is under a different subdirectory tree than the rest of your solution), defeating one of the major purposes of version control.
- Regard every addition of a project/workspace into Vault as "experimental" and double-check that the project was added with the intended directory structure.
Anyway, my inclusion of my projects into Vault was not "a breeze" in any way, but eventually I did end up with what I wanted.
I would recommend you experiment and definitely re-arrange your files before you even try to put them under source control. In the process of adding my projects and solutions to source control I got really good at editing solution and project files with Notepad to make re-arrangement much easier than through the VS IDE.
I still think that SourceGear should provide some walk-through or reference to Microsoft documents (if they exist) that deal with this issue. At the very least, there should be a strong warning that strange things may happen. I wasted about 2 full days making mistakes and recovering from them. I had so much trash in source control that I deleted and recreated the whole repository once, too.
Ending up with weird and redundant directories created by Visual Studio in the source control when I added a project to Vault was, to say the least, surprising.
gabriel magana-gonzalez
Thanks for the writeup here Gabriel - lots of good advice for everyone. 
We created this forum precisely so our users could share valuable information with each other on how to use and setup Vault.
It is true that we don't have a write up on how to setup Visual Studio projects to work specifically with Vault. However, since VS works the same with all source control backends, there are some microsoft support articles that are helpful: Try
http://msdn.microsoft.com/library/defau ... dlg_rm.asp
or specifically:
http://msdn.microsoft.com/library/defau ... lg_ch3.asp
Also, it really is the case that we don't control how Visual Studio, or any other IDE for that matter, decides where to put projects into the source control provider. We have to put source files where the client tells us to, and in this case, it is the IDE that tells us what to create, and where to put the files. Subverting that would not be wise, since the IDE (and all users) expect the controlled source to be where they put it. In this case, however, Visual Studio is between you and Vault, and unfortunately, once you choose a top level Vault node, it decides the rest. I know this seems like a copout, but the only way to have complete control over where your files reside in Vault is to not use VS SCC integration at all (and just do source control through the Vault GUI client), since all scc providers have to create what VS tells us to.
I do have 2 questions for you:
1. Where would you have expected to find a write up like this? Or, where would you have looked for it before attempting to add projects through the IDE? This would help us understand where information like this should go in the future.
2. Do you mind if we take the meat of your writeup, and add it as a knowledge base article on this forum (and of course attribute the write up to you). People might look for this info in the knowledge base more than in a support thread.
Again, we do appreciate your input, and especially the warnings/advice on how users should approach IDE integration. Thanks for taking the time to write it up.
We created this forum precisely so our users could share valuable information with each other on how to use and setup Vault.It is true that we don't have a write up on how to setup Visual Studio projects to work specifically with Vault. However, since VS works the same with all source control backends, there are some microsoft support articles that are helpful: Try
http://msdn.microsoft.com/library/defau ... dlg_rm.asp
or specifically:
http://msdn.microsoft.com/library/defau ... lg_ch3.asp
Also, it really is the case that we don't control how Visual Studio, or any other IDE for that matter, decides where to put projects into the source control provider. We have to put source files where the client tells us to, and in this case, it is the IDE that tells us what to create, and where to put the files. Subverting that would not be wise, since the IDE (and all users) expect the controlled source to be where they put it. In this case, however, Visual Studio is between you and Vault, and unfortunately, once you choose a top level Vault node, it decides the rest. I know this seems like a copout, but the only way to have complete control over where your files reside in Vault is to not use VS SCC integration at all (and just do source control through the Vault GUI client), since all scc providers have to create what VS tells us to.
I do have 2 questions for you:
1. Where would you have expected to find a write up like this? Or, where would you have looked for it before attempting to add projects through the IDE? This would help us understand where information like this should go in the future.
2. Do you mind if we take the meat of your writeup, and add it as a knowledge base article on this forum (and of course attribute the write up to you). People might look for this info in the knowledge base more than in a support thread.
Again, we do appreciate your input, and especially the warnings/advice on how users should approach IDE integration. Thanks for taking the time to write it up.
-
Guest
Dan - there's a cartoon I like where a bunch of little aliens are looking at some complex system layout on a whiteboard. In the middle of the system there's a box labelled simply, "a miracle happens here". One of the aliens is pointing to it and saying, "I think we need a little more detail right here."dan wrote:Visual Studio may create subfolders underneath that, depending on whether you are adding a solution or a project, but Vault doesn't have any control over that.
That's the feeling I'm getting with this whole "adding solutions to Vault" thing. I know a lot of this is due to the clunky integration API provided by Visual Studio, and the idiosyncracies of how and where Visual Studio creates projects, and that there's not much you can do about that until Microsoft fixes it.
HOWEVER it would be a huge service to those of us in the Vault community for the documentation to lay out exactly what happens when adding solutions to Vault using IDE integration. (FTR - I was against using integration altogether - I'd rather use the Vault Client for everything, which is much more predictable. I got outvoted
)Like the above poster, I spent a very frustrating couple of days trying to get (a) the integration to work for a particular solution and (b) to get the folder hierarchy in Vault to be what I wanted it to be.
I've scoured the Microsoft knowledgebase for definitive answers as to how this works - I've read all their "team development using VS .NET" type whitepapers, but they don't give any useful info.
Another strange behavior I've noticed: at some apparently random times, the VS integration will "fix" the working folder for subprojects within Vault. Normally I'd like to only define the working folder for the topmost project, and have all the subprojects inherit and derive theirs from it. However, under certain circumstances (haven't figured out exactly when) I suddenly see the sub projects have their own, non-inherited subfolder. This causes no end of grief when getting projects from source control - they often don't end up where you expect locally. Is this a bug, by design, or unavoidable with the current version of Visual Studio? (I'm using VS .NET 2003)
By the way - thanks to the Sourcegear team for the free support provided on these forums - I know you guys are doing this on your own time, or at least not getting any extra remuneration for it. The fact that the community support is so strong was a big factor in our decision to go with Vault.
Well, thanks for having the forums, definitely it's a great way to share info. Sorry if I had an "attitude" when I wrote what I did, the experience was exasperating.Thanks for the writeup here Gabriel - lots of good advice for everyone.
Perhaps a chapter in the help files? With so many different types of projects that you could integrate from VS.NET alone (never mind the older versions of VS), you could certainly fill a chapter.1. Where would you have expected to find a write up like this?
Or how about a warning that can be turned off that gets displayed then you try to add anything to source control from the VS IDE? Those who "don't need no stinkin' manual" (of course, I'm not in that group
) would get fair warning that they are walking into a minefield.I would not mind at all, but I would not put it up verbatim... What I wrote was very "foggy," not on purpose, but because I am still unclear on what exactly VS does when adding non-trivial solutions/projects to source control.2. Do you mind if we take the meat of your writeup, and add it as a knowledge base article on this forum (and of course attribute the write up to you).
For example, I ended up modifying by hand the "install project" project files to reference local (in the same directory as the project file) files rather than their original locations (for example, I originally had .ico files in a totally separate directory from the source code). So I do not know if that was the wisest thing to do, specially given that some of these file are binary and maybe should not be in source control?
So my point is that maybe Sourcegear should start a mini-project to better document this whole issue, as it is for sure not a simple explanation overall. Definitely what I wrote is not an exhaustive explanation. I mean, I could add the projects to Vault, but who knows later I might have forgotten a file? But feel free to use anything I wrote if it may help.
Since you asked (:-)), you may want to do create an introductory section where "base rules" are specified. Base rules might go something like this:
- Before adding to source contrrol, restructure your projects in the directory hierarchy you intend to use in source control.
- Backup your projects before you add them into source control.
- Always verify the added files/directories through the Vault client after adding projects.
- VS.NET changes the working folder settings to hide or mask the changes it made to the true directory structure of your projects/solutions. Do not assume that your source control projects are arranged in the same hierarchy as your working folders.
And then you could go into detail about .sln file issues, then walk through each kind of project that you can have and the source control issues for that specific kind of project.
Thanks for paying attention to this. Rest assured there are going to be lots of people asking the same questions, given how VS butchers the paths and then covers up for itself by modifying the working folders to give the impression that nothing happened.
gabriel magana-gonzalez