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
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/[email protected]
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.
You can untag revisions with:
p4 tag -d -l
This command removes the association between the specified label and the
file revisions tagged by it. For example, if you have tagged all revisions
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
use p4 files, specifying the label name as follows:
p4 files @
All revisions tagged with
labelname are listed,
with their file type, change action, and changelist number. (This command
is equivalent to p4 files
Listing labels that have been applied to files
To list all labels that have been applied to files, use the command:
Using a label to specify file revisions
You can use a label name anywhere you can refer to files by revision
#head), changelist number
@7381), or date (
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
If you specify file arguments when you issue the p4
sync command (p4 sync
files that are in your workspace and tagged by the label are synced to the
Example 34. Retrieving files tagged by a label into a client workspace
To retrieve the files tagged by Earl's
label into his client workspace, Bruno issues the following command:
p4 sync @ jam-2.1.0
//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>
To delete a label, use the following command:
p4 label -d
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
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
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
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
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
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
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
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
To sync the files tagged by the
(thereby recreating the workspace configuration), issue the following
p4 sync @ws_config
You can control how static labels are stored using the
autoreloadstores the labels in the unload depot. This storage option can improve performance on sites that make heavy use of labels.
noautoreloadstores the labels in the
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
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
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
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
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
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
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
-g option with p4
labelsync only works with a global client. To manipulate a
global label, use p4 tag.