A Perforce label is simply a user-determined list of files and revisions. The label can later be used later to reproduce the state
of these files within a client workspace.release2.0.1. At a later time, all the files in that label can be retrieved into a client workspace with a single command.
p4 label labelname. The label 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:
Label: filter.1 |
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
filter.1 has been created. It can contain files only from the depot's elm_proj filter and hdrs subdirectories. But at this point, filter.1 is empty; it contains no file references. It will be loaded with its file references with p4 labelsync.The right sides of the view mappings are a bit curious; what exactly is happening here? The depot's files are being mapped to the label's namespace, which will never be seen by the user; if these mappings are done incorrectly, it can be destructive. The safest way to set up a label view is to simply duplicate each mapping's left side on the mapping's right side, replacing the
depot name with the name of the label. The above example demonstrates this safe way of setting the label view.
labelsync command. The syntax for labelsync is
p4 labelsync -l labelname [filerevisions]The rules followed by
labelsync to include files in a label are as follows:
p4 label form. Any files or directories that are not mapped through the label view are ignored by labelsync. All the following rules assume this, without further mention.
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.
labelsync is called with no filename arguments, as in
p4 labelsync -l labelnamethen all the files mapped by the label view will be listed in the label. The revisions added to the label will be those last gotten into the client; these revisions can be seen in the
p4 have list. If there are any file references already in the label, calling labelsync this way will replace all existing file references with the new ones.Ed has created a label called
filter.1 as specified above; now he wants to load the filter.1 label with the proper file revisions. He types
p4 labelsync -l filter.1and sees the following:
//depot/elm_proj/filter/Makefile.SH#20 - added |
The file revisions added to the label are those contained in the intersection of the label view and the current client
have list.
labelsync is called with filename arguments, and the arguments contain no revision specifications, the head revisions of these files are included in the label's file list.
labelsync command, Ed finds that the file filter/filter.c is buggy. He fixes it, submits the new version, and wants to replace the old revision of this file in the label filter.1 with the new revision. From the filter subdirectory, he types
p4 labelsync -l filter.1 doc/filter.c
//depot/elm_proj/filter/filter.c#15 - updated |
The head revision of
filter.c replaces the revision that had been previously included in the label.
labelsync is called with filename arguments that contain revision specifications, these file revisions are included in the label's file list.
filter/audit.c contained in his label filter.1 is not the version he wants to include in the label; he'd prefer to include revision 12 of that file. From the main Elm directory, he types
p4 labelsync -l filter.1 filter/audit.c#12
/depot/elm_proj/filter/audit.c#12 - updated |
This revision of
audit.c replaces the revision that had been previously included in the label.
labelsync with no filepattern arguments overwrites the file names listed in the label, it is possible to accidently and easily lose the information that a label is meant to contain. To prevent this, change the owner of a label to a non-existent username. Only the owner of a label can use labelsync on that label.
If Lisa wanted to retrieve all the files listed in Ed's filter.1 label, she could type
p4 get //depot/...@labelname
or even
p4 @labelname
p4 get //depot/hdrs/*@filter.1
//depot/elm_proj/hdrs/curses.h#1 - added as /usr/lisag/elm/hdrs/curses.h //depot/elm_proj/hdrs/defs.h#1 - added as /usr/lisag/elm/hdrs/defs.h <etc> |
All the files in the subdirectory
hdrs that have been included in Ed's filter.1 label have been retrieved into her workspace.
p4 label -d labelname
A variation of this isp4 labelsync -d -llabelnamefilepatterns
p4 labelsync -d -l labelname
Command |
Description |
p4 labels
| Report the names, dates, and descriptions of all labels known to the server |
p4 files @labelname
| Lists all files and revisions contained in the given label. |