February 13, 2009

Surround SCM Labels

Surround SCM
Labels have always been a part of Surround SCM, however, they were originally provided mainly to support conversions from legacy systems that used labels. The following is an overview of the new labels. We always suggested that our customers use snapshot branches and steer away from using labels whenever possible. Labels were not treated as first-class citizens and had several limitations, for example:
  • You could not delete a label
  • You could not edit a label
  • You could not view differences between two labels.
  • And others....
One of the major changes in Surround SCM 2009 is the full support of labels. They are finally treated as first class citizens. There may be situations where a label might make more sense than using snapshot branches. [toc]

What are labels anyway?

Since we steered you away from labels, you might have chosen not to waste any time learning about them, and who could blame you. Unless you came from another system that used labels, you probably never used them. So you may be wondering what are labels and why should you care about them. Labels allow you to apply a string to a file or set of files, and the string is associated with a specific version of the file(s). For example, you just did a get of your entire project and did a successfull build. One way to capture this build is to create a snashot branch. Another approch is to apply a label (the string would be the build number) to the project. If you are confused when to use a label and when to use a snapshot, there is an article posted in our general wiki on this. Keep in mind that the article was written for versions prior to 2009.

Adding files to labels

One key change in the way labels work now is that now you add files to labels, as opposed to adding a label to a file. This was all done in a single operation. In prior versions, you only created a label when you were about to apply it to a file. You typed in the label name and it was associated with the selected file(s). If you wanted to add more files to the label you added a label by the same name to those files. Now, you can create the label first, and then apply it to the file(s). In fact, you could create several "empty" labels and then apply these labels to which ever files and versions you would like. The end result is virtually the same. Some concepts remain the same. You can still apply a label to single file, a selected group of files, or to an entire tree of files by adding the label at the repository level. Also, labels are still only applied to files, not repositories. One of the improvements is that you can now choose an existing label or a new label. If you want to apply an existing label to a file, you don't have to remember the label name and hope you did not mistype it. Being able to choose it from a list eliminates this risk. When you create a new label, you can also specify the scope. A label can be scoped to only exist on a specific branch, or on all branches for a given mainline. If you specify the scope to only be on a specific branch, the label will only show up there. This is a little bit different than in previous versions, where a label would be applied on a branch, but after a promote or rebase, the label would also show up on the destination branch. Labels also work a little different with shared files. The label is only applied to a specific share, instead of all shares. Figure 1 below illustrates the dialog that comes up when you choose to apply a label:

Figure 1 - Add to Label dialog

The first two text boxes are self explanatory, they indicate the branch and file(s) that will receive the new label. The dropdown list allows you to select from existing labels or to create a new label. The Select button allows you to browse the list of labels (including hidden labels) and create a new label. Enter Comments to explain the label in more detail. The name you choose for the label may make sense to you but not other users. Three years from now it may not make sense to you either. The File Version allows you to apply the label to the latest version of the file or a previous version in your working directory. You can not use the Version in working directory option to label modified files that have not been checked in. If they are not stored in Surround SCM, there is nothing that Surround SCM can associate the label to. A use case for using the Version in working directory option is when you do a get based on timestamp, and want to label those files for future retrieval. Maybe you forgot to apply a label to last Friday's build and several check ins have already taken place. You can do a get, use Friday's timestamp, and apply a label to those files. The checkbox Update label with selected version will update an existing label that is already associated with a different version of the selected file.

Label management

Now that we have added all of the new functionality to labels, we also needed to provide a way to easily manage labels. This management console is accessed from the Tools > Labels menu option. From here you are able to see all labels, change their name, remove files from them, delete the label entirely, duplicate the label, and even view differences between two labels.

Figure 2 - Labels management console

Creating new labels

Click on the Add button to create a new label. Figure 3 below illustrates the Create Label dialog.

Figure 3 - Create Label dialog

Label Name: Enter the name of the label to create. Description: A description is important because it can explain the purpose of the label. Label Scope: Select the mainline branch if you want this label to exist on all branches. Select a specific branch so the label only exists on that specific branch. The Browse button and the dropdown menu allow you to browse through your branch tree. Hidden: Check the box to make the label hidden. Hiding labels prevents them from showing up in dropdowns (like in the Add to Label dialog).

Editing existing labels

Click on Edit to edit an existing label. Figure 4 below illustrates the Edit Label dialog.

Figure 4 - Edit Label dialog

You can do the following:
  • Edit the label name.
  • Edit the label description.
  • Change the scope of the label.
  • Remove file(s) from the label.
  • Change the hidden attribute.

Deleting labels

Click on Delete to delete the label and all information associated with this label. The files associated with the label will not be removed, but any information about the label itself is destroyed (not recoverable).


Click on Duplicate if you want to create a new label that contains an identical file list (and versions associated) of an existing label. The duplicate can have different scope and different hidden attribute.

Comparing Labels

Select two labels and select Differences two see how to labels compare to each other. Figure 5 below illustrates the Label Differences dialog.

Figure 5 - Label Differences dialog.

There are three type of Differences status:
  • Identical - Both labels have the same version of the same file on the same branch.
  • Missing - Label does not contain this file (any version) on the specified branch (may exist on another branch if it is a global label).
  • Version - Both labels have the same file on the same branch, but are associated with different versions. Selecting a file that has a version difference enables the Differences button, which launches a diff utility showing the difference between the two versions.

More information

Chapter 10 of the user guide explains in more detail the use of labels in Surround SCM 2009.