Use Labels to Take a Snapshot of Your Files (Team Explorer Everywhere)

  • Article

By using labels, you can take a snapshot of your files so that you can refer back to that snapshot later. By using a label, you can view, build, or even roll back a large set of files to the state that they were in when the label was applied.

When you build your application by using Team Foundation Build, the files in your application are, by default, automatically labeled with the build number as part of the build process.

In this topic

  • Uses for Labels

  • Apply a Label

  • Rename a Label

  • List, Find, View, Edit, and Remove Labels

  • Retrieve Labeled Versions of Files to your Workspace

  • Modify a Label Definition by Using the Label Window

Required Permissions

To apply a label, your Label permission must be set to Allow. To find, list, or view labels, your Read permission must be set to Allow. To modify or delete a label, you must own it or your Administer Labels permission must be set to Allow. For more information, see the following topic on the Microsoft website: Team Foundation Server Permissions.

Uses for Labels

In many software projects, the team will build and release a new version of the product when the code has reached a reasonable level of quality and stability. The team must mark the current version of each file so that, even as the files continue to change, the team can still get and build the released version of every file in the project.

Theoretically, you could record the ID of each changeset for each file manually, but this kind of process is clearly not practical. You can use Team Foundation version control to simplify this task. 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. The following strings are a few examples of label names: "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.

After you apply a label, you might decide to change the files to which it applies. You can use Team Foundation version control to apply a label to additional files, to remove a label from certain files, and even to modify which version of a specific file to which the label applies.

Note

By applying a label, you gain many of the same benefits as creating a branch, but you typically reduce the cost and complexity.

Apply a Label

When you use the Team Foundation Server plug-in for Eclipse to apply a label that already exists, the operation removes the label from all file versions and then applies the label. However, the label operation is additive when you use the Cross-platform Command-Line Client for Team Foundation Server. For example, you might apply the label MyLabel to $/DinnerNow/Features/FeatureTeamA. If you later apply that to $/DinnerNow/Features/FeatureTeamB, the label will apply to both folders.

To apply a label from Source Control Explorer

  1. Open Source Control Explorer.

    For more information, see Open Source Control Explorer.

  2. In Source Control Explorer, right-click the team project collection, team project, branch, folder, or file to which you want to apply a label, and then click Apply Label.

    The New Label dialog box appears.

  3. In Name, type a name for the label.

  4. (Optional) In Comment, type your comments.

    In the Version list, the default value is Latest Version, which is the most typically used.

  5. (Optional) If you want the label to target a specific version, you can click one of the following options in the Version list:

    • If you click Changeset, you can specify the number of the changeset in the Changeset box. As an alternative, click the ellipses (...) to open the Find Changesets dialog box.

      For more information, see Search for a Changeset.

    • If you click Date, you can specify a date in the Date box or specify a date from the calendar in 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 List, Find, View, Edit, and Remove Labels.

    • If you click Workspace Version, the label is created for the version in your workspace.

  6. 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 specify Continue Editing. This action applies the label and then displays the New Label window. This window performs the same functions as the Edit Label window. For more information about how to use the Edit Label window to change a label, see Modify a Label Definition by Using the Label Window.

Note

If you use the Team Foundation Server plug-in for Eclipse to apply a label that already exists, you are prompted for whether you want to continue. If you click OK to continue, any items that are not contained in the path to which you are applying the label will no longer have that label.

To apply a label at a command prompt

  • At a command prompt, type tf label Label ItemSpec, and press ENTER. Replace Label with the name that you want to use to label the files. Replace ItemSpec with the file that you want to label. If you want to label all contents of a folder, type tf label Label . -recursive.

    For more information, see the following page on the Microsoft website: Label Command (Team Foundation Version Control).

Rename a Label

You cannot modify the name of an existing label, but you can easily apply a different label to the same files and same versions to which another label applies.

To apply a label that is based on an existing label in Source Control Explorer

  1. Open Source Control Explorer.

    For more information, see Open Source Control Explorer.

  2. In Source Control Explorer, right-click the project collection node (the root node), and then click Apply Label.

    The New Label dialog box appears.

  3. In Name, type a name for the label.

  4. (Optional) In the Comment box, type your comments.

  5. In the Version list, click Label.

    The Label box appears.

  6. 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 List, Find, View, Edit, and Remove Labels.

  7. Click Create.

  8. (Optional) After you have created the label, you can remove the old label.

    For more information, see List, Find, View, Edit, and Remove Labels.

List, Find, View, Edit, and Remove Labels

In the Team Foundation Server plug-in for Eclipse, you must use the Find Label dialog box to list and find a label. After you find the label that you want, you can then view, edit, or remove it, or you can work with the files to which it applies.

To list labels by using the Find Label dialog box

  1. Open Source Control Explorer.

    For more information, see Open Source Control Explorer.

  2. In Source Control Explorer, right-click any node, and then click Find Label.

    The Find Label dialog box appears.

  3. (Optional) Refine your search by performing one or more of the following steps:

    • In Name, type the name of the label.

    • In the Project list, click the team project that contains the label that you want to find.

    • In Owner, type the name or alias of the owner of the label.

  4. Click Find.

    The Results list displays labels that match the search criteria that you entered.

  5. (Optional) Perform one of the following steps:

    • To view or change a label, click it, and then click Edit.

      The Label window appears. For more information, see Modify a Label Definition by Using the Label Window.

    • To delete a label, click it, and then click Delete.

    • Click Close.

To list labels at a command prompt

  1. At a command prompt, change directories to the folder that corresponds to the Team Foundation Server workspace for which you want to view labels.

  2. Type tf labels, and then press ENTER.

    A list of the labels in the current Team Foundation Server workspace appears. You can specify the -format:detailed option to display more information about the labels. For more information, see the following page on the Microsoft website: Labels Command (Team Foundation Version Control).

To remove a label at a command prompt

  1. At a command prompt, change directories to the folder that corresponds to the Team Foundation Server workspace from which you want to remove a label.

  2. Type tf label –delete Label, and then press ENTER.

    Replace Label with the name of the label that you want to remove. For more information, see the following page on the Microsoft website: Label Command (Team Foundation Version Control).

Retrieve Labeled Versions of Files to Your Workspace

If you label a set of files, you are creating a snapshot of them at a certain point in time. Weeks or months after you have taken this snapshot, you may want 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.

To retrieve labeled versions of files

  1. Open Source Control Explorer.

    For more information, see Open Source Control Explorer.

  2. In Source Control Explorer, right-click the collection, team project, branch, or folder that contains the items that you want to download, and then click Get Specific Version.

    The Get dialog box appears.

  3. In the Type list, click 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 List, Find, View, Edit, and Remove Labels.

  4. Review and, if appropriate, specify any of the additional options in the Get dialog box.

  5. Click Get.

To retrieve labeled versions of files at a command prompt

  1. At a command prompt, change directories to the folder that corresponds to the Team Foundation Server workspace for which you want to retrieve files.

  2. Type tf get /version:LLabel ItemSpec, and then press ENTER. Replace Label with the name of the label that you want to retrieve. Replace ItemSpec with the name of the folder or file that you want to retrieve. You can omit the ItemSpec to retrieve all items that have the label that you specified.

    For more information, see the following page on the Microsoft website: Get Command (Team Foundation Version Control).

Modify a Label Definition

After you open the Edit Label window by using one of the preceding procedures, you are ready to start to work with the label. At the top of the window, a box displays the comment, which you can edit if you want.

In the Label window, you can perform the following tasks:

  • Apply an item to the label.

  • Remove the label from an item.

Note

Before you start these procedures, you must have opened the Edit Label window. For more information, see List, Find, View, Edit, and Remove Labels or Apply a Label.

To change the version of a file that is labeled, you must remove the label from that file and reapply it to the version that you want to use.

To apply the label to an item

  1. In the Edit Label window, click Add.

  2. In the Select Item to Label dialog box, locate and then click the item to which you want to apply the label.

  3. (Optional) In the Version list, you can click one of the following options if you want to apply the label to a specific version:

    • If you click Latest Version, the label will be applied to the most recent version in version control.

    • If you click Changeset, you can specify the number of the changeset in the Changeset box. As an alternative, you can click the ellipses (...) to open the Find Changesets dialog box.

      For more information, see Search for a Changeset.

    • If you click Date, you can specify a date in the Date box or specify 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 List, Find, View, Edit, and Remove Labels.

    • If you click Workspace Version, the label is created for the version in your Team Foundation Server workspace.

  4. Click OK, and then click OK to accept the changes to the label.

To remove a label from an item

  1. In the Edit Label window, click the collection, team project, branch, folder, or file from which you want to remove this label.

  2. Click Remove.

    The label is removed from the item. If the item is a project collection, a team project, a branch, or a folder, the label is also removed from all the items that the item contains.

  3. Click OK to accept the changes to the label.

See Also

Other Resources

Using Version Control (Team Explorer Everywhere)

Working with Changesets (Team Explorer Everywhere)

Working with Team Foundation Server Workspaces (Team Explorer Everywhere)