Label scope revealed

One not very well-known feature of Team Foundation version control label, is the ability to scope the label by the project (or, generally, by any folder path). By scoping I mean the following – the label is identified not only by name, but also by so-called "scope", where scope is the actual path within which the label name is unique.

Thus if your label scope is "$/", that means that you essentially have one global label; when scope is "$/Project1", the label name is unique within Project1.

Using UI (Source Control Explorer) you cannot fine tune the scope; generally, when you label set of items the scope will be defined according to the following rules

• If the items being labeled belong to the same Team project (say Project1), the scope will be "$/Project1"
  
• If the items labeled belong to several Team projects (say Project1 and Project2), the scope will be "$/"
  

The scope of the label can be viewed through command line client (for example, for label SampleLabel, tf labels SampleLabel /format:detailed) or using version control object model (as is done in Labels Sidekick).

However, when one uses command line to label files certain complications may occur if the label is not specified. Let's say that you are creating cross project label (that is label that contains set of files from Project1 and Project2). Since the label contains two sets of files that should be done through two calls to tf label

> tf label SampleLabel $/Project1/Source/* /recursive /server:TFS1
Created label SampleLabel@$/Project1

> tf label SampleLabel $/Project2/Source/* /recursive /server:TFS1
Created label SampleLabel@$/Project2

As you can see from the output, instead of creating one label with two sets of files, two separate labels were created: those labels have the same name but different scope (symbol at @ is used by tf to display the label's scope – thus the scope of the first label is $/Project1 and of the second one $/Project2).

To create one label, the scope needs to be explicitly specified (using @ syntax):

> tf label SampleLabel@$/ $/Project1/Source/* /recursive /server:TFS1
Created label SampleLabel@$/

> tf label SampleLabel@$/ $/Project2/Source/* /recursive /server:TFS1
Updated label SampleLabel@$/

Specifying explicit scope (common for the two sets of files – in our case, root folder $/) achieves the initial goal.

In my opinion, the scenario above would be the most common usage for the scope. While not recommended, the scope may be used to create same name labels within the same project as well (for example, specifying SampleLabel@$/Project1/Source will limit uniqueness of the label name to the folder $/Project1/Source). I attach "Not recommended" to this practice because of the relative invisibility of the scope in the SCE; not all users will be aware of the command line or third party tools and several labels with the same name in UI may be confusing.