p4 label

Synopsis

Create or edit a label specification and its view.

Syntax

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.

Form Fields

Field Name Type Description

Label:

Read-only

The label name as provided in the invoking command.

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 Perforce 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 distributed 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 distributed 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.

    By default, labels are local to your edge server, and you use the -g option to access global labels on the commit server. If your administrator has set rpl.labels.global to 1, labels are global by default, and the meaning of the -g option is inverted to allow updating of local labels.

Examples

p4 files @labelname

List the file revisions tagged by labelname.

Related Commands

To tag revisions in your client workspace with a label

p4 labelsync

To list all labels known to the system

p4 labels

To create a label and tag files with the label

p4 tag