Use Labels to Take a Snapshot of Your Files

  • Article

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 this article

  • Using Labels

  • Apply a Label

  • Rename a Label

  • List, Find, View, Edit and Remove Labels

  • Download Labeled Versions of Files to Your Workspace

  • Use the Label Window to Work with Labels

  • Roll Back Files to a Labeled Version

  • Work with Labels from the Command Line

Using Labels

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.

Tip

Applying a label provides many of the same benefits as creating a branch, but typically with lower cost and complexity.

Apply a Label

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, see Find Information About a Changeset.

    • 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. For more information, see Find, Edit, and Remove Labels.

    • 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, see Use the Label Window to Work with Labels.

Note

When you apply a label using a name that already exists, the system warns you and asks if you want to continue. If you click OK to continue, any items not contained in the path to which you are applying the label will no longer have that label.

Rename 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. (For more information, see Find, Edit, and Remove Labels.)

  6. Click Create.

  7. (Optional) After you have created the new label, you can remove the old label. For more information, see Find, Edit, and Remove Labels.

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. For more information, see Use the Label Window to Work with Labels.

    • 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. For information about how to use this window, see Use the Label Window to Work with Labels.

    • 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.

For more information about how to use the label tab in the History window, see View Historical Data.

Download Labeled Versions of Files to Your Workspace

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. For more information about how to use this dialog box, see Find, Edit, and Remove Labels.

  3. Review, and if appropriate, select any of the additional options in the Get dialog box.

  4. Click Get.

Use the Label Window to Work with Labels

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.

    Tip

    You can press and hold the CONTROL or SHIFT keys and then select multiple items.

  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. For more information, see Find Information About a Changeset.

    • 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. For more information, see Find, Edit, and Remove Labels.

    • 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. For more information, see Find Information About a Changeset.

    • 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 the Find Label dialog box. For more information, see Find, Edit, and Remove Labels.

    • 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

Roll Back Files to a Labeled 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. For more information, see Rollback Command (Team Foundation Version Control).

Work with Labels from the Command Line

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 /delete label name, where label name is the name of the label that you want to delete.

See Also

Reference

Label Command (Team Foundation Version Control)

Labels Command

Concepts

Working with Changesets

Create a Workspace to Work with your Team Project

Team Foundation Server Permissions

Using Source Control Explorer

Other Resources

Branching and Merging