p4 label

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]

Syntax conventions

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 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 can be a single user or a group.

Warning

A branch, depot, label, and workspace cannot 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

Advantage to this approach: facilitates scripting, does not use much space in label table, and provides a way to 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:
        ## comment line
        //depot/...  ## comment appended
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 Core 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	By default, the owner is the user who created the label. The specified owner does not have to be a Helix Core Server user. You might want to use an arbitrary name if the owner does not yet exist, or if you have deleted the owner and need a placeholder until you can assign the spec to a new owner.
`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. To learn more, see the topic that explains Views. Comments are preceded by `##` as shown in this example: View: ## comment line //depot/... ## comment appended
`ServerID:`	Writable, optional	If set, restricts usage of the label to the named server. If unset, this label can 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. The -g flag should be used on an Edge Server to update a global label. Note that in this case, the client should be a global client. Note Global labels can be updated from edge servers using either p4 tag -g or p4 labelsync -g
`-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`, but only the owner of a label can update which files are tagged with the label.

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.

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

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