Perforce 2005.1 User's Guide
<< Previous Chapter
Changelists
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Branching

Chapter 8
Labels

Labels provide a method of naming important sets of file revisions for future reference. You can use labels to reproduce the state of a client workspace, to branch files, and to compare files. For example, you might want to tag the file revisions that compose a particular release with the label release2.0.1. At a later time, you can retrieve all the tagged revisions into a client workspace by syncing the workspace to the label.

Use a label when you want to:

Labels or changelist numbers?

Labels share certain important characteristics with changelist numbers, as both refer to particular sets of file revisions, and both can be used to refer to all the revisions in the set. Labels and changelists have some important distinctions:

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

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. New label names must be distinct from any existing client workspace, branch, or depot names.

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:

The head revisions of files under //depot/proj/rel1.0/hdrs/... are tagged with the name my_label.

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

Untagging files

You can untag revisions with:

This command removes the association between labelname and all files tagged by labelname, regardless of the revision specified in the 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:

Revisions of the *.h header files are no longer tagged with my_label.

Previewing tag's 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 by the tag command 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:

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 the labels that have been applied to any of the files in a filepattern, use the command:

Referring to files using a label

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

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.

Deleting labels

To delete a label, use the following command:

Deleting a label has no effect on the tagged files other than to remove the ability to refer to the files with the @labelname revision specifier.

Creating a label for future use

The p4 tag command both creates a label and applies it to files. To create a label without tagging any file revisions, use p4 label labelname. This command brings up a form similar to the p4 client form. After you have created a label, you can use p4 tag or p4 labelsync to apply the label to file revisions.

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:

The following form is displayed:

Label: my_label
Owner:  edk
Description:
        Created by edk.
Options:        unlocked
View:
        //depot/...

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

The View: field in the p4 label form limits the files that can be tagged with a label. To include files and directories in a label view, specify the files and directories to be included using depot syntax.

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.

Using labels to record workspace configurations

The p4 labelsync command is a variant of p4 tag that you can use to record a workspace configuration. For example, to record the configuration of your current client workspace using the pre-existing ws_config label, use the following command:

All file revisions synced to your current workspace are tagged with the ws_config label. Files previously tagged with ws_config are untagged unless they are also synced to your workspace.

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

Preventing inadvertent tagging and untagging of files

Using p4 labelsync with no file arguments tags the eligible files in your client workspace and any applicable label view, and untags all other files. This means that it is possible to accidentally lose the information that a label is meant to preserve.

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 differences between p4 tag and p4 labelsync are as follows:

How p4 tag works

The full syntax of the p4 tag command is:

The rules followed by p4 tag to tag files with a label are as follows:

  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:

    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

The full syntax of the p4 labelsync command is:

The rules followed by labelsync to tag files with a label are as follows:

  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:

    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.

The following table lists variations of p4 labelsync as typed on the command line, their implicit arguments as parsed by the Perforce Server, and the sets of files from which p4 labelsync selects the intersection for tagging.

Call p4 labelsync with
Implicit Arguments

-l label

(no files specified)

-l label //myworkspace/...#have

Tags every file in your client workspace at the revision currently in your client workspace.

-l label files

(files specified in local syntax, no revision specified)

-l label [cwd]/files#have

Tags only the files in your client workspace that you specify, at the revision currently in your client workspace.

-l label files#rev

(files specified in local syntax, specific revision requested)

-l label [cwd]/files#rev

Tags only the files in your client workspace that you specify, at the revision you specify.

Files must be in your client workspace view.

You can use numeric revision specifiers here, or #none to untag files, or #head to tag the latest revision of a file, even if you haven't synced that revision to your workspace.

-l label //files

(files specified in depot syntax, no revision specified)

-l label //files#have

Tags only the files in the depot that you specify, at the revision currently in your client workspace, whether the files are in your client workspace view or not.

-l label //files#rev

(files specified in depot syntax, specific revision requested)

-l label //files#rev

Tags only the files in the depot that you specify, at the revision at the revision you specify, whether the files are in your client workspace view or not.

Label Reporting

The commands that list information about labels are:

Command
Description

p4 labels

List the names, dates, and descriptions of all labels known to the server

p4 labels file#revrange

List the names, dates, and descriptions of all labels that tag the specified revision(s) of file.

p4 files @labelname

Lists all files and revisions tagged by labelname.

p4 sync -n @labelname

Lists the revisions tagged by the label that would be brought into your client workspace, (as well as files under Perforce control that would be deleted from your client workspace because they are not tagged by the label), without updating your client workspace.


Perforce 2005.1 User's Guide
<< Previous Chapter
Changelists
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Branching
Please send comments and questions about this manual to [email protected].
Copyright 1997-2005 Perforce Software. All rights reserved.
Last updated: 05/12/05