This wide- and large- screen layout may not work quite right without Javascript.

Maybe enable Javascript, then try again.

Home Visual Source Safe

Branch or Pin ?

This material on VSS is an archive from fall 1998, about two decades ago. First I changed jobs so I no longer had any association with VSS. Then after a couple more years I changed careers completely so I wasn't associated with high tech at all. Then after even more years I retired altogether. I've left the VSS material on this site for use by others, even though I no longer remember exactly what it's about, or even understand some of it.

VSS continues to be used and to provide integration with other products, even though the VSS software product itself has been retired. Almost all VSS consulting services have disappeared. Microsoft Mainstream Support is no longer available for any version of VSS. And the end is near even for Microsoft Extended Support for VSS2005. As a result, roll your own support may become more important, and the experience with VSS related by these pages may turn out to be quite useful to some despite its great age.

This material reflects experience with VSS5. The user interfaces and the feature set in VSS6 were virtually identical, so almost all of this material continued to apply for several years. But I never had any detailed knowledge of the user interfaces or feature set of VSS2005, and so simply assumed most parts of this material still applied.

It often happens that a software product is released at some point, there is ongoing development for next release, and it becomes necessary to issue a patch to the released version. There should be only minimal differences between the released version and its patch; changes that have been made in the meantime in the course of ongoing development should not appear in the patch. It would also be nice --although not essential-- if the "fix" done for the patch could automatically propagate to the ongoing version since it most likely both versions have the same flaw.

It's clear that with VSS there should be two separate projects in this situation, one for the ongoing work and the other for patches to the previously released version. It's also clear some form of VSS "share" should be used, at least to initially populate the second project, and perhaps also to form an ongoing relation between the two projects. There are two mainstream methods to do this, popularly called "pin" and "branch". While the "pin" method is the one documented and recommended by Microsoft, it has its drawbacks and the "branch" method is also a contender.

To be concrete, suppose the released version is numbered 1.1.0, ongoing work is being done on what will probably be numbered 1.2.0, and it's necessary to produce a patch version numbered 1.1.1. There should be two projects in VSS, named perhaps Foo_1_1 and Foo_1_Next.

With the "pin" method, all the files under Foo_1_1 are initially just references to files under Foo_1_Next, with what VSS calls a 'pin' specifying a particular version of the file rather than the tip. The particular version chosen should be the one that was the tip back when the product was released. The patch project may have already been created when the product was released, or you can create it retrospectively when necessary. If the ongoing project has a "label" that was created when the product was released, you can display the history of the project, highlight the line for that label, and "share" the whole ongoing project to create the patch project. All the files in the patch project will be pinned at the version corresponding to the label you selected. If there is no label, you can use the VSS Command Line to create a retrospective label given a date. Then proceed as if the label had always been there.

Developers should find each file that will be affected by the fix and "branch" it. Doing this creates a separate copy of that file in the patch project, which you can then modify as necessary to make the patch without either affecting or being affected by changes made to that file in the ongoing project. This is what Microsoft best documents and suggests.

You could also "un-pin" rather than "branch" the file. Since the single file is shared between the patch project and the ongoing project, fixes you make will automatically also appear in the ongoing project. However, since an un-pinned file immediately floats up to the tip version, all changes made to that file as part of ongoing development in either the past or the future will also appear in the patch. In other words your patch may contain more changes than you bargained for. And if your software product is not carefully modularized, the changes imported from the ongoing project may depend on changes in other files that won't be touched by the fix and so won't be un-pinned, with the result that the patch project won't even compile. Although the Microsoft documentation seems to describe this method, it never explicitly recommends doing exactly this, perhaps because of the very negative side effects that sometimes result.

The alternative method is to "share and branch" the entire ongoing project to create the patch project. This creates a separate copy of every file, so there's no chance a change made for one project can accidentally appear in the other project. This is conceptually simpler. And it's operationally simpler for developers since they never have to worry about un-pinning or branching a file. Also they never have to debug problems caused by getting only part of a change. Its biggest drawback is that it takes up more disk space since there are two copies ovf every file even though most of them are identical.

Another perceived drawback of the "branch" method is it doesn't even try to propagate fixes from the patch project into the ongoing project. But this is a false dichotomy, as the "pin" method doesn't do a very good job of propagating fixes forward either. It simply isn't true that VSS can be easily set up to propagate all fixes forward, although some VSS literature seems to suggest just that. The best way to propagate fixes forward without double-entering them is with the VSS "Merge Branches" function. This takes the changes you made for a patch line by line and attempts to insert them into the ongoing version without destroying other changes that are already in the ongoing version. If VSS can do this automatically, it will. If VSS isn't sure what to do it will toss the hard decisions back to a developer with its Visual Merge.

Some VSS users feel that in this day of very large relatively inexpensive disks, the "pin" method is no longer worth the extra developer attention it requires.

Location: (N) 42.67995, (W) -70.83761
 (North America> USA> Massachusetts> Boston Metro North> Ipswich)

Email comments to Chuck Kollars
Time: UTC-5 (USA Eastern Time Zone)
 (UTC-4 summertime --"daylight saving time")

Chuck Kollars headshot Chuck Kollars' other web presences include Chuck's books and Chuck's movies.

You may also wish to look at Dad's photo album.

All content on this Personal Website (including text, photographs, audio files, and any other original works), unless otherwise noted on individual webpages, are available to anyone for re-use (reproduction, modification, derivation, distribution, etc.) for any non-commercial purpose under a Creative Commons License.