| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Chapter 8 Labels | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
A Perforce label is simply 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, all the files in that label can be retrieved into a client workspace with a single command.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Why Not Just Use Change Numbers? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Labels share certain important characteristics with change numbers: both refer to particular file sets, and both act as handles to refer to all the files in the set. But labels have four important advantages over change numbers:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Creating a Label | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Labels are created 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 the label has been created, the p4 labelsync command is used to load the label with file references.
Label names share the same namespace as clients, branches, and depots; thus, a label name can't be the same as any existing client, branch, or depot name. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Ed has finished the first version of filtering in elm; he wants to create a label that
references only those files in the filter and hdrs subdirectories. He wants to name the
label filters.1; he types p4 label filters.1 and fills in the resulting form as
follows:
When he quits from the editor, the label is created. 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 is used to limit 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 further in "Preventing Accidental Overwrites of a Label's Contents ").
| Adding and Changing Files Listed in a Label
Once a label has been created, references to files can be included in the label with the labelsync command. The syntax for labelsync is
| p4 labelsync [-a -d -n] -l labelname [filename...] The rules followed by labelsync to include files in a label are as follows:
|
The file revisions added to the label are those contained in the intersection of the label view and the current client have list.
|
p4 labelsync -l filters.1 doc/filter.c
The head revision of filter.c replaces the revision that had been previously included in the label.
|
p4 labelsync -l filters.1 filter/audit.c#12
This revision of audit.c replaces the revision that had been previously included in the label. Previewing Labelsync's ResultsThe 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 accidently 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. This command will match the state of the client workspace to the state of the label, rather than simply adding the files to the client workspace. Thus, files in the client workspace that aren't in the label may be deleted from the client workspace.
|
Lisa wants to retrieve all the files listed in Ed's filters.1 label into her client
workspace. She can type
| But she's interested in seeing only the header files from that label; she types p4 sync //depot/elm_proj/hdrs/*@filters.1
All the files in the subdirectory hdrs that are within the intersection of Ed's filters.1 label and Lisa's client view are retrieved into her workspace. But there is another effect as well: files that are not in the intersection of the label's contents and //depot/ elm_proj/hdrs/* are deleted from her 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 parameters will be updated to match the contents of the depot at that intersection.
| Deleting Labels
A label can be deleted in its entirety with
| Files can be deleted from labels with p4 labelsync -d -l labelname filepatterns This command deletes all the files from the label's file list, but leaves the empty label in the system.
| Label Reporting
The commands that provide reports on labels are: |
|
Please send comments and questions about this manual to
[email protected]. |
Copyright 1997, 1998 Perforce Software. All rights reserved. Last updated: 08/11/98 | |||||||||||||||||||||||||||||||||||||||