Beyond CheckOut and CheckIn
Many 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. A Vault user recently asked me to
explain why anyone would use things like Share, Branch, Label, Cloak, and Merge
Branch Into Trunk. I had fun writing my response, so I thought I would
re-post it here. Beware, this writeup doesn't even attempt to be objective
about which version control product is most neato. :-)
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 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 your 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
As I've mentioned before, Vault's labels are a little different from
SourceSafe's labels because they appear as just another folder in the repository
hierarchy. A label is used to remember a snapshot of time in the history
of your tree, so Vault presents that snapshot as a tree. In SourceSafe, a
label is merely a string which is associated with a set of versions of
items. The use cases remain the same.
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.
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
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:
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.
You didn't ask about Pin, but it deserves to be mentioned here. 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
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
This brings us to the topic of Branching. This is the most advanced of
the features you mentioned. 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
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
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
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.
The branch merging support in Vault 1.0 is not as powerful as the more mature
players in the SCM market. For example, Vault 1.0 can merge in only one
direction, from the branch back into its trunk. In my example, Vault 1.0
would only be able to merge from the blue version of turboLib back into the red
version. But we have clear plans and designs to keep improving our branch
merging in future releases.
And even though Vault 1.0's branch merging is not the most powerful
implementation, it may be one of the easiest to use. We implemented this
feature as a wizard which walks the user through the process step by step.
Our goal was to make branching less "scary", and we plan to maintain that value
as the feature becomes more powerful later.