Labels enable you to take a snapshot of your files so that at
a later date you can refer back to that snapshot. By using your label, you can
view, build, or even roll back a large set of files to the state they were in
when you applied the label.
Required
Permissions
To apply a label, you must have the Label permission set to Allow. To find, list, or view labels, you must have the Read permission set to Allow. To modify or delete a label, you must own the label or have
the Administer Labels permission set to Allow.
In many software projects, when the
code has reached a reasonable level of quality and stability, the team will
build and release a new version of the product. The team needs to mark the
current version of each file so that even as the files continue to change, the
team can still get and build the new version of every file in their project.
Theoretically, you could record the
ID of each changeset for each file manually; but clearly this kind of process
is not practical. Team Foundation version control makes the job simple:
You apply a label to the folder, branch, or team project that contains the
files. You can give the label a name that follows whatever naming convention
you prefer. Some examples of label names include: "Sprint 5",
"M1", "Beta2", and "Release Candidate 0".
After you have applied the label,
you can use it to qualify operations such as building, branching, merging, comparing,
and getting specific versions of files and folders.
Sometimes after you apply a label
you decide that you need to change it. Team Foundation version control enables
you to apply a label to additional files, remove a label from certain files,
and even to modify which version of a specific file to which the label applies.
Apply a
label
1. In Source
Control Explorer, right-click the collection, team project, branch,
folder, or file to which you want to apply a label and click Apply
Label.
The New
Label dialog
box appears.
2. In
the Name box, type a name for the label.
3. (Optional)
Type your comments in the Comment box.
4. In
the Version list, Latest Version is
selected by default. This option is the one most typically used, but if you
need the label to target a specific version, you can select one of the
following other options:
·
If you click Changeset, you can specify the number of the changeset in the Changeset box. Alternatively, click the ellipses (…) to open the Find Changesets dialog box. For more information,
·
If you click Date, you can specify a date in the Date box or select a date from the calendar on the drop-down
menu.
·
If you click Label, you can specify an existing label upon which to base
the new label. Either type the label name in the Label box, or click the ellipses (…)
to open the Find Label dialog
box.
·
If you click Workspace Version, the label is created for the version in your
workspace.
5. When
you are satisfied with your settings, perform one of the following steps:
·
To apply the label, click Create.
·
To apply the label and then modify it after it has been
applied, click Create and Edit. This applies the label and then displays the Label window. For more information about using the Label window to edit a label
While you cannot modify the name of an existing label, you
can easily apply a new label to exactly the same files and same versions to
which another label applies.
Apply a
label based on an existing label
1. In
Source Control Explorer, right-click the project collection node (the root
node), and then click Apply Label.
The New
Label dialog
box appears.
2. In
the Name box, type a name for the label.
3. (Optional)
In the Comment box, type a comment.
4. In Version list, select Label.
The Label box appears.
5. Perform
one of the following steps:
·
Type the name of the existing label.
·
If you are not sure of the name of the existing label,
click the browse button with the ellipses (…) next to the Label box.
The Find
Label dialog
box appears.
Use
the options in the Find Label dialog
box to filter the list of labels and find the existing label to which you want
to apply the new label.
6. Click Create.
7.
(Optional) After you have created the new label, you
can remove the old label. For more information.
List, Find, View, Edit and Remove Labels
There are two ways to list and find labels: the Find Label dialog box and the Label tab in the History window. After you find the label you
are interested in, you can then view it, edit it, remove it, or work with the
files to which it applies.
Find and
work with labels by using the Find Label dialog box
1. In
Source Control Explorer, on the File menu,
point to Source Control, then point to Label, and then click Find Label.
The Find
Label dialog
box appears.
2. (Optional)
Refine your search by performing one or more of the following steps:
·
In the Name text
box, enter the name of the label.
·
In the Project list,
select the team project that contains the label that you want to find.
·
In the Owner text
box, type the name or alias of the owner of the label.
3. Click Find.
The Results list displays labels that match the search criteria
that you entered.
4. (Optional)
Perform one of the following steps:
·
To view or edit a label, select it and click Edit.
The Label window appears.
·
To delete a label, select it and click Delete.
·
Click Close.
Sometimes
you may not be sure of the name of a label, but you know that the label was
applied to a particular item under version control. The following procedure
explains how to find and then work with a label in this situation.
List and
work with labels that apply to a specific item
1. In Source
Control Explorer, right-click the item to which the label you want to
find applies, and then click View History.
The History window appears.
2. Click
the Labels tab to display the list of labels that apply to this
item.
3. (Optional)
Perform one of the following steps:
·
To view or edit a label, right-click it and select Edit
Label.
The
Label window appears.
·
To delete a label, right-click it and select Delete
Label.
·
Right-click the label and select other actions such as Get
This Version, and Compare..
Labeling a set of files is like
taking a snapshot of how they existed at a certain point in time. Weeks or
months after you have taken this snapshot, you may need to view or work with
the files as they existed in that snapshot. The following procedure explains
how to download the labeled versions of a set of files to your workspace.
Download
labeled versions of files to your workspace
1. In Source
Control Explorer, right-click the project collection, team project,
branch, or folder that contains the items you want to download and then click Get
Specific Version.
The Get dialog box appears.
2. From
the Type list, select Label, and then either type the label name in the Label box, or click the ellipses (…)
to open the Find Label dialog
box.
3. Review,
and if appropriate, select any of the additional options in the Get dialog box.
4. Click Get.
After
you have opened the Label window by using one of the preceding procedures, you
are ready to begin working with the label. At the top of the window is a box
that displays the comment, which you can edit if you want.
You can use the Label window to perform the following
tasks:
·
Add an item to the label
·
Remove an item from the label
·
Change the version of a file
·
Perform other actions on an item
Add an item
to the label
1.
In the Label window,
click Add Item.
The Choose Item
Version dialog
box appears.
2.
In the Choose Item Version dialog box, navigate to and then select
the item that you want to add.
3.
(Optional) If you need
the label to target a specific version, you can select one of the following
options from the Version list:
·
If you click Latest Version,
the label will be applied to the latest version that is in version control.
·
If you click Changeset, you can specify the
number of the changeset in the Changeset box. Alternatively, click the ellipses (…) to open the Find Changesets dialog box.
·
If you click Date, you can specify a
date in the Date box or select a date from the calendar on the drop-down menu.
·
If you click Label, you can specify an
existing label upon which to base the new label. Either type the label name in
the Label box, or click the
ellipses (…) to open the Find Label dialog box.
·
If you click Workspace Version,
the label is created for the version in your workspace.
4.
Click OK.
5.
Click the File menu, and then click Save.
Remove an
item from the label
1.
In the Label window, locate the
collection, team project, branch, folder, or file that you want to remove from
this label.
2.
Right-click the item
and select Remove from Label.
The label is removed from the item. If the item is a project
collection, team project, branch, or folder, then the label is also removed
from all the items it contains.
3.
Click the File menu, and then click Save.
Change the
version of a file
1. In
the Label window, locate the file that you want to modify.
2. Right-click
the file and select Change Item Version.
3. The Choose
Item Version dialog
box appears.
4. Perform
one of the following steps:
·
Click Latest Version to
apply the label to the latest version that is in version control.
·
Click Changeset, and then specify the number of the changeset in the Changeset box. Alternatively, click the ellipses (…) to open the Find Changesets dialog box.
·
Click Date, and then specify a date in the Date box or select a date from the calendar on the drop-down
menu.
·
Click Label, and then specify an existing label upon which to base
the new label. Either type the label name in the Label box, or click the ellipses (…)
to open theFind Label dialog box.
·
Click Workspace Version, the label is created for the version in your
workspace.
5. Click
the File menu, and then click Save.
Perform
other actions on a labeled item
When you right-click an item in the Label window, you can also
select one of the following commands:
·
View (files only)
·
View History
·
Compare (files only)
·
Annotate (files only)
·
Get This Version
You can use the tf rollback command to revert a set of files to
the state in which they existed in the versions marked by a label.
This section provides some of the typical ways to work with labels
from the command line.
List labels
from the command line
List labels
from command line
1.
Click Start, click All Programs, point to Microsoft
Visual Studio 2010, point to Visual
Studio Tools, and then click Visual Studio Command Prompt (2010).
2.
Type cd path, where path is the directory that contains the
applicable workspace.
3.
Type tf labels.
Apply and
Edit Labels from the Command Line
Applying a label from the command line has a different effect than
applying a label by using Visual Studio ALM (as
described earlier in this topic). When you use Visual Studio ALM to apply a
label that already exists, the operation removes the label from all file
versions and then applies the label.
From the command line, however, the label operation is additive.
For example, suppose you apply the label mylabel to $/DinnerNow/Features/FeatureTeamA.
If you later apply the label mylabel to $/DinnerNow/Features/FeatureTeamB,
then mylabel will apply to both folders.
To apply a
label from the command line
1.
Click Start, click All Programs, point to Microsoft
Visual Studio 2010, point to Visual
Studio Tools, and then click Visual Studio Command Prompt (2010).
2.
Type cd path, where path is the path to the folder that you want to
label.
3.
Type tf label mylabel . /recursive.
The system applies the mylabel label
to the workspace version of the "path" folder and all the
files and folders it contains.
Remove a
Label from the Command Line
To remove
labels from command line
1.
Click Start, click All Programs, point to Microsoft
Visual Studio 2010, point to Visual
Studio Tools, and then click Visual Studio Command Prompt (2010).
2.
Type cd path, where path is the directory that contains the
applicable workspace.
3.
Type tf label /deletelabel name,
where label name is the name of the label that you want to
delete.
