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:

• You want to keep track of all the file revisions contained in a particular release of the software,

• There exists a particular set of file revisions that you want to give to other users, or

• You have a set of file revisions that you want to branch from, but you don't want to perform the branch yet. In this case, you would create a label for the file revisions that will form the base of the branch.

Why Not Just Use Changelist Numbers?

• The file revisions referenced by a particular label can come from different changelists.

• A change number refers to the state of all the files in the depot at the time the changelist was submitted, while a label can refer to any arbitrary set of files and revisions.

• The files and revisions referenced by a label can be arbitrarily changed at any point in the label's existence.

• Changelists are always referred to by Perforce-assigned numbers, while labels are named by the user.

Creating a Label

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.

Example:  Creating a Label

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:  filters.1 Owner:  edk Description:         Created by edk. Options:        unlocked View:         //depot/elm_proj/filter/...         //depot/elm_proj/hdrs/...

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 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 94).

Adding and Changing Files Listed in a Label

p4 labelsync [-a -d -n] -l labelname [filename...]

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:
   p4 labelsync -l labelname

   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.

   Example:  Including file references in a label with p4 labelsync.
   Ed has created a label called filters.1 as specified above, and now he wants to load the filters.1 label with the proper file revisions. He types:
   p4 labelsync -l filters.1
   and sees the following:

   //depot/elm_proj/filter/Makefile.SH#20 - added //depot/elm_proj/filter/actions.c#25 - added <etc.>

   Perforce adds those file revisions to the label that are those contained in the intersection of the label view and the current client have list.

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.
   Example:  Changing file references in a label with p4 labelsync.
   After performing the above 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 filters.1 with the new revision. From the filter subdirectory, he types
   p4 labelsync -l filters.1 filter/filter.c
   and sees

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

6. If you call p4 labelsync with file pattern arguments containing revision specifications, these file revisions are included in the label's file list.
   Example:  Including a different file revision in a label
   Ed realizes that the version of filter/audit.c contained in his label filters.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 filters.1 filter/audit.c#12
   and sees:

   /depot/elm_proj/filter/audit.c#12 - updated

   This revision of audit.c replaces the revision that had been previously included in the label.

Previewing labelsync's results

Preventing Accidental Overwrites of a Label's Contents

Retrieving a Label's Contents into a Client Workspace

Example:  Retrieving files into a client workspace from a label.

Lisa wants to retrieve all the files listed in Ed's filters.1 label into her client workspace. She can type:

p4 sync //depot/[email protected]

or even:

p4 sync @filters.1

Instead, she's interested in seeing only the header files from that label, so she types:

p4 sync //depot/elm_proj/hdrs/*@filters.1

and sees:

//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 //depot/elm_proj/hdrs/test.h#3 - deleted as /usr/lisag/elm/hdrs/test.h <etc>

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 arguments will be updated to match the contents of the depot at that intersection.

Deleting Labels

p4 label -d labelname

p4 labelsync -d -l labelname filepattern

p4 labelsync -d -l labelname

Label Reporting