Labels

A Perforce label is a set of tagged file revisions. For example, you might want to tag the file revisions that compose a particular release with the label release2.0.1. In general, you can use labels 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 (for example, a standard configuration).

  • Populate a clean build workspace.

  • Specify a set of file revisions to be branched for development purposes.

  • Sync the revisions as a group to a client workspace.

Labels and changelist numbers both refer to particular sets of file revisions but differ as follows:

  • A label can refer to any set of file revisions. A changelist number refers to the contents of all the files in the depot at the time the changelist was submitted. If you need to refer to a group of file revisions from different points in time, use a label. If there is a point in time at which the files are consistent for your purposes, use a changelist number.

  • You can change the contents of a label. You cannot change the contents of a submitted changelist.

  • You can assign your own names to labels. Changelist numbers are assigned by Perforce.

Changelists are suitable for many applications that traditionally use labels. Unlike labels, changelists represent the state of a set of files at a specific time. Before you assume that a label is required, consider whether simply referring to a changelist number might fulfill your requirements.

Tagging files with a label

To tag a set of file revisions (in addition to any revisions that have already been tagged), use p4 tag, specifying a label name and the desired file revisions.

For example, to tag the head revisions of files that reside under //depot/release/jam/2.1/src/ with the label jam-2.1.0, issue the following command:

p4 tag -l jam-2.1.0 //depot/release/jam/2.1/src/...

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

p4 tag -l jam-2.1.0 //depot/release/jam/2.1/src/...@1234

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.

Untagging files

You can untag revisions with:

p4 tag -d -l labelname filepattern

This command removes the association between the specified label and the file revisions tagged by it. For example, if you have tagged all revisions under //depot/release/jam/2.1/src/... with jam-2.1.0, you can untag only the header files with:

p4 tag -d -l jam-2.1.0 //depot/release/jam/2.1/src/*.h

Previewing tagging results

You can preview the results of p4 tag with p4 tag -n. This command lists the revisions that would be tagged, untagged, or retagged without actually performing the operation.

Listing files tagged by a label

To list the revisions tagged with labelname, use p4 files, specifying the label name as follows:

p4 files @labelname

All revisions tagged with labelname are listed, with their file type, change action, and changelist number. (This command is equivalent to p4 files //...@labelname).

Listing labels that have been applied to files

To list all labels that have been applied to files, use the command:

p4 labels filepattern

Using a label to specify file revisions

You can use a label name anywhere you can refer to files by revision (#1, #head), changelist number (@7381), or date (@2011/07/01).

If you omit file arguments when you issue the p4 sync @labelname command, all files in the client 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 you specify file arguments when you issue the p4 sync command (p4 sync files@labelname), files that are in your workspace and tagged by the label are synced to the tagged revision.

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

To retrieve the files tagged by Earl's jam-2.1.0 label into his client workspace, Bruno issues the following command:

p4 sync @ jam-2.1.0

and sees: 

//depot/dev/main/jam/Build.com#5 - updating c:\bruno_ws\dev\main\jam\Build.com
//depot/dev/main/jam/command.c#5 - updating c:\bruno_ws\dev\main\jam\command.c
//depot/dev/main/jam/command.h#3 - added as c:\bruno_ws\dev\main\jam\command.h
//depot/dev/main/jam/compile.c#12 - updating c:\bruno_ws\dev\main\jam\compile.c
//depot/dev/main/jam/compile.h#2 - updating c:\bruno_ws\dev\main\jam\compile.h
<etc>

Deleting labels

To delete a label, use the following command:

p4 label -d labelname

Deleting a label has no effect on the tagged file revisions (though, of course, the revisions are no longer tagged).

Creating a label for future use

To create a label without tagging any file revisions, issue the p4 label labelname command. This command displays a form in which you describe and specify the label. After you have created a label, you can use p4 tag or p4 labelsync to apply the label to file revisions.

Label names cannot be the same as client workspace, branch, or depot names.

For example, to create jam-2.1.0, issue the following command:

p4 label jam-2.1.0

The following form is displayed: 

Label:    jam-2.1.0
Update:    2011/03/07 13:07:39
Access:    2011/03/07 13:13:35
Owner:    earl
Description:
     Created by earl.
Options:     unlocked noautoreload
View:
     //depot/...

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

After you create the label, you are able to use the p4 tag and p4 labelsync commands to apply the label to file revisions.

Restricting files that can be tagged

The View: field in the p4 label form limits the files that can be tagged with a label. The default label view includes the entire depot (//depot/...). To prevent yourself from inadvertently tagging every file in your depot, set the label's View: field to the files and directories to be taggable, using depot syntax.

Example 35. Using a label view to control which files can be tagged

Earl wants to tag the revisions of source code in the release 2.1 branch, which he knows can be successfully compiled. He types p4 label jam-2.1.0 and uses the label's View: field to restrict the scope of the label as follows: 

Label:    jam-2.1.0
Update:    2011/03/07 13:07:39
Access:    2011/03/07 13:13:35
Owner:    earl
Description:
     Created by earl.
Options:     unlocked noautoreload
View:
     //depot/release/jam/2.1/src/...

This label can tag only files in the release 2.1 source code directory.

Using static labels to archive workspace configurations

You can use static labels to archive the state of your client workspace (meaning the currently synced file revisions) by issuing the p4 labelsync command. The label you specify must have the same view as your client workspace.

For example, to record the configuration of your current client workspace using the existing ws_config label, use the following command:

p4 labelsync -l ws_config

All file revisions that are synced to your current workspace and visible through both the client workspace view and the label view (if any) are tagged with the ws_config label. Files that were previously tagged with ws_config, then subsequently removed from your workspace (p4 sync #none), are untagged.

To sync the files tagged by the ws_config label (thereby recreating the workspace configuration), issue the following command:

p4 sync @ws_config

Note

You can control how static labels are stored using the autoreload or noautoreload option:

  • autoreload stores the labels in the unload depot. This storage option can improve performance on sites that make heavy use of labels.

  • noautoreload stores the labels in the db.label table.

These storage options do not affect automatic labels.

Using automatic labels as aliases for changelists or other revisions

You can use automatic labels to specify files at certain revisions without having to issue the p4 labelsync command.

To create an automatic label, fill in the Revision: field of the p4 label form with a revision specifier. When you sync a workspace to an automatic label, the contents of the Revision: field are applied to every file in the View: field.

Example 36. Using an automatic label as an alias for a changelist number.

Earl is running a nightly build process, and has successfully built a product as of changelist 1234. Rather than having to remember the specific changelist for every night's build, he types p4 label nightly20111201 and uses the label's Revision: field to automatically tag all files as of changelist 1234 with the nightly20111201 label: 

Label:    nightly20111201
Owner:    earl
Description:
     Nightly build process.
Options:     unlocked noautoreload
View:
     //depot/...
Revision:
     @1234

The advantage to this approach is that it is highly amenable to scripting, takes up very little space in the label table, and provides a way to easily refer to a nightly build without remembering which changelist number was associated with the night's build process.

Example 37. Referring specifically to the set of files submitted in a single changelist.

A bug was fixed by means of changelist 1238, and requires a patch label that refers to only those files associated with the fix. Earl types p4 label patch20111201 and uses the label's Revision: field to automatically tag only those files submitted in changelist 1238 with the patch20111201 label: 

Label:    patch20111201
Owner:    earl
Description:
     Patch to 2011/12/01 nightly build.
Options:     unlocked noautoreload
View:
     //depot/...
Revision:
     @1238,1238

This automatic label refers only to those files submitted in changelist 1238.

Example 38. Referring to the first revision of every file over multiple changelists.

You can use revision specifiers other than changelist specifiers; in this example, Earl is referring to the first revision (#1) of every file in a branch. Depending on how the branch was populated, these files could have been created through multiple changelists over a long period of time: 

Label:    first2.2
Owner:    earl
Description:
     The first revision in the 2.2 branch
Options:     unlocked noautoreload
View:
     //depot/release/jam/2.2/src/...
Revision:
     "#1"

Because Perforce forms use the # character as a comment indicator, Earl has placed quotation marks around the # to ensure that it is parsed as a revision specifier.

Preventing inadvertent tagging and untagging of files

To tag the files that are in your client workspace and label view (if set) and untag all other files, issue the p4 labelsync command with no arguments. To prevent the inadvertent tagging and untagging of files, issue the p4 label labelname command and lock the label by setting the Options: field of the label form to locked. To prevent other users from unlocking the label, set the Owner: field. For details about Perforce privileges, refer to the Perforce Server Administrator's Guide: Fundamentals.

Using labels on edge servers

You can user Perforce Server in a distributed, multi-site environment using central and edge servers. With a distributed Perforce service architecture, users typically connect to an edge server and execute commands just as they would with a classic Perforce service. For more information, refer to Perforce Server Administrator's Guide: Multi-site Deployment.

When connected to an edge server, the commands p4 label, p4 labelsync, and p4 tag operate on labels local to the edge server. Global labels can be manipulated by using the -g option. For details, refer to the P4 Command Reference.

Note

Using the -g option with p4 labelsync only works with a global client. To manipulate a global label, use p4 tag.