Basics of using Label, Cloak, Share, Pin, Branch and Merging

[ericsink]

Most people use only a small portion of the features of the version control system. If you use little more than checkout and checkin, you might actually be in the majority.

The "more advanced" features exist for teams and projects which are, er, more advanced. The bigger your team, the bigger your company, the more stuff you have going on, then the more powerful you want your Source Control Management (SCM) tool to be.

Even still, I've run across teams of significant size who prefer to use only the basics. The truth is that concurrent development is hard. Good SCM tools make it easier, but some people prefer to adopt processes which prevent complexity instead of using tools which help manage complexity.

But for those who dare, good version control systems offer several ways to maintain your sanity even while lots of things are going on at one time.

The most painless feature on the list is Label. Labels are conceptually very simple and are used by most teams. A label is used to mark a specific version of a file or a group of files. It is typical to apply a label when a project milestone is reached. A label is often applied when an important build is made, thus making it easier to retrieve the exact source code which corresponds to that build. In other SCM tools, labels are sometimes called "tags".

Suppose you've been working for months to deliver a beta to your customers. When you finally reach completion, you build your beta release. You want to remember exactly what the state of your repository was at the moment you reached beta, so you create a Label. You can later fetch the files from that Label and you will get the same versions you used to build your beta release.

Some processes call for the very frequent use of labels. For example, Sapient's BuildIt tool applies a label for every build it does.

Another rather painless feature on your list is Cloak. This one is actually even simpler. Cloak allows you to hide folders you don't care about. The folder is still there, but you no longer have to deal with it. For example, assume you have a big folder hierarchy. Three levels down, your marketing people placed a folder containing a whole bunch of enormous TIFF images. Developers don't want to be retrieving this stuff every time they do a get-latest operation. Luckily they can just cloak that folder and Vault will pretend it's not there. Cloak is a personal feature. When you cloak a folder, you hide it from yourself, but others can still see it.

Taking a step up the stairway of complexity we come to Share. This feature allows a folder or file to appear in multiple places in the repository. For you Unix-heads out there, Share is somewhat like a file system link.

For example, suppose your team's projects are in $/blue and another team in your company stores their work in $/red. They have a library in $/red/turboLib that you want to use, but you don't want to constantly be fetching everything else in $/red. So, you Share $/red and make it appear as $/blue/red/shares/turboLib. Now, the following two repository paths actually point to the same folder:

$/red/turboLib
$/blue/red/shares/turboLib

Any change to one of these folders will automatically appear in the other. They are not copies of each other. Rather, there is only one instance of the folder, and it simply shows up in two different places.

Note that Vault's Share command works considerably better than SourceSafe because folders can be shared, not just files. When you share a folder in SourceSafe, it just recursively shares every folder inside. If this example were done in SourceSafe, then $/blue/red/shares/turboLib would simply be a set of new folders which contain a bunch of files which are individually shared with their counterparts back in $/red/... However, the folders themselves are distinct. After the Share is created, if you add a file to $/red/turboLib, that new file will not automatically appear in $/blue/red/shares/turboLib. With Vault, the added file does appear, because the folders themselves are shared, not just the files.

Pin is handy when you have shared something but you want to freeze it. Let's say that you've been happily benefiting from the excellent efforts of the red team and you're very happy with how turboLib is working out for your project. Every time they checkin a change to turboLib, it magically becomes part of your tree as well. Suddenly one Friday, the manager of the red team decides that the fridge in their building will from now on be stocked with free beer for all the programmers. Shortly thereafter, the quality of turboLib starts going down. You are no longer quite as happy with the Share you established.

So, you bring up the Show History window and Pin $/blue/red/shares/turboLib to the version which existed on that fateful Friday. The red team can continue their "work" in $/red/turboLib, but your side of the share link will no longer automatically get their changes. It has been frozen at a Friday in the past. If you later Unpin that folder, the Share will become alive again. As long as your folder is pinned, you can't make any changes in it.

This brings us to the topic of Branching. This is the most advanced of the features mentioned here. Suppose you have a folder in which development is going on, but you want to start a second development effort using that same folder. You want the two efforts to be separate, even if you eventually want them to be one again. What you want is a branch.

Returning once again to my Share example, let's assume that after several weeks of the party life, the red team doesn't seem to be returning to normal. Pin has shielded you from their rather questionable checkins to turboLib, but now you need more. You need bugfixes in turboLib. It's time to take matters into your own hands and start maintaining your own version of turboLib. It's time to Branch.

You can branch at any version you like. In this case, you want to branch back on that freaky Friday when the red team began its decline. Those versions, the same ones you've held pinned for the last several weeks, will be the initial contents of your branch, which you create at $/blue/red/forks/turboLib.

There continues to be a relationship between $/blue/red/forks/turboLib and $/red/turboLib. They share all their history prior to that Friday. But after that Friday they diverge. Changes to one folder do not appear in the other.

Now let's say that the manager of the red team leaves and the new manager is horrified to find beer in the fridge. The beer is removed and the red team gradually regains its capacity for consecutive thought. Suddenly the red and blue versions of turboLib might seem a little too detached. The blue team has made changes which the newly coherent red team finds desirable. Similarly the red team is now beginning to improve turboLib again, leading the blue team to become interested in their new changes as well.

What these two teams need is the ability to migrate changes back and forth. This feature can go by different names. Vault and SourceSafe call it Merge Branches. The basic idea is that the user can review changes to either folder and choose to apply those changes to the other folder. The SCM tool tries to make this process as painless as possible.

Different SCM tools handle branch merging in different ways. Suffice it to say that the topic is extremely complex. A truly powerful implementation can require years of development.