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

Chapter 8
Labels

A Perforce label is a set of tagged file revisions. You can use labels to reproduce the state of these files within a client workspace.

Labels provide a method of naming important sets of file revisions for future reference. 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.

Create a label when you want to:

Why not just use 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 have some important advantages over change numbers:

Using labels

Labeling files is a two-step process.

  1. Create the label.

  2. Tag the file revisions with the label.

Creating a new label

Use p4 label labelname to create a label. This command brings up a form similar to the p4 client form.

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

After you have created the label, you can use p4 labelsync to tag files.

For instance, 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/...

(The View: field denotes a label view; this field can be used to limit which files can be tagged with the label. You do not normally need to change the View: field; the only thing you need to do is update the label's description.)

After you have created the label, you can use it to tag any revision of any file under Perforce control. Only one revision of a given file can be tagged with a given label, but the same file revision may be tagged with multiple labels. Files are tagged with labels using the p4 labelsync command.

Labeling all revisions in your workspace

To tag file revisions in your client workspace with a label, use p4 labelsync as follows:

All revisions in your client workspace are tagged with my_label, and any revisions previously tagged by my_label which are not present in your client workspace, are untagged.

Note

Anyone can use p4 labelsync with your label to tag or untag files.

To prevent others (or yourself) from inadvertently changing which files are tagged by a label, lock the label. See "Preventing inadvertent tagging and untagging of files" on page 93 for details.

Tagging specific files and revisions with p4 labelsync

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

For example, to tag all files in your client workspace that reside under //depot/proj/rel1.0/hdrs with the label my_label, use the following:

The revisions of files under //depot/proj/rel1.0/hdrs/.. that also reside in your client workspace are tagged with the name my_label.

(This operation can also be thought of as "adding" the label to the files; hence the use of the -a flag with p4 labelsync.)

Untagging files with p4 labelsync

You can untag revisions with:

If you omit the filepattern, an implicit //... is assumed; all files formerly tagged by the label are untagged.

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.

(Just as you can add a label to files with p4 labelsync -a, you can delete the label from files with p4 labelsync -d.)

Previewing labelsync's results

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

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 contain.

To prevent this, call p4 label labelname and set the value of the Options: field to locked. It will be impossible to call p4 labelsync on that label until the label is subsequently unlocked.

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)

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.

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

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 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:

Details: 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. You must be the owner of the label to use p4 labelsync on it, and the label must be unlocked. If you are not the owner of a label, you may (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 may unlock the label by setting the Options: field (also in the p4 label form) to 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 may 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 2003.2 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-2003 Perforce Software. All rights reserved.
Last updated: 12/12/03