Wednesday, April 16, 2008

Managing Branching in VSS

A good article that provides a step by step approach on how to do branching in Visual SourceSafe can be found here.

The article is as follows:
The official Microsoft word on branching projects is '132923 Sharing SourceSafe Projects'. It's on the lean side. I've added some more meat that hopefully will help you through the trauma of your first attempt at branching projects.

branching projects

You and i might think it logical to start by specifying the source tree so that the software could check that such a thing actually exists and, gathering confidence as we go, move on to specify where we want to put the new tree. That's being too logical.. The actual sequence of events is ...

1-Destination Project Root | 2-Source Project Name | 3-Destination Project Name

1. click on the project UNDER WHICH the DESTINATION project tree is to be created. In this case we'll suppose we want to create the replicated tree off the root so select $/

2. Right click on $/ and click again on 'Share' on the menu.

3. On the 'Share with' dialog Select the head of the SOURCE project tree you want to branch. In this case select project Word 1.

You may want to check the [] Branch after Share checkbox, but for now just let's defer that. The dialogs we're trekking through are very un-intuitive. I'll get to the effect of checking that later.

4. Click the [Share] button

5.Now we're in a second 'Share $/Word1' dialog.

The system doesn't know what the name of the DESTINATION project tree is to be at this point. All it knows is that it's going to hang it off of the project you specified in 1. above.

In the 'New Name' field enter the name for the head of the DESTINATION project tree. In this case, since we're creating the DESTINATION project as a peer of $/Word 1 it can't have the same name, so let's call it Client2. However all the child projects will retain their original names.

6. Now IMPORTANT! check the [Recursive] box or all we'll get is $/Client2!

Enter in the comment box

'I have lead a clean life, and I have backed up the database,
and made sure I have at LEAST double the free space the current database takes up,
and I have run analyze in the hope it will clean up the deleted files and any
and all broken links in the tree
and I truly believe that SourceSafe will recurse over the thousands of projects
and files in the tree I want to branch without breaking and leaving a gawdawful mess.
I do. I do. I do.'

Lastly place chicken entrails or rabbits foot to taste on the keyboard and

7. click on [Ok].

If and when the Status bar shows 'Ready' Click [Close] to exit the 'Share with ..' dialog. And go and have a cold one. You deserve it.
The Small Print

  • If you think that this dialog sequence is .. awkward .. imho you'd be right.
  • If you want to place the destination tree somewhere in the tree where it's not a peer to the source tree then the head source and destination names can be the same as there won't be a conflict.
  • Don't specify a destination tree that overlaps with the source tree or you'll get "A project cannot be shared under a descendent" messages indicating that you're trying to do illegal recursion.
  • Selecting the 'branch after share' checkbox has this effect:

If NOT SELECTED you'll see double document icons in the Client2 tree indicating that file appearances in the Word and Client2 trees are still only backed by one physical file in SourceSafe, so changes to one appear in both.

If SELECTED you'll see single document icons in the client2 tree indicating that each file is now backed by it's own physical file (the Client2 files were copied from the Word files which is why you made sure you have plenty of free disc space to accomodate the growth in the database size).


If you want to refine the torture your brain has already endured, and assuming that you elected the 'Branch after Share' checkbox, then you might want to consider pinning.

In this case the files in the Client2 branched project tree have a separate history from now on, and can be modified at will without affecting the corresponding files in the the Word tree.

However it's quite likely that you don't want some, perhaps most, of the files in the branched tree to be changed, and you want to lock those down so they stay the same as the originals.

The SourceSafe term for locking them 'Pinning'.

This is really a separate topic, but if you want to dip a toe in start here


There's a good writup on Branching in Larry Whipple's excellent book 'Essential Sourcesafe'.

You'll find a link to it on the 'SourceSafe Third Party Tools' page.

When you do get to it click on the 'Search inside this book' link under the jacket image. When you get the next page scroll up the page to uncover 'Search [Inside this book]. Finally select the 'on Page 51' link.

I say this not to do Larry out of his royalties but to encourage you to try and buy the book. If you're a professional SourceSafe administrator i'd say it's pretty well ... essential.

No comments: