Perforce 2002.1 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 user-determined list of files and revisions. The label can later be used to reproduce the state of these files within a client workspace.

Labels provide a method of naming important combinations of file revisions for later reference. For example, the file revisions that comprise a particular release of your software might be given the label release2.0.1. At a later time, you can retrieve all the files in that label into a client workspace with a single command.

Create a label when:

Why Not Just Use Changelist Numbers?


Labels share certain important characteristics with change numbers, as both refer to particular file sets, and both act as handles to refer to all the files in the set. But labels have some important advantages over change numbers:

Creating a Label


You can create a label with p4 label labelname. This command brings up a form similar to the p4 client form. Like clients, labels have associated views; the label view limits which files can be referenced by the label. Once you have created the label, use p4 labelsync to load the label with file references.

Label names share the same namespace as clients, branches, and depots. Thus, a label name cannot be the same as any existing client, branch, or depot name.

Before following this example further, it's worth stopping for a moment to examine exactly what has and hasn't been accomplished. So far, a label called filters.1 has been created. It can contain files only from the depot's elm_proj filter and hdrs subdirectories. But the label filters.1 is empty; it contains no file references. It will be loaded with its file references with p4 labelsync.

The View: field limits the files that are included in the label. These files must be specified by their location in the depot; this view differs from other views in that only the depot side of the view is specified.

The locked / unlocked option in the Options: field can prevent p4 labelsync from overwriting previously synced labels (this is described in "Preventing Accidental Overwrites of a Label's Contents" on page 88).

Adding and Changing Files Listed in a Label


Once you've created a label, you can include references to files within it by using p4 labelsync. This command's syntax is

The rules followed by labelsync to include files in a label are as follows:

  1. You must be the owner of the label in order 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:

      p4 label labelname
    and changing the Owner: field to your userid in the p4 label form. Similarly, you may unlock a label by setting the Options: field (also in the p4 label form) to unlocked.

  2. All files listed in a label must be contained in the label view specified in the p4 label form. Any files or directories that are not mapped through the label view are ignored by p4 labelsync. All the following rules assume this, without further mention.

  3. When p4 labelsync is used to include a particular file in a label's file list, the file is added to the label if it is not already included in the label. If a different revision of the file is already included in the label's file list, it is replaced with the newly specified revision. Only one revision of any file is ever included in a label's file list.

  4. If labelsync is called with no filename arguments, as in:

    then all the files mapped by the label view are listed in the label. The revisions added to the label are those last synced into the client; these revisions can be seen in the p4 have list. Calling p4 labelsync this way replaces all existing file references with the new ones.

  5. When you call p4 labelsync with file pattern arguments, and the arguments contain no revision specifications, the head revisions of these files are included in the label's file list.

  6. If you call p4 labelsync with file pattern arguments containing revision specifications, these file revisions are included in the label's file list.

Previewing labelsync's results

The results of p4 labelsync can be previewed with p4 labelsync -n. This lists the files that would be added, deleted, or replaced in the label without actually performing the operation.

Preventing Accidental Overwrites of a Label's Contents


Since p4 labelsync with no file arguments overwrites all the files that are listed in the label, 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.

Retrieving a Label's Contents into a Client Workspace


To retrieve all the files listed in a label into a client workspace, use p4 sync files@labelname. Rather than simply adding the files to the client workspace, this command matches the state of the client workspace to the state of the label. Thus, files in the client workspace that aren't in the label may be deleted from the client workspace.

If p4 sync @labelname is called with no file parameters, all files in the client that are not in the label will be deleted from the client. If this command is called with file arguments, as in p4 sync files@labelname, then the client workspace at the intersection of the depot, the client workspace view, and the file arguments will be updated to match the contents of the depot at that intersection.

Deleting Labels


You can delete a label with:

You can delete files from labels with:

To delete all the files from the label's file list, but leave the empty label in the Perforce database, use:

Label Reporting


The commands that provide reports on labels are:

Command
Description

p4 labels

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

p4 labels file#revrange

Report the names, dates, and descriptions of all labels that include the specified revision range of file.

p4 files @labelname

Lists all files and revisions contained in the given label.

p4 sync -n @labelname

Shows what p4 sync would do when retrieving files from a particular label into your client workspace, without actually performing the sync.


Perforce 2002.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-2002 Perforce Software. All rights reserved.
Last updated: 04/03/02