Label Command (Team Foundation Source Control)
Attaches a label to or removes a label from a version of a file or folder in the Team Foundation source control server.
tf label [/server:servername] labelname[@scope] [/owner:ownername]
itemspec [/version:versionspec] [/comment:("comment"|@commentfile)]
[/child:(replace|merge)] [/recursive]
tf label [/server:servername] /delete labelname[@scope]
[/owner:ownername] itemspec [/version:versionspec] [/recursive]
Parameters
| Argument | Description |
|---|---|
servername |
The user-provided value for the /server option. Example: teamfoundation2. |
labelname |
Identifies the name of the label to attach, modify, or remove from the specified items. |
@scope |
Specifies a Team Foundation source control server directory within which the labelname is unique. This parameter lets you independently create, manage, retrieve, and delete one label or set of labeled items when two labels of the same name exist in different parts of the Team Foundation source control server. |
ownername |
Provides a value such as DOMAIN\JuanGo or just juango to the /owner option. |
itemspec |
Identifies the file or folder from which to label, re-label, or modify. For more information about how Team Foundation parses itemspecs to determine which items are within scope, see Command-Line Options. |
versionspec |
Provides a value such as c2 for the /version option. For more information about how Team Foundation parses a version specification to determine which items are within its scope, see Command-Line Syntax. |
comment |
A user-provided comment about the label. |
@commentfile |
The user-provided path of a file on disk that contains the comment to use for the check-in. |
| Option | Description |
|---|---|
/server |
Identifies the Team Foundation Server. This option is required if the command is invoked from a directory that is not mapped to a workspace. |
/owner |
Specifies the name of the user who owns the label. |
/version |
Optional Specifies the version of the file or folder to which the label should be attached, modified, or from which the label should be removed. These are changeset values, for example, C93. By default, Team Foundation uses the base workspace version if no versionspec is provided. |
/comment |
Adds or modifies a description or comment for the label. |
/child |
Identifies how to deal with items that have pre-existing labels which are identical to the label you have specified. Use Replace to update the version of the item corresponding to the existing label. Use Merge to leave items with the existing label alone. |
/recursive |
Labels all items in the directory that matches your itemspec and versionspec. |
/delete |
Removes the label from all specified items. |
Remarks
A label is a marker that you can attach to a set of unrelated files and folders in the Team Foundation source control server to simplify their retrieval to a workspace for either development or build purposes. Therefore, a label is like a changeset or date/time to which and from which you can arbitrarily add and remove files and folders or change the versions of the items therein. A label is a version specification that can be passed to the following Team Foundation commands:
Common types of labels are milestone labels such as "M1," "Beta2," or "Release Candidate 0."
Labels are version-specific, that is, you can only attach a label to one version of a file or folder. Each version of an item can support multiple labels.
By default, the label command is non-recursive. If you label a folder in the Team Foundation source control server by using the following command syntax, Team Foundation applies the label to the project folder but not to the files or folders the project contains: tf label M3.2 projects.
A label is not a versioned object; therefore, the label history of files is not tracked. Additionally, a label operation does not create a pending change in your workspace. When you issue the label command, the appropriate updates are immediately reflected in the Team Foundation source control server.
Removing and Deleting Labels
You can use the Unlabel Command to remove a label from a file or folder. Alternatively, you can delete a label from the system using the tf label /delete command.
For information about an existing labelthat includes a list of the items to which the label has been attached, its comment, scope, and owner, see Labels Command.
Managing Overloaded Labels
Label names must be unique throughout a specified scope. When you add a label, you reserve the use of that label name at or under the specified or implied scope. The default value for the @scope parameter is the team project, for example, $/TeamProject1.
If another team or user adds a common label such as "M3" to a set of source files in a different part of the Team Foundation source control server, you can apply the M3 label to source files in your project as long as the root project folders are in different directories. For example, if files in the $/math directory are labeled "M3," you can apply the "M3" to files in your $/projects directory.
To get, remove a label, or otherwise manage your M3-labeled items, you should specify the @scope parameter to tell Team Foundation which M3 label you want to work with.
You can effectively prevent other users from "overloading" a label such as "M3" in different parts of the Team Foundation source control server by either creating your label at the root ($/) of the Team Foundation source control server or by fine-tuning Label permissions for certain folders.
Using the /Child Option to Avoid Labeling Mishaps
If you issue a label command together with a pre-existing label name and an itemspec that includes files that are already marked by the same label, the value of the /child option determines whether the marked files are updated with new revision information. That is, the files are labeled by the same name, but have different scope.
For example, assume that you have folder named c:\projects that contains two files, 314.cs and 271.cs. Also assume that version C70 of 314.cs is labeled "ready." The latest version of 314.cs is version C93. If you apply a label, "ready" to the latest version of the folder and the files it contains using the following command, the "ready" label is moved from 314.cs;C70 to 314.cs;C93:
tf label ready c:\projects /recursive /version:T /child:Replace
On the other hand, if you do not want to move the existing label "ready" from version C70 to version C93 of 314.cs, you would use the following syntax:
tf label ready c:\projects /recursive /version:T /child:Merge
When you specify Merge as the value for the /child option, pre-existing instances of the issued label are left alone.
Note
T is used for "Tip" to get the latest version of versionspec in the above two examples.
Examples
The following example attaches the "goodbuild" label to the workspace version of the "docs" folder and the files and folders it contains.
c:\projects>tf label goodbuild docs /recursive
The following example attaches the "goodbuild" label to the "docs" folder but not the files and folders the docs folder contains.
c:\projects>tf label goodbuild docs
The following example attaches the "goodbuild" label to version 3 of 314.cs in the Team Foundation source control server.
c:\projects>tf label goodbuild /version:3 $/src/314.cs
The following example removes the "badbuild" label from all items in the Team Foundation source control server.
c:\projects>tf label /delete badbuild
The following example uses the scope option to apply a label to 314.cs.
c:\projects>tf label goodbuild@$/TeamProject1 314.cs
Security
To use the label command, you must have the Label permission set to Allow. To modify or delete labels created by other users, you must have the Administer labels permission set to Allow. For more information, see Team Foundation Server Permissions.
See Also
Tasks
Walkthrough: Advanced Functionality of Source Control
How to: Apply Labels
Reference
Command-Line Syntax
Labels Command
Unlabel Command
Concepts
Source Control Security Rights and Permissions
Working with Labels