Chapter 8
Labels

Use a label when you want to:

• keep track of all the file revisions contained in a particular release of software,

• distribute a particular set of file revisions to other users, or

• branch from a known set of file revisions.

Labels or changelist numbers?

• The files and revisions tagged by a label can be changed at any point in the label's existence.

• Changelists are always referred to by Perforce-assigned numbers, but labels are named by the user.

• A changelist is an implicit revision marker, but labels must be applied in order to be used as revisions.

• A changelist is a revision marker that applies to all files in the depot, but labels are typically limited to a subset of depot files.

Using labels

Note

Versions of Perforce prior to release 2004.2 used the p4 labelsync command to tag files with a label. The p4 tag command, introduced in Release 2004.2, simplifies this process. The p4 labelsync command remains available for specialized purposes. For details, see "Differences between p4 tag and p4 labelsync" on page 100.

Tagging files with a label

For example, to tag the head revisions of files that reside under //depot/proj/rel1.0/hdrs with the label my_label, use the following:

p4 tag -l my_label //depot/proj/rel1.0/hdrs/...

To tag revisions other than the head revision, specify a changelist number in the file pattern:

p4 tag -l my_label //depot/proj/rel1.0/hdrs/...@1234

Untagging files

p4 tag -d -l labelname filepattern

To untag a subset of tagged files, supply a file specification. For example, if you have previously tagged all revisions under //depot/proj/rel1.0/... with my_label, you can untag only the header files with:

p4 tag -d -l my_label //depot/proj/rel1.0/hdrs/*.h

Previewing tag's results

Listing files tagged by a label

p4 files @labelname

Listing labels that have been applied to files

p4 labels filepattern

Referring to files using a label

If p4 sync @labelname is called with no file parameters, all files in the workspace view that are tagged by the label are synced to the revision specified in the label. All files in the workspace that do not have revisions tagged by the label are deleted from the workspace. Open files or files not under Perforce control are unaffected. This command is equivalent to p4 sync //...@labelname.

If p4 sync @labelname is called with file arguments, as in p4 sync files@labelname, files in the user's workspace that are specified on the command line and also tagged by the label are updated to the tagged revisions.

Example:  Retrieving files tagged by a label into a client workspace.

Lisa wants to retrieve some of the binaries tagged by Ed's build1.0 label into her client workspace. To get all files tagged by build1.0, she could type:

p4 sync //depot/[email protected]

or even:

p4 sync @build1.0

Instead, she's interested in seeing only one platform's build from that label, so she types:

p4 sync //depot/proj/rel1.0/bin/osx/*@build1.0

and sees:

//depot/proj/rel1.0/bin/osx/server#6 - added as /usr/lisa/osx/server#6 //depot/proj/rel1.0/bin/osx/logger#12 - added as /usr/lisa/osx/logger#12 //depot/proj/rel1.0/bin/osx/install#2 - added as /usr/lisa/osx/install#2 <etc>

All files under //depot/proj/rel1.0/bin/osx that are tagged with Ed's build1.0 label and are also in Lisa's client workspace view are retrieved into her workspace.

Deleting labels

p4 label -d labelname

Creating a label for future use

Label names share the same namespace as client workspaces, branches, and depots. A new label name must be distinct from any existing client workspace, branch, or depot name.

For example, you can create a new label my_label by typing:

p4 label my_label

Enter description for the label, and save the form. (You do not need to change the View: field.)

After creating the label, you are able use the p4 tag and p4 labelsync commands to apply the label to file revisions. Only one revision of a given file can be tagged with a given label, but the same file revision can be tagged by multiple labels.

Using label views

To prevent yourself from inadvertently tagging your entire workspace with a label, set the label's View: field to a subset of the depot. The default label view includes the entire depot (//depot/...), which tags any (and every) file in the depot with p4 labelsync.

Example:  Using a label view to control what files can be tagged

Ed wishes to tag a recently built set of binaries with the label build1.0. He wants to ensure that only the files in the build path can be tagged with the build1.0 label.

He types p4 label build1.0 and uses the label's View: field to restrict the scope of the label as follows:

Label: build1.0 Owner:  edk Description:         Created by edk. Options:        unlocked View:         //depot/proj/rel1.0/bin/...

After he saves from the editor, a new label build1.0 is created. This label can tag only files in the /rel1.0/bin directory.

With the default View: of //depot/..., Ed must type:

p4 tag -l build1.0 //depot/proj/rel1.0/bin/...

With the new label view, he can use the simpler p4 tag -l build1.0 //... to tag the desired files.

Using labels to record workspace configurations

p4 labelsync -l ws_config

To recreate the workspace tagged by the ws_config label, sync your workspace to the label with:

p4 sync @ws_config

Preventing inadvertent tagging and untagging of files

To prevent the inadvertent tagging and untagging of files, lock the label by setting the value of the Options: field of the p4 label labelname form to locked. Other users will be unable to use p4 labelsync or p4 tag to tag files with that label until you or a Perforce superuser unlocks the label.

Differences between p4 tag and p4 labelsync

• The p4 tag command automatically creates and applies a new label to specified files if no label exists. The p4 labelsync command can only be used to tag files with an existing label.

• The p4 tag command requires a file pattern argument. The p4 labelsync command does not require a file pattern argument; if you call p4 labelsync without a file pattern argument, the command applies to your entire client workspace view.

• By default, p4 tag tags the #head revisions of files in the depot. By default, the p4 label command tags the revisions of files most recently synced to your client workspace; that is, to the #have revision.

• A single call to p4 tag can tag or untag files, but never both. The p4 labelsync command can tag some files while untagging others in order to make a label match a client workspace.

How p4 tag works

p4 tag [-d -n] -l labelname filename...

1. If labelname does not exist, create labelname. By default, you are the owner of the new label, the label is unlocked, and has a view of the entire depot. After creating the label, you can change these default options by using p4 label labelname.

2. If labelname already exists, you must be the owner of the label to use p4 tag on it, and the label must be unlocked. If you are not the owner of a label, you can (assuming you have sufficient permissions) make yourself the owner by running:
   p4 label labelname

   and changing the Owner: field to your Perforce user name in the p4 label form. If you are the owner of a label, you can unlock the label by setting the Options: field (also in the p4 label form) to unlocked.

3. All files tagged with a pre-existing label must be in the label view. Any files or directories not included in a label view are ignored by p4 tag.

4. When p4 tag files is used to tag specified file revisions with a label, revisions not tagged with the label are tagged. If another revision of the file has already been tagged with the label, it is untagged and the newly specified revision is tagged. Any given file revision can be tagged by one or more labels, but only one revision of any file can be tagged with a given label at any one time.

5. If you call p4 tag with file pattern arguments that contain no revision specifications, the #head revisions are tagged with the label.

6. If you call p4 tag with file pattern arguments and those arguments contain revision specifications, the specified file revisions are tagged with the label.

How p4 labelsync works

p4 labelsync [-a -d -n] -l labelname [filename...]

1. A label must exist, and you must be the owner of the label to use p4 labelsync on it, and the label must be unlocked.

2. All files tagged with a label must be in the label view specified in the p4 label form. Any files or directories not included in a label view are ignored by p4 labelsync.

3. When p4 labelsync is used to tag a file revision with a label, the revision is tagged with the label if it is not already tagged with the label. If a different revision of the file is already tagged with the label, it is untagged and the newly specified revision is tagged. Any given file revision can be tagged by one or more labels, but only one revision of any file can be tagged with a given label at any one time.

4. If labelsync is called with no filename arguments, as in:
   p4 labelsync -l labelname

   then all the files in both the label view and the client workspace view are tagged with the label. The revisions tagged by the label are those last synced into the client workspace; these revisions ("the #have revisions") can be seen in the p4 have list. Calling p4 labelsync this way removes the label from revisions it previously tagged unless those revisions are in your workspace.

5. When you call p4 labelsync with file pattern arguments, but the arguments contain no revision specifications, the #have revision is tagged with the label.

6. If you call p4 labelsync with file pattern arguments and those arguments contain revision specifications, the specified file revisions are tagged with the label.

   Specifying a revision in this manner overrides all other ways of specifying a revision with a label; whether the client workspace contains a different revision than the one specified, (or doesn't contain the file at all), the revision specified on the command line is tagged with the label.

Label Reporting