| Perforce 2003.2 User's Guide | ||
|
<< Previous Chapter Changelists |
Table of Contents Index Perforce on the Web |
Next Chapter >> Branching |
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:
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:
p4 label my_label
The following form is displayed:
(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.
p4 labelsync -l my_label
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. |
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:
p4 labelsync -a -l my_label //depot/proj/rel1.0/hdrs/...
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.)
p4 labelsync -d -l labelname filepattern
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:
p4 labelsync -d -l my_label //depot/proj/rel1.0/hdrs/*.h
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.)
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.
p4 files @labelname
All revisions tagged with labelname are listed with their file type, change action, and changelist number. (This command is equivalent to p4 files //...@labelname)
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.
Ed is working in a large client workspace, and wishes to tag a recently built set of binaries in
this workspace with the label build1.0. He wants to ensure that he doesn't inadvertently
tag the rest of his workspace by calling p4 labelsync without specifying a file argument.
He types p4 label build1.0 and uses the label's View: field to restrict the scope of the
label as follows:
|
Label: build1.0 |
After he saves from the editor, a new empty label build1.0 is created. This label can tag only
files in the /rel1.0/bin directory.
With the default View: of //depot/..., he must type:
p4 labelsync -a //depot/proj/rel1.0/bin/... -l labelname
With the new View:, Ed can use p4 labelsync -l build1.0 to tag the desired files.
The locked / unlocked option in the Options: field can be used to prevent others from
inadvertently retagging files with p4 labelsync. See "Preventing inadvertent tagging and
untagging of files" on page 93).
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.
Lisa wants to retrieve some of the binaries tagged by Ed's build1.0 label into her client
workspace. To get all files tagged by build1.0, she could type:
p4 sync //depot/[email protected]
Instead, she's interested in seeing only one platform's build from that label, so she types:
p4 sync //depot/proj/rel1.0/bin/osx/*@build1.0
All files under //depot/proj/rel1.0/bin/osx that are tagged with Ed's build1.0 label
and are also in Lisa's client workspace view are retrieved into her workspace.
p4 labelsync [-a -d -n] -l labelname [filename...]
The rules followed by labelsync to tag files with a label are as follows:
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.
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.
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.
| Perforce 2003.2 User's Guide | ||
|
<< Previous Chapter Changelists |
Table of Contents Index Perforce on the Web |
Next Chapter >> Branching |