February 13, 2009
Surround SCM Labels
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....
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 labelsOne 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:
Label managementNow 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.
Creating new labelsClick on the Add button to create a new label. Figure 3 below illustrates the Create Label dialog.
Editing existing labelsClick on Edit to edit an existing label. Figure 4 below illustrates the Edit Label dialog.
- 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 labelsClick 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).
DuplicateClick 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 LabelsSelect two labels and select Differences two see how to labels compare to each other. Figure 5 below illustrates the Label Differences dialog.
- 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.