p4 label

Create or edit a label specification and its view.

Syntax conventions

p4 [g-opts] label [-f -g] [-t template] labelname
p4 [g-opts] label -d [-f -g] labelname
p4 [g-opts] label -o [-t template] labelname
p4 [g-opts] label -i [-f -g]

Description

Use p4 label to create a new label specification or edit an existing label specification. A labelname is required.

Running p4 label allows you to configure the mapping that controls the set of files that are allowed to be included in the label. After configuring the label, use p4 labelsync or p4 tag to tag files with the label.

Labels can be either automatic or static. Automatic labels refer to the revisions provided in the View: and Revision: fields. Static labels refer only to those specific revisions tagged by the label by means of either the p4 labelsync or p4 tag commands.

Only the Owner: of an unlocked label can use p4 labelsync or p4 tag to tag files with that label. The owner of a group may be a single user or a group.

Warning

A branch, depot, label, and workspace may not share the same name.

Automatic labels

Automatic labels refer to the revisions provided in the View: and Revision: fields of the label specification. To create an automatic label, fill in the Revision: field of the p4 label spec with a revision specifier. When you sync a workspace to an automatic label, the contents of the Revision: field are applied to every file in the View: field.

Example   Using an automatic label as an alias for a changelist number

Bruno is running a nightly build process, and has successfully built a product as of changelist 1234. Rather than having to remember the specific changelist for every night’s build, he types p4 label nightly20111201 and uses the label’s Revision: field to automatically tag all files as of changelist 1234 with the nightly20111201 label:

Label:  nightly20111201
Owner:  bruno
Description:
        Nightly build process.
Options:     unlocked noautoreload
View:
        //depot/...
Revision:
        @1234

The advantage to this approach is that it is highly amenable to scripting, takes up very little space in the label table, and provides a way to easily refer to a nightly build without remembering which changelist number was associated with the night’s build process.

Example   Referring specifically to the set of files submitted in a single changelist

A bug was fixed by means of changelist 1238, and requires a patch label that refers to only those files associated with the fix. Bruno types p4 label patch20111201 and uses the label’s Revision: field to automatically tag only those files submitted in changelist 1238 with the patch20111201 label:

Label:  patch20111201
Owner:  bruno
Description:
        Patch to 2011/12/01 nightly build.
Options:     unlocked noautoreload
View:
        //depot/...
Revision:
        @1238,1238

This automatic label refers only to those files submitted in changelist 1238.

Example   Referring to the first revision of every file over multiple changelists

You can use revision specifiers other than changelist specifiers. In this example, Bruno specifies to the first revision (#1) of every file in a branch. Depending on how the branch was populated, these files could have been created through multiple changelists over a long period of time:

Label:  first2.2
Owner:  bruno
Description:
        The first revision in the 2.2 branch
Options:     unlocked noautoreload
View:
        //JamCode/release/jam/2.2/src/...
Revision:
        "#1"

Because Helix server forms use the # character as a comment indicator, Bruno has placed quotation marks around the # to ensure that it is parsed as a revision specifier.

Form Fields

Field Name Type Description

Label:

Read-only

The label name as provided in the invoking command.

Be aware of the Limitations on characters in filenames and entities.

Owner:

Writable, optional

The label’s owner. By default, the user who created the label. Only the owner of a label can update which files are tagged with the label.

The specified owner does not have to be a Helix server user. You might want to use an arbitrary name if the user does not yet exist, or if you have deleted the user and need a placeholder until you can assign the spec to a new user.

Update:

Read-only

The date the label specification was last modified.

Access:

Read-only

The date and time the label was last accessed, either by running p4 labelsync on the label, or by otherwise referring to a file with the label revision specifier @label. (Note: Reloading a label with p4 reload does not affect the access time.)

Description:

Writable, optional

An optional description of the label’s purpose.

Options:

Writable

Options to control behavior and storage location of labels

  • locked or unlocked. If the label is locked, the list of files tagged with the label cannot be changed with p4 labelsync.
  • autoreload or noautoreload. For static labels, if noautoreload is set, the label is stored in db.label, and if autoreload is set, it is stored in the unload depot. This option is ignored for automatic labels. Storing labels in the unload depot can improve performance on sites that make extremely heavy use of labels.

Revision:

Writable

An optional revision specification for an automatic label.

If you use the # character to specify a revision number, you must use quotes around it in order to ensure that the # is parsed as a revision specifier, and not as a comment field in the form.

View:

Writable

A list of depot files that can be tagged with this label. No files are actually tagged until p4 labelsync is invoked.

Unlike client views or branch views, which map one set of files to another, label views consist of a simple list of depot files. See Views for more information.

ServerID:

Writable, optional

If set, restricts usage of the label to the named server. If unset, this label may be used on any server.

Options

-d [-f]

Delete the named label if it’s unlocked. The -f option forces the deletion even if the label is locked. (Deleting a locked label requires admin or super access.)

-f

Allow the Update: field’s date to be set. Can be used with either the -i option or the -t option for the same purpose.

-g

In multi-server environments, use the -g option to control whether the label is local to an edge server, or globally available from the commit server.

-i

Read the label definition from standard input without invoking the editor.

-o

Write the label definition to standard output without invoking the editor.

-t template

Copy label template's view and options into the View: and Options: fields of this label. You can specify a default label template using the template.label configure variable. If you do so, you do not have to specify this option.

g-opts

See Global options.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

N/A

N/A

open

  • To create an automatic label, fill in the Revision: field of the p4 label form with a revision specifier. When you sync a workspace to an automatic label, the contents of the Revision: field are applied to every file in the View: field.
  • With a multi-server Perforce service, labels may be local or global. Local labels are restricted to a single edge server, and cannot be used on other servers. Global labels are created and updated on the commit server, and are visible to all servers. However, global labels may only be used with global (unbound) client workspaces.

    Local Label

    Global Label

    rpl.labels.global is unset, which is 0 rpl.labels.global set to 1
    by default, labels are local to your edge server by default, labels are global
    -g option provides access to global labels on the commit server

    -g option allows the updating of local labels

    If a label exists on an edge server before rpl.labels.global is set, and you want that label to be available on both the edge server and the commit server, unloaded the label from the edge server and reload it on the commit server

Examples

p4 files @labelname

List the file revisions tagged by labelname.

Related Commands

To synchronize a label with the client workspace.

p4 labelsync

To list all labels known to the system

p4 labels

To create a label and tag files with the label

p4 tag